alignlinear

purpose
usage
examples
comments
error messages
see also

Purpose:

This is a general linear intramodality registration tool (within or across subjects, 2D or 3D). The user can specify any of a variety of models, including rigid-body, affine, or perspective.

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

Usage:

alignlinear standard-file reslice-file air-out -m model-menu-number [options]

Model Menu:

3-D models:: 6. rigid body 6 parameter model; 7. global rescale 7 parameter model; 9. traditional 9 parameter model (std must be on AC-PC line); 12. affine 12 parameter model; 15. perspective 15 parameter model
2-D models (constrained to in-plane, no interpolation):: 23. 2-D rigid body 3 parameter model; 24. 2-D global rescale 4 parameter model; 25. 2-D affine/fixed determinant 5 parameter model; 26. 2-D affine 6 parameter model; 28. 2-D perspective 8 parameter model

options:

[-b1 FWHM_x FWHM_y FWHM_z] (standard file)

smooths standard-file

[-b2 FWHM_x FWHM_y FWHM_z] (reslice file)

smooths reslice-file

[-c convergence-threshold]

changes default convergence threshold

[-d]

forces use of static partitioning, reverting to default behavior of AIR 3.0x

[-e1 mask]

masks standard-file

[-e2 mask]

masks reslice-file

[-f initialization-file]

changes default spatial initialization

[-fs scaling-initialization-file]

changes default intensity initialization

[-g termination-file [overwrite?(y/n)]]

saves final parameters as ASCII file

[-gs scaling-termination-file [overwrite?(y/n)]]

saves final intensity scaling parameter

[-h halt-after-(N)-iterations-without-improvement]

changes default iterations without improvement

[-j]

uses currently unvalidated method for overcoming non-positive definite Hessian matrices

[-p1 partitions]

segments standard-file into designated number of partitions

[-p2 partitions]

segments reslice-file into designated number of partitions

[-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

~~[-w ...]~~

deprecated and no longer supported since .air files can be used directly for initialization of align_warp

[-x cost-function]

cost function from the menu:

standard deviation of ratio image
least squares
least squares with intensity rescaling

[-z]

turns on pre-alignment interpolation to cubic voxels

where the following definitions apply:

air-out [mandatory]

the exact name of the .air transformation parameter output file (cannot contain '.img' or '.hdr').

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.

cost-function [-x]

the number of the cost function selected from the following menu:

1. Standard deviation of ratio images cost function: This cost function has the advantage of being independent of image intensity, so image intensities can be poorly matched and the registration will not be adversely affected. This is the only model that allows multiple partitions as required for intermodality registration.
2. Least squares cost function: This cost function assumes that the image intensities are scaled identically. Least squares is computationally simpler and therefore faster than the standard deviation of ratio images, but may be inaccurate if the image intensities are poorly matched.
3. Least squares with global rescaling cost function: This cost function is identical to the least squares cost function except that an intensity scaling term is added to the model.

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. 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-file [-f]

the name of an ASCII file containing spatial transformation initialization parameters. These parameters can be used to control the starting position for automated registration, a feature that is useful if the initial misregistration is extreme (e.g., > 45° of rotational misregistration) or if the default registration leads to an obviously incorrect result. The format for the rigid-body initialization file is discussed under file types. Rigid-body initialization files are created most easily using the program manualreslice. Different spatial models require different numbers and types of parameters in the initialization file. Note that some cost functions may also allow an intensity parameter initialization file.

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 number of the spatial transformation model selected from the following menu:

3D models

6. rigid-body 6 parameter model

used for intrasubject registration when all voxel sizes are accurately known

7. global rescaling 7 parameter model

provides the so-called 'Procrustes' fit used in some morphometric contexts

9. traditional 9 parameter model (standard must be on AC-PC line)

the usual 9 parameter implementation of the Talairach model, not to be confused with the formal 13 parameter transformation originally described by Talairach and colleagues

12. affine 12 parameter model

generally the recommended model for intersubject registration (the resulting .air file can also be used to initialize polynomial warping with align_warp) or for intrasubject registration when voxel sizes are uncertain

15. perspective 15 parameter model

provides perspective deformation that allows parallel lines to intersect
2D models

23. 2D rigid-body 3 parameter model

analogous to the 6 parameter 3D model

24. 2D global rescale 4 parameter model

analogous to the 7 parameter 3D model

25. 2D affine/fixed determinant 5 parameter model

allows for linear non-rigid distortions that preserve total area; potentially useful for data from serial tissue sections

26. 2D affine 6 parameter model

analogous to the 12 parameter 3D model

28. 2D perspective 8 parameter model

analogous to the 3D 15 parameter model; appropriate for photographs with perspective distortions

overwrite?(y/n) [-g ...] [-gs ...]

'y' allows any preexisting file with the same name as the argument it follows (termination-file or scaling-termination-file) to be overwritten.

partitions [-p1] [-p2]

defines the number of partitions used for segmenting the standard file in the forward direction (-p1) or for segmenting the reslice file in the reverse direction (-p2) when using the standard deviation of the ratio image as a cost function. If this value is zero, no forward direction (-p1 0) or reverse direction (-p2 0) computation is performed. A value of 256 is typically used for intermodality registration when the corresponding file is an MRI study. For MRI-PET registration, the number of partitions corresponding to the PET study should be set to zero. When registering two dissimilar MR images, both data sets can be assigned 256 partitions. For intramodality registration, the default value of 1 is appropriate.

only the ratio image cost function allows more than one partition

Note that AIR now uses dynamic partitioning by default. Instead of dividing the theoretical range of voxel intensities into the designated number of partitions, the actual range of voxel intensities is divided into this number of partitions. This assures that when the dynamic range of the data is restricted, the voxels do not all end up occupying far fewer partitions than requested. The -d flag forces the use of static partitioning as in AIR 3.0x.

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 spatial transformation initialization 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 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).

