align_warp


Purpose:

This is a nonlinear registration tool that can be used within or across subjects and includes implementation of 2D and 3D nonlinear spatial transformation models.

The program will generate a .warp file that can be used to reslice the specified reslice data set to match the specified standard data set.


Usage:

align_warp standard-file reslice-file .warp-out -m model-menu-number [final-model-menu-number ] [options]

Model Menu:

3-D models:
1. first order linear 12 parameter model
2. second order nonlinear 30 parameter model
3. third order nonlinear 60 parameter model
4. fourth order nonlinear 105 parameter model
5. fifth order nonlinear 168 parameter model
6. sixth order nonlinear 252 parameter model
7. seventh order nonlinear 360 parameter model
8. eighth order nonlinear 495 parameter model
9. ninth order nonlinear 660 parameter model
10. tenth order nonlinear 858 parameter model
11. eleventh order nonlinear 1092 parameter model
12. twelfth order nonlinear 1365 parameter model
2-D models:
21. first order linear 6 parameter model
22. second order nonlinear 12 parameter model
23. third order nonlinear 20 parameter model
24. fourth order nonlinear 30 parameter model
25. fifth order nonlinear 42 parameter model
26. sixth order nonlinear 56 parameter model
27. seventh order nonlinear 72 parameter model
28. eighth order nonlinear 90 parameter model
29. ninth order nonlinear 110 parameter model
30. tenth order nonlinear 132 parameter model
31. eleventh order nonlinear 156 parameter model
32. twelfth order nonlinear 182 parameter model

options:

