Usage 1: A script to transform an antomical dataset to align with
some standard space template.
@auto_tlrc [options] <-base template> <-input anat>
Mandatory parameters:
-base template : Reference anatomical volume
Usually this volume is in some standard space like
TLRC or MNI space and with afni dataset view of
(+tlrc).
Preferably, this reference volume should have had
the skull removed but that is not mandatory.
AFNI's distribution contains several templates.
For a longer list, use "whereami_afni -show_templates"
TT_N27+tlrc --> Single subject, skull stripped volume.
This volume is also known as
N27_SurfVol_NoSkull+tlrc elsewhere in
AFNI and SUMA land.
(www.loni.ucla.edu, www.bic.mni.mcgill.ca)
This template has a full set of FreeSurfer
(surfer.nmr.mgh.harvard.edu)
surface models that can be used in SUMA.
For details, see Talairach-related link:
https://afni.nimh.nih.gov/afni/suma
TT_icbm452+tlrc --> Average volume of 452 normal brains.
Skull Stripped. (www.loni.ucla.edu)
TT_avg152T1+tlrc --> Average volume of 152 normal brains.
Skull Stripped.(www.bic.mni.mcgill.ca)
TT_EPI+tlrc --> EPI template from spm2, masked as TT_avg152T1
TT_avg152 and TT_EPI volume sources are from
SPM's distribution. (www.fil.ion.ucl.ac.uk/spm/)
If you do not specify a path for the template, the script
will attempt to locate the template AFNI's binaries directory.
NOTE: These datasets have been slightly modified from
their original size to match the standard TLRC
dimensions (Jean Talairach and Pierre Tournoux
Co-Planar Stereotaxic Atlas of the Human Brain
Thieme Medical Publishers, New York, 1988).
That was done for internal consistency in AFNI.
You may use the original form of these
volumes if you choose but your TLRC coordinates
will not be consistent with AFNI's TLRC database
(San Antonio Talairach Daemon database), for example.
-input anat : Original anatomical volume (+orig).
The skull is removed by this script
unless instructed otherwise (-no_ss).
Optional parameters:
-no_ss : Do not strip skull of input data set
(because skull has already been removed
or because template still has the skull)
NOTE: The -no_ss option is not all that optional.
Here is a table of when you should and should not use -no_ss
Template Template
WITH skull WITHOUT skull
Dset.
WITH skull -no_ss xxx
WITHOUT skull No Cigar -no_ss
Template means: Your template of choice
Dset. means: Your anatomical dataset
-no_ss means: Skull stripping should not be attempted on Dset
xxx means: Don't put anything, the script will strip Dset
No Cigar mean: Don't try that combination, it makes no sense.
-warp_orig_vol: Produce a TLRC version of the input volume, rather
than a TLRC version of the skull-stripped input.
This option is useful if you want the skull to be
preserved in the +tlrc output.
The default is to produce the skull-stripped version
of the input in +tlrc space.
-dxyz MM : Cubic voxel size of output DSET in TLRC
space. Default is the resolution of the
template. If you do not want your output
voxels to be cubic, then use the
-dx, -dy, -dz options below.
-dx MX : Size of voxel in the x direction
(Right-Left). Default is 1mm.
-dy MY : Size of voxel in the y direction
(Anterior-Posterior). Default is 1mm.
-dz MZ : Size of voxel in the z direction.
(Inferior-Superior). Default is 1mm.
-pad_base MM : Pad the base dset by MM mm in each directions.
That is needed to make sure that datasets
requiring wild rotations do not get cropped.
Default is MM = 15.
If your output dataset is clipped, try increasing
MM to 25.000000 or
35.000000.
If that does not help, make sure
that the skull-stripped volume has no clipping.
If it does, then the skull stripping needs to
be corrected. Feel free to report such instances
to the script's authors.
-keep_tmp : Keep temporary files.
-clean : Clean all temp files, likely left from -keep_tmp
option then exit.
-xform XFORM : Transform to use for warping:
Choose from affine_general or shift_rotate_scale
Default is affine_general but the script will
automatically try to use shift_rotate_scale
if the alignment does not converge.
-no_avoid_eyes : An option that gets passed to 3dSkullStrip.
Use it when parts of the frontal lobes get clipped
See 3dSkullStrip -help for more details.
-ncr : 3dWarpDrive option -coarserot is now a default.
It will cause no harm, only good shall come of it.
-ncr is there however, should you choose NOT TO
want coarserot used for some reason
-onepass : Turns off -twopass option for 3dWarpDrive. This will
speed up the registration but it might fail if the
datasets are far apart.
-twopass : Opposite of -onepass, default.
-maxite NITER : Maximum number of iterations for 3dWarpDrive.
Note that the script will try to increase the
number of iterations if needed.
When the maximum number of iterations is reached
without meeting the convergence criteria,
the script will double the number of iterations
and try again. If the second pass still fails,
the script will continue unless the user specifies the
-not_OK_maxite option.
The default number of iterations is 50 for first
pass and then doubled to 100 in second pass.
To reset to former default, set maxite to 0
-not_OK_maxite : See -maxite option.
-inweight : Apply -weight INPUT (in 3dWarpDrive).
By default, 3dWarpDrive uses the BASE dataset to
weight the alignment cost. Use this option to
weight via the INPUT dataset, instead.
This might be useful for partial coverage cases.
-rigid_equiv : Also output a the rigid-body version of the
alignment. This would align the brain with
TLRC axis without any distortion. Note that
the resultant .Xrigid volume is NOT in TLRC
space. Do not use this option if you do not
know what to do with it!
For more information on how the rigid-body
equivalent transformation is obtained, see
cat_matvec -help 's output for the -P option.
-init_xform XFORM0.1D: Apply affine transform in XFORM0.1D before
beginning registration and then include XFORM0.1D
in the final xform.
To verify that XFORM0.1D does what you think
it should be doing, try:
3dWarp -matvec_out2in XFORM0.1D \
-prefix pre.anat anat+orig
and verify that 'pre.anat+orig' is
transformed by XFORM0.1D as you expected it to be.
XFORM0.1D can be obtained in a variety of ways.
One of which involves extracting it from a transformed
volume.
For example, say you want to perform an initial
rotation that is equivalent to:
3drotate -matvec_order RotMat.1D \
-prefix struct.r struct+orig
The equivalent XFORM0.1D is obtained with:
cat_matvec 'struct.r+orig::ROTATE_MATVEC_000000' -I \
> XFORM0.1D
See cat_matvec -help for more details on extracting
appropriate affine transforms from dataset headers.
Note: You can also use -init_xform AUTO_CENTER to automatically
run @Align_Centers if the centers are off by more than
40 mm.
AUTO_CENTER_CM would do the centering based on the
center of mass rather than the center of the volume grids.
You can force centering with -init_xform CENTER
or with -init_xform CENTER_CM regardless of the center
distance between volumes
-no_pre: Delete temporary dataset created by -init_xform
-out_space spacename: Set output to a particular space
Usually, output space is determined by the space
of the input template and does not need to be set
explicitly here
-3dAllineate: Use 3dAllineate with the lpa+ZZ cost function
instead of 3dWarpDrive
-3dAlcost costfunction : use another cost function, like nmi,
for instance
-overwrite: Overwrite existing output.
With this option, 3dSkullstrip will get rerun even
if skull stripped volume is found on disk, unless of
course you use the -no_ss option.
This option has not been fully tested under the myriad
combinations possible. So check closely the first
time you use it, if use it you must
Note on the subject of transforms:
The script will output the final transform in a 1D file with the
extension Xat.1D, say THAT_NAME.1D
Call this transform Mt and let Xt and Xo be the 4x1 column vectors
coordinates of the same voxel in standard (t) and original (o)
space, respectively. The transform is such that Xo = Mt Xt
You can use this transform to manually warp a volume in orig
space to the standard space with:
3dWarp -matvec_out2in THAT_NAME.Xat.1D -prefix PPP SOME_VOL+orig.
3drefit -view +tlrc PPP+orig
Example:
@auto_tlrc -base TT_N27+tlrc. -input SubjectHighRes+orig.
(the output is named SubjectHighRes+TLRC, by default.
See -suffix for more info.)
Usage 2: A script to transform any dataset by the same TLRC
transform obtained with @auto_tlrc in Usage 1 mode
Note: You can now also use adwarp instead.
@auto_tlrc [options] <-apar TLRC_parent> <-input DSET>
Mandatory parameters:
-apar TLRC_parent : An anatomical dataset in tlrc space
created using Usage 1 of @auto_tlrc
From the example for usage 1, TLRC_parent
would be: SubjectHighRes+TLRC
-input DSET : Dataset (typically EPI time series or
statistical dataset) to transform to
tlrc space per the xform in TLRC_parent
-dxyz MM : Cubic voxel size of output DSET in TLRC
space Default MM is 1. If you do not
want your output voxels to be cubic
Then use the -dx, -dy, -dz options below.
-dx MX : Size of voxel in the x direction
(Right-Left). Default is 1mm.
-dy MY : Size of voxel in the y direction
(Anterior-Posterior). Default is 1mm.
-dz MZ : Size of voxel in the z direction.
(Inferior-Superior).Default is 1mm.
Optional parameters:
-pad_input MM : Pad the input DSET by MM mm in each direction.
That is needed to make sure that datasets
requiring wild rotations do not get cropped.
Default is MM = 15.
If your output dataset is clipped, try increasing
MM to 25.000000 or
35.000000.
If that does not help, report the
problem to the script's authors.
-onewarp : Create follower data (-apar use) with one interpolation
step, instead of two. - Now default
This option reduces blurring of the output data.
-twowarp : Create follower data (-apar use) with two interpolations
step, instead of one.
This option is for backward compatibility.
Example:
@auto_tlrc -apar SubjectHighRes+tlrc. \
-input Subject_EPI+orig. -dxyz 3
(the output is named Subject_EPI_at+TLRC, by default.
Common Optional parameters:
-rmode MODE: Resampling mode. Choose from:
linear, cubic, NN or quintic .
Default for 'Usage 1' is cubic.
Default for 'Usage 2' is cubic for 3dWarp,
followed by Bk for the 3dresample step.
-prefix prefix: Name output dataset
(xxx -> xxx+tlrc, yyy.nii.gz, zzz.nii)
-suffix SUF : Name the output dataset by append SUF
to the prefix of the input data for the output.
Default for SUF is NONE (see below)
NOTE: You can now set SUF to 'none' or 'NONE' and enable
afni's warp on demand features.
With NIFTI input volumes -suffix defaults to _at
-keep_view : Do not mark output dataset as +tlrc
-base_copy COPY_PREFIX: Copy base (template) dataset into COPY_PREFIX.
You can use ./ for COPY_PREFIX if you
want the copy to have the same name as the
template.
-base_list : List the full path of the base dataset
-use_gz : When using '-suffix ..', behave as if you had
provided a prefix with '*.gz' at the end.
Useful if your '-suffix'-specified output will
be NIFTI, and you want it zipped
-verb : Yakiti yak yak
When you're down and troubled and you need a helping hand:
1- Oh my God! The brain is horribly distorted (by Jason Stein):
The probable cause is a failure of 3dWarpDrive to converge.
In that case, rerun the script with the option
-xform shift_rotate_scale. That usually takes care of it.
Update:
The script now has a mechanism for detecting cases
where convergence is not reached and it will automatically
change -xform to fix the problem. So you should see very
few such cases. If you do, check the skull stripping
step for major errors and if none are found send the
authors a copy of the command you used, the input and base
data and they'll look into it.
2- Parts of the frontal cortex are clipped in the output:
That is likely caused by aggressive skull stripping.
When that happens, use the -no_avoid_eyes option.
3- Other parts of the brain are missing:
Examine the skull stripped version of the brain
If the source of the problem is with the stripping,
then you'll need to run 3dSkullStrip manually and
select the proper options for that dataset.
Once you have a satisfactorily stripped brain, use that
version as input to @auto_tlrc along with the -no_ss option.
4- Skull stripped dataset looks OK, but TLRC output is clipped.
Increase the padding from the default value by little more
than the size of the clipping observed. (see -pad_*
options above)
5- The high-res anatomical ends up at a lower resolution:
That is because your template is at a lower resolution.
To preserve (or control) the resolution of your input,
run @auto_tlrc in usage 2 mode and set the resolution
of the output with the -d* options.
6- I want the skulled anatomical, not just the stripped
anatomical in TLRC space:
Use @auto_tlrc in usage 2 mode.
7- What if I want to warp EPI data directly into TLRC space?
If you have an EPI template in TLRC space you can use it
as the base in @auto_tlrc, usage 1 mode. You can use whatever
you want as a template. Just make sure you are warping
apples to oranges, not apples to bananas for example.
8- Bad alignment still:
Check that the center of your input data set is not too
far off from that of the template. Centers (not origins)
of the templates we have are close to 0, 0, 0. If your
input dataset is 100s of mm off center then the alignment
will fail.
The easiest way around this is to add -init_xform AUTO_CENTER
to your command. If that still fails you can try to manually
shift all of the input data in your session by an equal amount
to get the centers closer to zero.
For example, say the center of your subject's volumes
is around 100, 100, 100. To shift the centers close to 0, 0, 0 do:
3drefit -dxorigin -100 -dyorigin -100 -dzorigin -100 Data+orig
Then use @auto_tlrc on the shifted datasets.
Take care not to shift datasets from the same session by differing
amounts as they will no longer be in alignment.
Global Help Options:
--------------------
-h_web: Open webpage with help for this program
-hweb: Same as -h_web
-h_view: Open -help output in a GUI editor
-hview: Same as -hview
-all_opts: List all of the options for this script
-h_find WORD: Search for lines containing WORD in -help
output. Seach is approximate.
Written by Ziad S. Saad (saadz@mail.nih.gov)
SSCC/NIMH/NIH/DHHS
