uniseg¶

Segments brain MR images into tissue classes while correcting their intensity inhomogeneity and aligning them to a template. It is a reimplementation of the Unified Segmentation of SPM12; reach for it when you want grey matter, white matter and CSF probability maps from one or several MR contrasts, without SPM or MATLAB.

nitorch uniseg FILE... [-t FILE... | --no-tpm] [-m FILE] [-o DIR]
                       [OUTPUT OPTIONS] [-k INT...] [-b] [-w] [--mix]
                       [--mrf [MODE]] [--wish] [-c] [-f]
                       [--lam-prior X] [--lam-bias X] [--lam-warp X]
                       [--lam-mix X] [--lam-mrf X] [--lam-wish X]
                       [-s MM...] [-n ITER] [--tolerance TOL]
                       [-v [LEVEL] | -q] [-p [LEVEL]]
                       [--cpu [THREADS] | --gpu [DEVICE]]

Description¶

Unified Segmentation (Ashburner and Friston, 2005) expresses segmentation, bias correction and spatial normalisation as a single generative model that is fitted by expectation-maximisation. The intensities of each tissue class are modelled by a mixture of Gaussians, so a class such as grey matter can absorb partial-volume voxels with several clusters. The prior probability that a voxel belongs to a class comes from a tissue probability map (TPM), a template that holds one probability map per class and is itself deformed to fit the subject. Dividing out a smooth, multiplicative bias field accounts for the intensity non-uniformity of the scanner. The three parts help each other: a good alignment gives a better segmentation, which in turn gives a better alignment.

uniseg estimates, for the input image(s):

• the posterior probability of each tissue class at each voxel, and the corresponding hard labels;
• the mean and covariance of the Gaussian clusters, and the mixing proportions;
• a bias field per input channel;
• an affine transformation and a nonlinear warp that align the template to the image.

The classes of the default template are those of the SPM12 TPM: grey matter, white matter, CSF, bone, soft tissue and background, in this order. The sixth class, the background, is not stored in the template: it is implicitly what is left for the probabilities to sum to one. By default, the classes are modelled with 4, 2, 2, 2, 2 and 3 Gaussians.

Inputs¶

Pass one or several MR images of the same subject. Several files are treated as the channels of a single multi-channel image (for example T1w and T2w), and must have the same voxel grid. The orientation matrix of the first one is used for all.

• Template. -t gives the template, either one 4D file with a class per volume, or one 3D probability map per class. Without -t, the SPM12 TPM is used. It is downloaded once from the SPM repository, which needs network access the first time, and kept in NITorch's cache directory. A template that stores one class fewer than the number of classes has its last class implicit. The affine matrix and the grid of the first template file define the template space used for the mni and wrp outputs.
• No template. With --no-tpm, no prior is used: the model reduces to a Gaussian mixture with a bias field. Then there is no alignment or warping, you must give the number of classes with -k, and only native-space outputs exist. Also pass --no-wish and --no-clean, since the Wishart regularisation of the command assumes the SPM template and the clean-up assumes a brain.
• Mask. -m gives a mask or a voxel-wise weight map on the grid of the inputs, which sets how much each voxel contributes to the fit.

Number of classes and clusters¶

-k lists the number of Gaussians for each class; its length is the number of classes. The default is 4 2 2 2 2 3 (six classes) when the template has five maps, as the SPM12 TPM does, and one Gaussian per map otherwise. A single value K means K classes with one Gaussian each.

Components¶

Each part of the model can be switched off.

The Markov random field has several modes: once (default) applies it only at the end; always applies it at each iteration; learn applies it at each iteration and also estimates its weights; no (or false) switches it off, like --no-mrf. A bare --mrf means learn, and yes is an alias for learn. Any other value is an error that lists the allowed ones.

The clean-up is tuned for typical head MRI at about 1 mm resolution and may behave poorly on other data. It also assumes the class layout of the SPM12 template (grey matter, white matter and CSF as the first three classes), so switch it off with --no-clean when you use a different template.

Alignment of the template¶

When there is a template, it is first aligned to the image with an affine transformation and then deformed by the warp, which is refined together with the other parameters. -a/--align controls the affine part:

• always (default, also a bare -a or yes) re-optimises the affine transformation at every iteration;
• once aligns the template only at the start;
• no (or --no-align) skips the alignment. The mni and wrp outputs then use the orientation matrix of the image as it is, without affine correction.

Any other value is an error that lists the allowed ones. With --flexi, uniseg also tries to find the right orientation of the image by comparing candidate orientations during the alignment, which helps when the orientation matrix of the file is wrong.

Output spaces and files¶

Every output belongs to one of three spaces, written SPACE below:

Only the native probabilities and labels are written by default. The following files can be requested. Each option takes an optional file name (a template, see below) and switches the output on; without a name, the default one is used.

The default native outputs, --prob-nat and --labels-nat, can be turned off with --no-prob-nat and --no-labels-nat. Bias-related outputs exist only if bias correction is on, and warps only if warping is on. The affine transformation that aligns the template is not written to disk.

In a file name, {dir} is the output directory (-o, or the directory of the first input if -o is not given), {sep} is the directory separator, and {base} and {ext} are the base name and the extension of the first input file (.nii.gz counts as one extension). See also Output filenames. --mni-vx changes the voxel size of the mni and wrp grids from that of the template to an isotropic one.

With several inputs, --bias-SPACE and --nobias-SPACE write one file per channel. Each name follows the {base} of its own input, and a template may also use {c}, the 1-based channel index. If names still collide (for example a custom name without {base} or {c}), .{c} is inserted before the extension. The --nobias-SPACE files hold the bias-corrected images.

Arguments¶

Options¶

Inputs¶

Hardware¶

See Hardware for the shared conventions.

Outputs¶

Components¶

A BOOL can be true, yes, false, no, 1 or 0. A bare flag, such as -b, means yes.

Regularisation¶

Larger values give stiffer or more strongly constrained estimates.

Optimisation¶

Verbosity¶

Examples¶

Segment a T1-weighted image with the SPM12 template. This writes T1w.prob.nat.nii.gz (six probability volumes) and T1w.labels.nat.nii.gz next to the input:

nitorch uniseg T1w.nii.gz

Segment two contrasts of the same subject jointly and collect the results in a directory:

nitorch uniseg T1w.nii.gz T2w.nii.gz -o seg

Also write the bias field, the bias-corrected image and the warp in native space:

nitorch uniseg T1w.nii.gz --bias-nat --nobias-nat --warp-nat

Write the probabilities and labels in the space of the template, resampled to a 1 mm grid:

nitorch uniseg T1w.nii.gz --prob-mni --labels-mni --mni-vx 1

Use a custom template made of one probability map per class, give the number of Gaussians per class, and skip the clean-up, which assumes the class layout of the SPM12 template:

nitorch uniseg T1w.nii.gz -t tpm_gm.nii.gz tpm_wm.nii.gz tpm_csf.nii.gz -k 2 2 2 --no-clean

Make the fit more accurate, at the cost of speed, by sampling every 2 mm and allowing more iterations:

nitorch uniseg T1w.nii.gz -s 2 -n 50

Fit a plain three-class Gaussian mixture without any template:

nitorch uniseg T2w.nii.gz --no-tpm -k 3 --no-wish --no-clean

References¶

• Ashburner, J. and Friston, K. J. (2005). "Unified segmentation". NeuroImage 26(3):839–851. doi:10.1016/j.neuroimage.2005.02.018

See also¶

• denoise_mri: denoise MR images before segmenting them.
• register: register images with more control over the transformations.