`t1-volume` – Volume-based processing of T1-weighted MR images with SPM¶

This pipeline performs four main processing steps on T1-weighted MR images using the SPM software:

Tissue segmentation, bias correction and spatial normalization to MNI space This corresponds to the Segmentation procedure of SPM that simultaneously performs tissue segmentation, bias correction and spatial normalization, a procedure also known as "Unified segmentation" [Ashburner and Friston, 2005].
Inter-subject registration using Dartel A group template is created using DARTEL, an algorithm for diffeomorphic image registration, from the subjects' tissue probability maps in native space (usually GM, WM and CSF tissues) obtained at the previous step. Here, not only the group template is obtained, but also the deformation fields from each subject's native space into the Dartel template space. This is achieved by wrapping the Run Dartel procedure from SPM [Ashburner, 2007].
Dartel template to MNI Once the transformation from the subject’s T1-weighted MRI image to the Dartel template has been computed, the T1-weighted MRI image of each subject can be transported to the MNI space. More precisely, for a given subject, its flow field into the Dartel template is combined with the transformation of the Dartel template into MNI space, and the resulting transformation is applied to the subject’s different tissue maps. As a result, all the images are in a common space, providing a voxel-wise correspondence across subjects. This is achieved by wrapping the Dartel2MNI procedure from SPM [Ashburner, 2007].
Atlas statistics A set of anatomical regions is obtained from different atlases in MNI space (list of available atlases here). The average gray matter density (also in MNI space) is then computed in each of the regions.

Dependencies¶

If you only installed the core of Clinica, this pipeline needs the installation of either SPM12 and Matlab, or SPM standalone on your computer.

Running the pipeline¶

The pipeline t1-volume can be run with the following command line:

