AFNI program: @SUMA_AlignToExperiment
Output of -help
@SUMA_AlignToExperiment <-exp_anat Experiment_Anatomy> <-surf_anat Surface_Anatomy>
[dxyz] [-wd] [-prefix PREFIX] [-EA_clip_below CLP]
[-align_centers] [-ok_change_view] [-strip_skull WHICH]
Creates a version of Surface Anatomy that is registered to Experiment Anatomy.
<-exp_anat Experiment_Anatomy>: Name of high resolution anatomical data set in register
with experimental data.
<-surf_anat Surface_Anatomy> Path and Name of high resolution antomical data set used to
create the surface.
NOTE: In the old usage, there were no -exp_anat and -surf_anat flags and the two
volumes had to appear first on the command line and in the proper order.
[-dxyz DXYZ]: This optional parameter indicates that the anatomical
volumes must be downsampled to dxyz mm voxel resolution before
registration. That is only necessary if 3dvolreg runs out of memory.
You MUST have 3dvolreg that comes with afni distributions newer than
version 2.45l. It contains an option for reducing memory usage and
thus allow the registration of large data sets.
[-out_dxyz DXYZ]: Output the final aligned volume at a cubic voxelsize
of DXYZmm. The default is based on the grid of ExpVol.
[-wd]: Use 3dWarpDrive's general affine transform (12 param) instead of
3dvolreg's 6 parameters.
If the anatomical coverage differs markedly between 'Experiment
Anatomy' and 'Surface Anatomy', you might need to use -EA_clip_below
option or you could end up with a very distorted brain.
The default now is to use -coarserot option with 3dWarpDrive, this
should make the program more robust. If you want to try running without it
the add -ncr with -wd
I would be interested in examining cases where -wd option failed to
produce a good alignment.
[-al]: Use 3dAllineate to do the 12 parameter alignment. Cost function
[-al_opt 'Options for 3dAllineate']: Specify set of options between quotes
to pass to 3dAllineate.
[-ok_change_view]: Be quiet when view of registered volume is changed
to match that of the Experiment_Anatomy, even when
rigid body registration is used.
[-strip_skull WHICH]: Use 3dSkullStrip to remove non-brain tissue and
potentially improve the alignment. WHICH can be
one of 'exp_anat', 'surf_anat', 'both', or 'neither' (default).
In the first case, the skull is removed from Experiment_Anatomy
dataset, in the second it is removed from the surf_anat dataset.
With 'both' the skull is removed from Experiment_Anatomy
[-skull_strip_opt 'Options For 3dSkullStrip']: Pass the options between
quotes to 3dSkullStrip.
[-align_centers]: Adds an additional transformation to align the volume
centers. This is a good option to use when volumes
are severely out of alignment.
[-init_xform XFORM0.1D]: Apply affine transform in XFORM0.1D to
Surface_Anatomy before beginning registration.
After convergence, combine XFORM.1D and the
the registration matrix to create the output volume
To verify that XFORM0.1D does what you think
it should be doing, try:
3dWarp -matvec_out2in XFORM0.1D \
-prefix pre.SurfVol SurfVol+orig
and verify that 'pre.SurfVol+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
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 \
See cat_matvec -help for more details on extracting
appropriate affine transforms from dataset headers.
See also Example 4 below.
[-EA_clip_below CLP]: Set slices below CLPmm in 'Experiment Anatomy' to zero.
Use this if the coverage of 'Experiment Anatomy' dataset
extends far below the data in 'Surface Anatomy' dataset.
To get the value of CLP, use AFNI to locate the slice
below which you want to clip and set CLP to the z coordinate
from AFNI's top left corner. Coordinate must be in RAI, DICOM.
[-prefix PREFIX]: Use PREFIX for the output volume. Default is the prefix
[-surf_anat_followers Fdset1 Fdset2 ...]: Apply the same alignment
transform to datasets Fdset1, Fdset2, etc.
This must be the last option on the command line.
All parameters following it are considered datasets.
You can transform other follower dsets manually by
3dAllineate -master Experiment_Anatomy \
-1Dmatrix_apply Surface_Anatomy_Alnd_Exp.A2E.1D \
-input Fdset \
-prefix Fdset_Alnd_Exp+orig \
[-followers_interp KERNEL]: Set the interpolation mode for the
follower datasets. Default is NN, which
is appropriate for ROI datasets.
Allowed KERNEL values are:
NN, linear, cubic, or quintic
Note: For atlas datasets, the KERNEL is forced to NN
regardless of what you set here.
of the 'Surface Anatomy' suffixed by _Alnd_Exp.
[-atlas_followers]: Automatically set the followers to be atlases in
the directory of -surf_anat. This way all the
parcellations will get aligned to the experiment.
[-keep_tmp]: Keep temporary files for debugging. Note that you should
delete temporary files before rerunning the script.
[-overwrite_resp RESP]: Answer 'overwrite' questions automatically.
RESP (response) should be one of O/S/Q/A:
O : overwrite previous result
S : skip this step (applying previous result)
Q : quit the script
A : pause script and ask at each occurance
NOTE: You must run the script from the directory where Experiment Anatomy resides.
Example 1: For datasets with no relative distortion and comparable coverage.
Using 6 param. rigid body transform.
@SUMA_AlignToExperiment -exp_anat DemoSubj_spgrsa+orig. \
Example 2: For datasets with some distortion and different coverage.
Using 12 param. transform and clipping of areas below cerebellum:
@SUMA_AlignToExperiment -exp_anat ABanat+orig. -surf_anat DemoSubj_SurfVol+orig. \
-wd -prefix DemoSubj_SurfVol_WD_Alnd_Exp \
Example 3: For two monkey T1 volumes with very different resolutions and severe
@SUMA_AlignToExperiment -surf_anat MOanat+orig. -al \
-exp_anat MoExpanat+orig. \
-strip_skull both -skull_strip_opt -monkey \
Example 4: When -exp_anat and -surf_anat have very different orientations
Here is an egregious case where -exp_anat (EA) was rotated severely
out of whack relative to -surf_anat (SV), AND volume centers were
With the 'Nudge Dataset' plugin, it was determined that a 60deg.
rotation got SV oriented more like ExpAnat.
The plugin can be made to spit out an the 3dRotate command
to apply the roation:
3drotate -quintic -clipit -rotate 0.00I 60.00R 0.00A \
-ashift 0.00S 0.00L 0.00P \
-prefix ./SV_rotated+orig SV+orig
We will get XFROM.1D from that rotated volume:
cat_matvec 'SV_rotated+orig::ROTATE_MATVEC_000000' -I \
and tell @SUMA_AlignToExperiment to apply both center alignment
-init_xform XFORM0.1D -align_centers \
-surf_anat SV+orig -exp_anat EA+orig \
Note 1: 'Nudge Dataset' can also be used to get the centers
aligned, but that would be more buttons to press.
Note 2: -init_xform does not need to be accurate, it is just
meant to get -surf_anat to have a comparable orientation.
Global Help Options:
-h_view: Open -help output in a GUI editor
-all_opts: List all of the options for this script
-h_find WORD: Search for lines containing WORD in -help
output. Seach is approximate.
More help may be found at http://afni.nimh.nih.gov/ssc/ziad/SUMA/SUMA_doc.htm
Ziad Saad (firstname.lastname@example.org)
SSCC/NIMH/ National Institutes of Health, Bethesda Maryland
This page auto-generated on
Thu May 23 09:55:01 EDT 2013