[-b1 FWHM-x FWHM-y FWHM-z]
smooths standard-file
[-b2 FWHM-x FWHM-y FWHM-z]
smooths reslice-file
[-c convergence-threshold]
changes default convergence threshold
[-e1 mask]
masks standard-file
[-e2 mask]
masks reslice-file
[-f initialization-warp-file]
changes default spatial initialization
[-fs scaling-initialization-file]
changes default intensity initialization
[-g ...]AIR 5.0
deprecated and no longer supported, unneeded since .air and .warp files can be used directly for initializations
[-gs scaling-termination-file [overwrite?(y/n)]
saves final intensity scaling parameter
[-h halt-after-(N)-iterations-without-improvement]
changes default iterations without improvement
[-i]
enables saving (with overwrite permission) of intermediate .warp files for each incremental model
[-j]
uses currently unvalidated method for overcoming non-positive definite Hessian matrices
[-l lesion-file] AIR 5.2
excludes specified regions in reslice-file when computing cost function
[-q]
assumes non-interaction of spatial parameter derivatives (reduces likelihood of non-positive definite Hessian matrices)
[-r repeated-iterations]
changes default repeated interations
[-s initial-sampling final-sampling sampling-decrement-ratio]
changes default sampling
[-t1 threshold]
changes default threshold for standard-file
[-t2 threshold]
changes default threshold for reslice-file
[-v]
enables verbose reporting of interim results
where the following definitions apply:
convergence-threshold [-c]
controls how small the predicted change in the cost function must be in order to meet the convergence criteria. Setting this value too large will result in convergence while the images are still misregistered; setting it too small may lead to a failure to converge.
final-model-menu-number [flagless option]
Models are incremented sequentially from the model-menu-number to this the model from the model menu that corresponds to this value. If the algorithm fails to improve the parameters at a given polynomial order,this final value will not be reached.
final-sampling [-s ...]
controls how densely data is sampled during the final iterative cycle of the algorithm. If your data is oversampled, the time spent sampling very densely may not provide any significant improvement in accuracy. Unlike alignlinear, the default here is to end with sparse sampling at every ninth voxel. Iterations will cease if the new sampling density is less than the final_sampling density specified here. The final sampling will be even more sparse than indicated by this value if the initial-sampling divided repeatedly by the sampling-decrement-ratio does not give a value equal to this number.
FWHM-x FWHM-y FWHM-z [-b1 ...] [-b2 ...]
if this option is used, smoothing filters are applied along the x, y and z axes of the standard file (-b1) or reslice file (-b2) before performing registration. The FWHM value specifies the full width at half maximum of the Gaussian smoothing filter to be applied along each dimension. The filters have units of millimeters (or whatever units you use to specify voxel sizes in your .hdr files). All three dimensions must be specified. If you give a value of zero, no smoothing will be applied along the corresponding dimension.
halt-after-(N)-iterations-without-improvement [-h]
controls the maximum number of iterations without any observed improvement in the cost function. If greater than or equal to repeated-iterations, this value has no effect. At lower values, it can help you escape from situations where you are bouncing back and forth between two or three locations in parameter space without making any real progress. This sort of thing usually only happens at superficial sampling densities.
initial-sampling [-s ...]
controls how densely data is sampled during the first iterative cycle of the algorithm for each order of polynomial. Large values generally speed up the registration process because gross misregistration can be detected with fairly superficial sampling of the data. However, choosing an excessively large value can be counterproductive if the algorithm falls into an infinite loop or is led far from the true value by nonrepresentative sampling.
initialization-warp-file [-f]
the name of a .warp file to be used to initialize the spatial transformation. Starting with AIR 5.2.3, the order of this file can be either equal to or one less than that of the model-menu-number. Earlier versions of AIR 5 will only allow orders that are one less than that of the model-menu-number. First (AIR 5.2.3 and later) or second order spatial transformations may also be initialized using a .air file rather than a .warp file provided that the .air file does not use perspective transformations. Prior to AIR 5.0, ASCII files were used for initialization purposes. This is no longer supported. Note that intensity scaling must be initialized separately using the scaling-initialization-file
lesion_file [-l]
regions in the reslice file that correspond to non-zero regions in this file are excluded when computing the cost function. This file must have sizes and dimensions matching those of the reslice file. This option can be used to exclude regions of pathology in the reslice file from consideration when performing registration.
mask [-e1] [-e2]
this file is applied to the standard file (-e1) or reslice file (-e2) as a mask. The file must match the corresponding file's dimensions, and voxels that are zero in this file will be treated as if they were zero in the corresponding file when computing the cost function. Mask files can be binary or regular files.
model-menu-number [mandatory]
the menu number, from the model menu listed above, of the polynomial transformation to be used initially for spatial transformation. Note that this parameter was changed in AIR 5.0 such that this is always the initial model used, regardless of the presence of the optional final-model-menu-number. If no final-model-menu-number is provided, the algorithm starts and ends with the model specified here.
overwrite?(y/n) [-gs ...]
'y' allows any preexisting file with the same name as scaling-termination-file to be overwritten.
repeated-iterations [-r]
controls the maximum number of iterations permitted at each sampling density. If this number is made too low, it will lead to inaccurate results and/or slow down the overall performance of the algorithm by preventing you from making use of information that could have been derived more quickly at the prematurely aborted, more superficial sampling.
reslice-file [mandatory]
the name of the file you want registered to the standard-file (.img or .hdr suffix optional)
sampling-decrement-ratio [-s ...]
determines the number of intermediate iterative cycles of the algorithm. The current sampling is divided by this ratio with each cycle to determine the new sampling.
scaling-initialization-file [-fs]
the name of an ASCII file containing a single parameter that initializes intensity scaling
scaling-termination-file [-gs]
the name of an ASCII file to be created containing the intensity scaling parameter identified as optimal by the algorithm. Combined with a .warp file, this parameter can be used to restart the algorithm at the same location in parameter space where it left off. In addition, the scaling parameter can be used as an intensity normalization factor for subsequent statistical analysis of the registered data or as input to reslice_warp to create a final image that is intensity corrected as well as spatially corrrected.
standard-file [mandatory]
the name of the file that you want the other file resliced to match (.img or .hdr suffix optional). The standard file will often be an atlas, but can also be images from a single subject.
threshold [-t1] [-t2]
defines a minimum voxel value for the standard file (-t1) or reslice file (-t2). Voxels in the corresponding file with intensities below this value are excluded from analysis when computing the cost function and its derivatives. The value should always be an integer less than the maximum voxel value in the corresponding file.
.warp-out [mandatory]
the exact name of the .warp transformation parameter output file (cannot contain '.img' or '.hdr').

Examples:

align_warp subject1 subject2 subject2.warpsubject1 -m 1 2 -t1 10 -t2 10 -gs s2.inits align_warp subject1 subject2 subject2.warpsubject1 -m 3 3 -t1 10 -t2 10 -f subject2.warpsubject1 -fs s2.inits -gs s3.inits y align_warp subject1 subject2 subject2.warpsubject1 -m 4 5 -t1 10 -t2 10 -f subject2.warpsubject1 -fs s3.inits

Comments:


Error messages: (alphabetical by case)

See also: Generic error messages
-b1 must be followed by three non-negative numbers
-b2 must be followed by three non-negative numbers
-c must be followed by a positive number
-h must be followed by a non-negative integer
-m must be followed by a transformation model number from the menu
-r must be followed by a non-negative integer
-s must be followed by three positive integers
-t1 must be followed by an integer
-t2 must be followed by an integer
A termination parameter file name must follow -gs
An image file name must follow -e1 or -e2
An initialization parameter file name must follow -f or -fs
Cannot have two output files with the name: ____
Final model ____ should not be lower than initial model ____
Final sampling (2nd argument after -s) cannot be larger than initial sampling (1st argument after -s)
Initial model ____ is incompatible with a final model of ____
Name of output .warp file cannot contain .hdr or .img
Sampling decrement ratio (3rd argument after -s) must be larger than 1
Unable to parse ____
Unable to parse argument ____, which was expected to being with a '-'
You must specify a spatial transformation model using the -m argument
when two arguments not preceeded by '-' follow -m, both arguments must be spatial transformation model numbers from the menu

See also:


Modified: October 28, 2002
© 2001-2002   Roger P. Woods, M.D.(rwoods@ucla.edu)