termination-file [-g]

the name of an ASCII file to be created containing spatial transformation termination parameters. These parameters can then be used as initialization parameters to restart the algorithm at the same location in parameter space where it left off (using the same spatial model). This allows you to switch cost functions or to vary smoothing, among other things. Different spatial models create incompatible files. Note that some cost functions may also allow an intensity parameter termination file.

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.

Examples:

alignlinear pet1 pet2 pet2.airpet1 -m 6 -t1 55 -t2 55 -x 1 -r 8 -c 0.0 -h 8 -a 8

This will derive a .air file for aligning PET study pet2 to match PET study pet1. Thresholds of 55 will be set for each study, the standard deviation of ratio images cost function will be employed, a six parameter spatial model will be used and the algorithm will stop after eight iterations at each sampling density (using the default samplings of 81, 27, 9, 3, and 1). The total number of iterations will be the only applicable stopping criteria since the -h and -a flags have been effectively disabled by setting them equal to the -r flag and the -c flag has been disabled by setting it to zero.

Comments:

The most common problem with the use of this algorithm is inappropriate selection of the thresholds. If you are using an eight bit version of AIR, a PET data threshold around 55 works well. For MRI data, a threshold around 10 is often but not always appropriate. For a sixteen bit verson of AIR, a PET threshold around 14000 may be about right if the image uses the full dynamic range, but a proportionately lower threshold will be needed if only part of the range is utilized. MRI data often only uses 12 of the available 16 bits, so appropriate values typically will be in the 160-2560 range for 16 bit versions of AIR. It is best to look at the images to pick a threshold that excludes nonbrain regions.
When choosing a spatial model, do not assume that more is better. While you can use a 15 parameter model to perform intrasubject registration, the results will be slower. Furthermore, unless there truly is some element of nonrigid-body distortion of the images, the extra parameters that you derive will be errors. If you know that your scanner systematically introduces some sort of linear distortion, the best approach would be to understand the distortion and systematically remove it before registration. However, if this is not practical, use of a model with more freedom does represent a reasonable alternative.
It is better to use mask files than to simply edit the data prior to registration. If you edit prior to registration, there will be a tendency to line up the edges created by editing which may allow the accuracy of the editing to become a predominant factor in determining the accuracy of the registration. When you specify a mask file, the program actually stores two versions of each file, one with editing and the other without. When the cost function is computed, it is always then based on an edited version of one image (dictating that edited regions do not contribute to the cost function) and an unedited version of the other (assuring that data is being compared to data, not to zeros created by editing).
If you are having frequent problems with an error indicating the Hessian matrix is not positive definite, try using the -q option. The non-positive definite Hessian matrix is especially likely to arise when you try to register a file to a resliced version of itself (as people often do when they first try out the algorithm). In this particular situation, the problem is created by the fact that the two files only differ by interpolation and round-off errors which do not have well behaved second derivatives.
Every spatial transformation model is now implemented for every cost function.
The effective default initializations for affine and perspective models in the context of images with differing voxel sizes have been modified to match the default initializations of other models

alignlinear

Purpose:

Usage:

Examples:

Comments:

Error messages: (alphabetical by case)

See also: