align_warp
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.
align_warp
standardfile
reslicefile
.warpout
m
modelmenunumber
[finalmodelmenunumber ]
[options]
Model Menu:
 3D 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
 2D 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 FWHMx FWHMy FWHMz]
 smooths standardfile
 [b2 FWHMx FWHMy FWHMz]
 smooths reslicefile
 [c convergencethreshold]
 changes default convergence threshold
 [e1 mask]
 masks standardfile
 [e2 mask]
 masks reslicefile
 [f initializationwarpfile]
 changes default spatial initialization
 [fs scalinginitializationfile]
 changes default intensity initialization
[g ...]
 deprecated and no longer supported, unneeded since .air and .warp files can be used directly for
initializations
 [gs scalingterminationfile [overwrite?(y/n)]
 saves final intensity scaling parameter
 [h haltafter(N)iterationswithoutimprovement]
 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 nonpositive definite Hessian matrices
 [l lesionfile]
 excludes specified regions in reslicefile when computing cost function
 [q]
 assumes noninteraction of spatial parameter derivatives (reduces likelihood of nonpositive definite Hessian matrices)
 [r repeatediterations]
 changes default repeated interations
 [s initialsampling finalsampling samplingdecrementratio]
 changes default sampling
 [t1 threshold]
 changes default threshold for standardfile
 [t2 threshold]
 changes default threshold for reslicefile
 [v]
 enables verbose reporting of interim results
 where the following definitions apply:

 convergencethreshold [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.
 finalmodelmenunumber [flagless option]
 Models are incremented sequentially from the
modelmenunumber 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.
 finalsampling [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
initialsampling divided repeatedly by the
samplingdecrementratio does
not give a value equal to this number.
 FWHMx FWHMy FWHMz [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.
 haltafter(N)iterationswithoutimprovement [h]
 controls the maximum number of iterations without any observed improvement in
the cost function. If greater than or equal to
repeatediterations,
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.
 initialsampling [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.
 initializationwarpfile [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 modelmenunumber. Earlier versions of AIR 5 will only allow
orders that are one less than that of the modelmenunumber. 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
scalinginitializationfile
 lesion_file [l]
 regions in the reslice file that correspond to nonzero 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.
 modelmenunumber [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
finalmodelmenunumber. If no
finalmodelmenunumber 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
scalingterminationfile to be overwritten.
 repeatediterations [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.
 reslicefile [mandatory]
 the name of the file you want registered to the standardfile
(.img or .hdr suffix optional)
 samplingdecrementratio [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.
 scalinginitializationfile [fs]
 the name of an ASCII file containing a single parameter that initializes
intensity scaling
 scalingterminationfile [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.
 standardfile [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.
 .warpout [mandatory]
 the exact name of the .warp transformation parameter output file (cannot
contain '.img' or '.hdr').
align_warp subject1 subject2 subject2.warpsubject1 m 1 2 t1 10 t2 10 gs s2.inits
 This will derive a .warp file for aligning an image of subject2 to match an image of
subject1. Thresholds of 10 will be applied to each file, and the algorithm will start with a
first order transformation using the default assumption that the centers of the files
should be aligned. The algorithm will proceed to a second order polynomial spatial
transformation model. A scaling termination file called s2.inits will be created. If
a file called s2.inits already exist, the program won't run because it doesn't have
permission to overwrite this file. However, note that permission to overwrite
subject2.warpsubject1 is automatically granted by default.
align_warp subject1 subject2 subject2.warpsubject1 m 3 3 t1 10 t2 10 f subject2.warpsubject1 fs s2.inits gs s3.inits y
 This example will pick up where the previous one left off. It will read the parameters of the
previous model from subject2.warpsubject1 and performs registration using a third order
polynomial spatial transformation model. A scaling termination file called s3.inits will be
created. The .warp file from the previous registration will be overwritten. If a file called
s3.inits already exists, it will also be overwritten.
align_warp subject1 subject2 subject2.warpsubject1 m 4 5 t1 10 t2 10 f subject2.warpsubject1 fs s3.inits
 This example will again pick up where the previous one left off. It will read the parameters
of the previous model from the .warp and termination files and performs registration using
a fourth and then a fifth order polynomial spatial transformation model. It will not
create a termination file. The .warp file from the previous third order registration will
overwritten.
 For MR data, it is recommended that you edit the data to remove nonbrain structures
(e.g., scalp, skull and dura). Even if the algorithm does run successfully, you will have
invested a lot of computation time in making sure that your subjects' noses are of
similar size and shape, even if this means that their cerebellums don't line up so well.
For human PET data where nonbrain structures are not prominent, editing is probably not
required. Similarly, some MR fast spin echo sequences can be handled without editing.
 If data is missing because it was outside the original field of view (e.g., if you
have resampled a target image to place it in a standardized pose), the missing data can
be a source of major errors since this program will assume that the data is truly
absent and will distort the image being registered to such a target in an effort to
put zeros (including the implicit zeros that lie outside the field of view) into the
region where your target inappropriately has zeros. Similar problems can arise if you
make inconsistent decisions about certain arbitrary boundaries during manual editing
(e.g., the boundary between brain and spinal cord). To avoid such problems, you should
eliminate planes that contain only partial brain data since this program will ignore
anything that is outside the field of view of the images that are being registered. The
program resize will allow you to remove planes of partial data.
 If you do edit the data, you can choose thresholds of 1 (unless you want the
threshold to provide some additional editing of low voxel values). Note that 8 and
16 bit data will require different thresholds and that the thresholds should be chosen
to exclude nonbrain voxels.
 If you are using the algorithm for the first time, its best to start with a low order
polynomial and work your way up to get a feel for how long the registration requires.
Second order polynomial models run reasonably fast, but fifth order polynomials are
noticeably slower. Polynomials above 8th order are extremely computationally expensive.
You might also consider using very sparse sampling to get a feeling for speed (e.g.,add
" s 81 81 3" to your command line). Termination and initialization files will allow you
to proceed to higher order models without having to rederive any work already done.
 For PET data, you probably will only get a third order polynomial even if you request
a higher order because the algorithm generally can't improve upon the third order results
with PET data. Since higher order fits take longer, you might as well save time and only
ask for third order in the first place. MRI data can generally sustain improvements
through fifth or sixth order in all cases. Higher orders are increasingly less likely to
achieve a result of the requested order.
 Missing data due to a limited field of view can lead to unexpected or even bizarre
results with high order warping. If you are dealing with a restricted field of view, you
should probably stay with second or third order nonlinear models (or at least carefully
inspect the results obtained with higher order models.
 The first order polynomial registration provided by this algorithm is probably not as
accurate as the one that can be derived using alignlinear.
Although the spatial transformation models are identical,
alignlinear takes advantage of the invertibility of the transformation to compute the
cost function in an unbiased fashion such that registration of image A to image B will be
the exact inverse of registration of image B to image A. This is not the case here. In
fact, I prefer to use alignlinear to derive the
initial linear transformation using the scaled least squares cost function (x 3 flag)
and then use that data to create a scaling initialization file for this program starting
with a second order transformation. The spatial transformations saved by
alignlinear can be loaded as a first order initialization
file for this program.
 The use of mask files by this program is different from
alignlinear. There, the masks are applied in a way that assures that edited images
are never directly compared to one another, preventing any tendency to just line up the
edited edges. Here, the masks are applied to both images immediately, and the two edited
images are directly compared in computing the cost function. Maskfiles are included here
merely as a convenience. You will get the same results if you simply edit the images and
register the edited versions.
 Nonlinear transformations cannot be inverted analytically, so plan carefully when
deciding which file should be the standard file and which should be the reslice file.
 The effective default initialization in the context of images with differing voxel sizes have been modified to match the new default initialization in alignlinear
See also: Generic error messages
 b1 must be followed by three nonnegative numbers

 smoothing kernels must be greater than or equal to zero. If your images are
twodimensional, specify zero for the third smoothing kernel.
 b2 must be followed by three nonnegative numbers

 smoothing kernels must be greater than or equal to zero. If your images are
twodimensional, specify zero for the third smoothing kernel.
 c must be followed by a positive number

 negative values or nonnumbers cannot be used
 h must be followed by a nonnegative integer

 negative integers or nonintegers cannot be used
 m must be followed by a transformation model number from the menu

 r must be followed by a nonnegative integer

 negative integers or nonintegers cannot be used
 s must be followed by three positive integers

 negative integers or nonintegers cannot be used
 t1 must be followed by an integer

 nonintegers cannot be used
 t2 must be followed by an integer

 nonintegers cannot be used
 A termination parameter file name must follow gs

 the additional file name argument must be supplied
 An image file name must follow e1 or e2

 the additional file name argument must be supplied
 An initialization parameter file name must follow f or fs

 the additional file name argument must be supplied
 Cannot have two output files with the name: ____

 the .warp file and scaling termination file cannot have the same name
 Final model ____ should not be lower than initial model ____

 the final model should be greater than or equal to the initial model
 Final sampling (2nd argument after s) cannot be larger than initial sampling (1st argument after s)

 adjust values as required
 Initial model ____ is incompatible with a final model of ____

 2D and 3D models cannot be intermixed
 Name of output .warp file cannot contain .hdr or .img

 use a name that does not contain these terms
 Sampling decrement ratio (3rd argument after s) must be larger than 1

 adjust values as required
 Unable to parse ____

 the specified flag is not defined
 Unable to parse argument ____, which was expected to being with a ''

 check syntax, an argument without a flag is positioned as if were a flag
 You must specify a spatial transformation model using the m argument

 the m flag and argument(s) are required, not optional
 when two arguments not preceeded by '' follow m, both arguments must be spatial transformation model numbers from the menu

 supply valid models from the menu
Modified: October 28, 2002
© 20012002 Roger P. Woods, M.D.(rwoods@ucla.edu)