vopt¶

Turns a set of pairwise nonlinear registrations between subjects, each encoded as a stationary velocity field, into one consistent "template-to-subject" velocity field per subject. It is the nonlinear counterpart of affopt.

nitorch vopt -i FIX MOV FILE [-i FIX MOV FILE]... [-w FIX MOV FILE]...
             [-o FILE] [-x BOUND] [-a VAL] [-m VAL] [-b VAL] [-l VAL [VAL]]

Description¶

When you register several images of a subject (several contrasts, or several time points) in pairs with a diffeomorphic method, the pairwise results do not agree with one another: going from A to B and then from B to C does not land where the direct registration from A to C does. vopt reconciles the pairwise velocity fields. It looks for one velocity field \(v_i\) per image, such that for every pair you provide

where \(v_{ij}\) is the field that registers image \(j\) (moving) to image \(i\) (fixed). Velocity fields live in a vector space, so this is a linear least-squares problem. The solution is defined up to a common additive field; vopt removes this ambiguity by centring the \(v_i\), so that they sum to zero. The space they refer to is the "mean space" of the subjects.

Read the other way round, \(v_i\) is the field you would estimate by registering a virtual template, as the moving image, to subject \(i\), taken as the fixed image. This is why the outputs are called template-to-subject fields.

The idea comes from the USLR and JUMP pipelines of Casamitjana et al., which fit mean-to-subject fields with an L1 objective, and from the longitudinal model of Ashburner and Ridgway (2012). vopt instead uses a weighted L2 objective with fixed weights, which you can supply with -w. These weights are the precisions (inverse variances, or squared weights) of the pairwise fields and can come from the Hessian of the registration loss, written at the same time as the field by register. The estimated fields are then smoothed by a regulariser built from the absolute, membrane, bending and linear-elastic energies of the field (-a, -m, -b, -l).

Inputs¶

Each -i option describes one pair: the label of the fixed image, the label of the moving image, and the path to a stationary velocity field that warps the moving image to the fixed one. Labels are arbitrary strings (mtw, 01, sub-02_T1w); they only serve to tell which pairs involve the same image, and they are used in the names of the output files. If you give the same pair twice, the last file wins. A pair given in one direction only is taken as the negative of the reverse direction (the inverse transformation), whether or not you provide weights. You therefore only need to give one direction of each pair. Leaving pairs out can bias the estimate, but the bias averages out when there are many subjects and the pairs you evaluate are sampled at random.

All velocity fields must be defined on the same voxel grid, as 3D vector fields with three components (see Spatial transformations). The pairs should link all images together: every image should appear in at least one pair, and the graph formed by the pairs should be connected.

Each -w option attaches a weight map to one pair, with the same three arguments as -i. A weight map is an image on the same grid as the fields, with either one value per voxel (the same weight for the three components), three values (one weight per component) or six values (the independent entries of a symmetric \(3 \times 3\) precision matrix: three diagonal entries, followed by the three off-diagonal ones). The weight of a pair is also used for its reverse: if you give it for one direction only, it is copied to the other. If only some pairs have a weight, the others receive an isotropic weight equal to the mean of the given weights (averaged over their diagonal entries). If you give no -w option at all, all pairs are weighted equally.

Regularisation¶

After the pairwise fields have been combined, each template-to-subject field is smoothed by solving a regularised problem, using the penalties below. The voxel size used by the penalties is taken from the first input file.

-x selects the boundary condition used when computing derivatives. Accepted values are dct2, dct1, dst2, dst1, dft, zero and nearest.

Output¶

For every label, vopt writes one velocity field. Subjects are sorted by label before they are written. Labels are strings, so they are sorted as strings (10 comes before 2), which only matters if you rely on the order in which {label} is expanded. The header (orientation matrix and grid) is copied from the first input file. The output path is a template in which these placeholders are expanded:

The default is {dir}{sep}{label}_optimal.nii.gz, which writes NIfTI files next to the first input. Create the output directory beforehand when you choose another one.

Arguments¶

vopt has no positional arguments.

A bare -- completes the option just before it, so that the last value can start with a dash: nitorch vopt -i fix mov -- -odd.nii. Only the last option can take dash-prefixed values this way; write the others as ./-name.

Options¶

Each of -o, -x, -a, -m, -b and -l may be given at most once.

Using the outputs¶

The output for a label is the velocity field you would obtain by registering a template (moving) to that subject (fixed), in the same convention as your pairwise fields. To bring a subject into the common space, apply it with reslice as a velocity field (-v, or -iv for its inverse), exactly as you would for a pairwise result, with a target that defines the grid of the template. You can write that grid with meanspace, and integrate a field into a displacement field with vexp.

Examples¶

Combine the six pairwise fields of three images, writing one field per image (A_to_B.nii.gz registers A, as the moving image, to B, as the fixed image):

nitorch vopt \
  -i mtw pdw mtw_to_pdw.nii.gz \
  -i mtw t1w mtw_to_t1w.nii.gz \
  -i pdw mtw pdw_to_mtw.nii.gz \
  -i pdw t1w pdw_to_t1w.nii.gz \
  -i t1w mtw t1w_to_mtw.nii.gz \
  -i t1w pdw t1w_to_pdw.nii.gz \
  -o out/{label}_to_mean.nii.gz

Write the outputs next to the first input file, keeping its extension:

nitorch vopt \
  -i mtw pdw mtw_to_pdw.nii.gz \
  -i pdw t1w pdw_to_t1w.nii.gz \
  -i t1w mtw t1w_to_mtw.nii.gz \
  -o {dir}{sep}{label}_to_mean{ext}

Weight each pair by a precision map, such as the Hessians written by register, and increase the smoothness of the result:

nitorch vopt \
  -i mtw pdw mtw_to_pdw.nii.gz  -w mtw pdw mtw_to_pdw_hessian.nii.gz \
  -i pdw t1w pdw_to_t1w.nii.gz  -w pdw t1w pdw_to_t1w_hessian.nii.gz \
  -i t1w mtw t1w_to_mtw.nii.gz  -w t1w mtw t1w_to_mtw_hessian.nii.gz \
  -b 0.5 \
  -o out/{label}_to_mean.nii.gz

References¶

• Casamitjana, Iglesias, Tudela, Niñerola-Baizán, Sala-Llonch. "JUMP: A joint multimodal registration pipeline for neuroimaging with minimal preprocessing". ISBI (2024).
• Casamitjana, Sala-Llonch, Lekadir, Iglesias. "USLR: an open-source tool for unbiased and smooth longitudinal registration of brain MR". arXiv (2023).
• Ashburner, Ridgway. "Symmetric diffeomorphic modeling of longitudinal structural MRI". Frontiers in Neuroscience (2012).

See also¶

• affopt: the same problem for affine transformations.
• register: produces the pairwise velocity fields and Hessians.
• reslice, vexp, meanspace: apply and manipulate the results.