optinorm¶

Unbiased, groupwise alignment ("normalisation") of several scans of the same subject, for example sessions acquired over time or different contrasts acquired in one session. Use it when you have three or more images of one brain and want them all in a common space without privileging any one of them.

nitorch optinorm INPUT INPUT... [-o DIR] [-s STEP...] [--both] [--cleanup]
                 [--loss NAME] [--affine {rigid,similitude,affine}]
                 [--affine-levels LEVELS] [--nonlin-levels LEVELS]
                 [-a VAL] [-m VAL] [-b VAL] [-l VAL...]
                 [-i ORDER] [--no-clip]
                 [-v [LEVEL]] [--cpu [THREADS] | --gpu [ID]]

Description¶

The usual way to align several scans is to choose one as a reference and register all the others to it. This is simple, but biased: the reference is never resampled and its anatomy is imposed on the group, which matters when you compare scans quantitatively, for example to measure longitudinal change.

optinorm avoids the choice. It registers every ordered pair of images, and then finds, for each image, the transformation to a mean space that is, in the least-squares sense, most consistent with all the pairwise transformations. No image plays a special role. The same procedure is used twice, first with affine transformations and then with nonlinear (stationary velocity field) transformations, and the images are finally resampled into the mean space.

Inputs are given first, then options. At least two images are required, and their filenames can have any extension NITorch reads. With N images, the command runs N(N − 1) pairwise registrations in each of the two registration stages, so the cost grows quickly with N; it is intended for a handful of scans.

The command is a driver that chains other NITorch commands. It performs six steps, which you can run in full or selectively:

Each step reads the outputs of the previous steps from the output directory. This makes a run resumable: if it stops or you want to change the settings of the nonlinear stage, rerun it with -s listing only the steps that remain. Before a step starts, the files it needs are checked, and the command stops with a message if any is missing.

By default, the nonlinear stage weights the pairwise velocity fields with the Hessian of the matching term (written by register), which gives more influence to regions where a registration was well constrained. With --both the unweighted combination is computed as well.

All of the intermediate results are kept, unless --cleanup is given. The affine and nonlinear pairwise registrations make up most of the disk usage.

Output layout¶

Everything is written under the output directory DIR (norm by default). Indices i and j are positions in the list of inputs, starting at 1. {base} and {ext} are the name and extension of input file i. If two inputs have the same name, {base} is prefixed by the position of the image.

The optimal transformations of image i can be used to bring any other image in its native space, such as a segmentation, into the mean space with reslice, exactly as the norm step does. See the last example.

Arguments¶

Options¶

Input and output¶

Registration¶

The four penalty weights have the same meaning as in the @nonlin group of register. They apply to the pairwise registrations and to the fit of the optimal velocity fields. The default is a pure membrane energy, which allows large but smooth deformations.

Resampling¶

Other¶

See Hardware for general notes on devices.

Examples¶

Normalise three sessions of the same subject. All the steps are run, and the results are written to norm/; the normalised images are norm/opt/sub-01_ses-1_T1w.norm.nii.gz and so on:

nitorch optinorm sub-01_ses-1_T1w.nii.gz sub-01_ses-2_T1w.nii.gz \
    sub-01_ses-3_T1w.nii.gz -o norm

Align images with different contrasts, using mutual information instead of the default local correlation, on a GPU:

nitorch optinorm sub-01_T1w.nii.gz sub-01_T2w.nii.gz sub-01_FLAIR.nii.gz \
    --loss mi --gpu -o norm

Only align the images affinely (no nonlinear deformation), and write them resliced in the mean space:

nitorch optinorm sub-01_T1w.nii.gz sub-01_T2w.nii.gz sub-01_FLAIR.nii.gz \
    -s aff affopt meanspace -o norm_affine

The result is in norm_affine/opt/*.aligned.resliced.nii.gz.

Continue the run above with the nonlinear stages. The outputs of the affine stage are read from norm_affine/, so the affine settings must not change (the affine model is part of the filenames), but the nonlinear settings can be chosen now: here a stronger membrane penalty, both the weighted and the unweighted optimal fields, and removal of the pairwise registrations at the end:

nitorch optinorm sub-01_T1w.nii.gz sub-01_T2w.nii.gz sub-01_FLAIR.nii.gz \
    -s svf svfopt norm -m 40 --both --cleanup -o norm_affine

Bring a binary brain mask of the first image (sub-01_T1w.nii.gz) into the mean space, using the optimal transformations of image 1. This is what the norm step does for the images themselves:

nitorch reslice sub-01_T1w_mask.nii.gz \
    -l norm/opt/aff/rigid_optim_1.lta \
    -v norm/opt/svf/weighted/svf_optim_weighted_1.nii.gz \
    -t norm/opt/meanspace.nii.gz -i 0 -o sub-01_T1w_mask_mean.nii.gz

See also¶

• register — the pairwise registration used internally.
• affopt and vopt — the steps that turn pairwise registrations into mean-to-image transformations, usable on their own with registrations obtained elsewhere.
• meanspace — computes the mean space.
• reslice — resamples images with the resulting transformations.