clinica run t1-volume [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY GROUP_LABEL

where:

BIDS_DIRECTORY is the input folder containing the dataset in a BIDS hierarchy
CAPS_DIRECTORY is the output folder containing the results in a CAPS hierarchy
GROUP_LABEL is the user-defined identifier for the provided group of subjects.

Pipeline options:

--smooth: a list of integers specifying the different isomorphic full width at half maximum (FWHM) in millimeters used to smooth the images. Default value is: 8.
--tissue_classes: a list of integers (possible values range from 1 to 6) that indicates the tissue classes to save after segmentation (in order: gray matter (GM), white matter (WM), cerebrospinal fluid (CSF), bone, soft-tissue, air/background). Default value is: 1, 2, 3 (GM, WM and CSF are saved).
--dartel_tissues: a list of integers (possible values range from 1 to 6) that indicates the tissue classes to use for the Dartel template calculation (in order: GM, WM, CSF, bone, soft-tissue, air/background). Default value is: 1, 2, 3 (GM, WM and CSF are used).
--modulate / --no-modulate: a flag. If enabled, output images are modulated and volumes are preserved. If disabled, they are not modulated and concentrations are preserved. Default value: --modulate.

Optional parameters common to all pipelines

-tsv / --subjects_sessions_tsv

This flag allows you to specify in a TSV file the participants belonging to your subset. For instance, running the FreeSurfer pipeline on T1w MRI can be done using :

clinica run t1-freesurfer BIDS_PATH OUTPUT_PATH -tsv my_subjects.tsv

TSV Example :

participant_id  session_id
sub-CLNC0001    ses-M000
sub-CLNC0001    ses-M018
sub-CLNC0002    ses-M000

Creating the TSV

To make the display clearer the rows here contain successive tabs but that should not happen in an actual TSV.

-wd / --working_directory

By default when running a pipeline, a temporary working directory is created. This directory stores all the intermediary inputs and outputs of the different steps of the pipeline. If everything goes well, the output directory is eventually created and the working directory is deleted.

With this option, a working directory of your choice can be specified. It is very useful for the debugging process or if your pipeline crashes. Then, you can relaunch it with the exact same parameters which will allow you to continue from the last successfully executed node. For the pipelines that generate many files, such as dwi-preprocessing (especially if you run it on multiple subjects), a specific drive/partition with enough space can be used to store the working directory.

-np / --n_procs

This flag allows you to exploit several cores of your machine to run pipelines in parallel, which is very useful when dealing with numerous subjects and multiple sessions. Thanks to Nipype, even for a single subject, a pipeline can be run in parallel by exploiting the cores available to process simultaneously independent sub-parts. We recommend using your_number_of_cpu - 1 for costly pipelines such as pet-surface-longitudinal.

If you do not specify -np / --n_procs flag, Clinica will detect the number of threads to run in parallel and propose the adequate number of threads to the user.

-cn / --caps-name

Use this option if you want to specify the name of the CAPS dataset that will be used inside the dataset_description.json file, at the root of the CAPS folder (see CAPS Specifications for more details). This works if this CAPS dataset does not exist yet, otherwise the existing name will be kept.

Centering BIDS nifti

If the images from the BIDS_DIRECTORY are not centered, Clinica will give a warning because this can be an issue if later processing steps involve SPM (for instance if you are planning to run pet-surface afterwards). The warning message will contain a suggestion of a command to be run on your BIDS_DIRECTORY in order to generate a new BIDS dataset with images centered. This relies on the IOTool center-nifti. It is highly recommended to follow this recommendation but Clinica won't force you to do so.

Dartel Template

The creation of a new Dartel template performed in the t1-volume pipeline requires at least two images.

Tip

Do not hesitate to type t1-volume --help to see the full list of parameters.

Outputs¶

Tissue segmentation, bias correction and spatial normalization¶

Results are stored in the following folder of the CAPS hierarchy: subjects/<participant_id>/<session_id>/t1/spm/segmentation.

The main output files are:

native_space/:
- <source_file>_segm-{graymatter|whitematter|csf}_probability.nii.gz: The tissue probability maps for the gray matter, white matter and CSF.
normalized_space/
- <source_file>_space-Ixi549Space_T1w.nii.gz: The T1-weighted image in MNI space.
- <source_file>_segm-{graymatter|whitematter|csf}_space-Ixi549Space_modulated-off_probability.nii.gz: The different tissue maps that have been registered to the MNI space without modulation, i.e. no division by the jacobian of the transformation meaning that concentrations are preserved. These outputs are useful if you want to QC both the registration into MNI and the accuracy of the segmentations.

Example of gray matter (GM), white matter (WM) and CSF tissue segmentation.

Inter-subject registration using Dartel¶

The final estimation of the gray matter template is stored under the following folder of the CAPS hierarchy: groups/group-<group_label>/t1/group-<group_label>_template.nii.gz

Example of a group template calculated using DARTEL. Only the gray matter class is shown.

The flow fields containing the deformation from an image to the group template are stored in the folder subjects/<participant_id>/<session_id>/t1/spm/dartel/group-<group_label>/ under the filename <source_file>_target-<group_label>_transformation-forward_deformation.nii.gz.

Dartel template to MNI¶

Results are stored in the following folder of the CAPS hierarchy: subjects/<participant_id>/<session_id>/t1/spm/dartel/group-<group_label>.

The main output files are:

<source_file>_segm-{graymatter|whitematter|csf}_space-Ixi549Space_modulated-on_fwhm-<label>_probability.nii.gz: The modulated tissue probability maps, i.e. the tissue probability maps obtained with multiplied by their relative volume before and after spatial normalisation, into the MNI space. The different tissue maps that have been registered to the MNI space and modulated, i.e. divided by the jacobian of the transformation meaning that volume is preserved.

Final result: Probability Gray Matter in MNI space without smoothing (top) or smoothed using a 8 mm FWHM kernel (bottom).

Atlas statistics¶

Results are stored in the following folder of the CAPS hierarchy: subjects/<participant_id>/<session_id>/t1/spm/dartel/group-<group_label>/atlas_statistics/.

The main output file is:

<source_file>_space-<space>_map-graymatter_statistics.tsv: TSV files summarizing the regional statistics on the labelled atlas <space>.

Note

The full list of output files can be found in the The ClinicA Processed Structure (CAPS) specifications.

Going further¶

If you have PET data, you can now run the pet-volume pipeline to obtain standardized uptake value ratio maps.
You can use mean gray matter maps to perform group comparison with the statistics-volume pipeline.
You can perform classification based on machine learning, as showcased in the AD-ML framework.

Describing this pipeline in your paper¶

Example of paragraph for the t1-volume pipeline:

These results have been obtained using the t1-volume pipeline of Clinica [Routier et al., 2021; Samper et al., 2018]. This pipeline is a wrapper of the Segmentation, Run Dartel and Normalise to MNI Space routines implemented in SPM. First, the Unified Segmentation procedure [Ashburner and Friston, 2005] is used to simultaneously perform tissue segmentation, bias correction and spatial normalization of the input image Next, a group template is created using DARTEL, an algorithm for diffeomorphic image registration [Ashburner, 2007], from the subjects’ tissue probability maps on the native space, usually GM, WM and CSF tissues, obtained at the previous step. The DARTEL to MNI method [Ashburner, 2007] is then applied, providing a registration of the native space images into the MNI space. Finally, a set of anatomical regions are obtained from different atlases in MNI space [Tzourio-Mazoyer et al., 2002, 2015; Joliot et al., 2015; Hammers et al., 2003; Gousias et al., 2008; Shattuck et al., 2008; CAT12], and the average gray matter density is computed in each of the regions.

Tip

Easily access the papers cited on this page on Zotero.

Support¶

You can use the Clinica Google Group to ask for help!
Report an issue on GitHub.

Advanced usage¶

The four main processing steps of the t1-volume pipeline can be performed individually:

A: Tissue segmentation, bias correction and spatial normalization to MNI space

Command line:
```
clinica run t1-volume-tissue-segmentation <bids_directory> <caps_directory>
```
B1: Inter-subject registration using Dartel (creating a new Dartel template)

Command line:
```
clinica run t1-volume-create-dartel <bids_directory> <caps_directory> <group_label>
```
B2: Inter-subject registration using Dartel (using an existing Dartel template)

Command line:
```
clinica run t1-volume-register-dartel <bids_directory> <caps_directory> <group_label>
```

C: Dartel template to MNI

Command line:

clinica run t1-volume-dartel2mni <bids_directory> <caps_directory> <group_label>

D: Atlas statistics