align_warp

• purpose
• usage
• examples
• comments
• error messages
• see also

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 ...]

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]

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:

• 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.

• 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.

• 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.

Comments:

• 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

Error messages: (alphabetical by case)

-b1 must be followed by three non-negative numbers

• smoothing kernels must be greater than or equal to zero. If your images are two-dimensional, specify zero for the third smoothing kernel.

-b2 must be followed by three non-negative numbers

• smoothing kernels must be greater than or equal to zero. If your images are two-dimensional, specify zero for the third smoothing kernel.

-c must be followed by a positive number

• negative values or non-numbers cannot be used

-h must be followed by a non-negative integer

• negative integers or non-integers cannot be used

-m must be followed by a transformation model number from the menu

• see the model above

-r must be followed by a non-negative integer

• negative integers or non-integers cannot be used

-s must be followed by three positive integers

• negative integers or non-integers cannot be used

-t1 must be followed by an integer

• non-integers cannot be used

-t2 must be followed by an integer

• non-integers 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

See also:

• alignlinear
• reslice_warp
• reslice_unwarp
• scan_warp