Skip to content

dwi-preprocessing-* – Preprocessing of raw DWI datasets

This pipeline corrects diffusion weighted imaging (DWI) datasets for motion, eddy current, magnetic susceptibility and bias field distortions.

In particular, head-motion and eddy current corrections are performed with the eddy tool [Andersson et al., 2016a; Andersson et al., 2016b] from FSL [Jenkinson et al., 2011]. Depending on the data available (see below), the magnetic susceptibility correction can also be performed with the eddy tool or as a separate step. Finally, bias field correction is performed using the N4 algorithm [Tustison et al., 2010] from ANTs [Avants et al., 2014] by computing a single multiplicative bias field from the corrected b0 image(s) as implemented in MRtrix3 [Tournier et al., 2019].

Notes regarding the fieldmaps for the magnetic susceptibility correction

Depending on the type of extra acquisition available (see details in the 'Fieldmap data' section of the BIDS specifications), different magnetic susceptibility corrections are performed. Clinica supports two scenarios:

  • Phase difference image and at least one magnitude image (case 1 in the BIDS specifications).

  • No extra data: this is the case with the public Alzheimer’s Disease Neuroimaging Initiative (ADNI) dataset for instance. The phase unwrapping is simulated thanks to a non-linear registration towards the T1-weighted image, which does not suffer from these artifacts.

The cases 2, 3 and 4 of the BIDS specifications aka the "two phase maps and two magnitude images", the "direct field mapping" (showing the field inhomogeneity in each voxel) and the "multiple phase encoded directions" (topup) approaches are not currently implemented in Clinica.

Dependencies

If you only installed the core of Clinica, the dwi-preprocessing-* pipeline needs the installation of ANTs, FSL, and MRtrix3 on your computer.

Extra installation of Convert3D will be needed for the dwi-preprocessing-using-t1 pipeline.

Running the pipeline

The pipeline can be run with the following command lines depending on the data you have:

clinica run dwi-preprocessing-using-t1 [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY

clinica run dwi-preprocessing-using-phasediff-fmap [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY

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

Please note that you will need the PhaseEncodingDirection and TotalReadoutTime metadata fields in the JSON file associated to your DWI images (see BIDS specifications for more details). For the dwi-preprocessing-using-phasediff-fmappipeline, you will also need the EchoTime1 and EchoTime2 metadata fields in the JSON file associated to your fieldmap images (see BIDS specifications). Without these metadata fields, the pipelines will not run.

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

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.

Decreasing computation time

By default, the eddy tool of FSL uses OpenMP for parallel computing. CUDA can be used instead to speed up processing. To do so, see instructions on the eddy page of the FSL wiki for installation and configuration of eddy_cuda. To check that CUDA has been installed properly, type the eddy_cuda command. If this type of message appears:

$ eddy_cuda
eddy_cuda9.1: error while loading shared libraries: libcudart.so.9.1: cannot open shared object file: No such file or directory
it means that something went wrong during the installation or configuration of CUDA. Otherwise, you should see the help of the command and you can now add the --use_cuda flag in Clinica!

Tip

If your b0 images are not identical to 0 (e.g. 5 or 10, you can check this information by opening your *.bval file), you can use the --low_bval parameter to consider these images as b0s.

Note

Please note that the dwi-preprocessing-using-t1 pipeline will generate many temporary files. It can generate up to 20 GB of data for a dataset with 45 volumes. The size of the working directory is proportional to the number of directions available in the DWI dataset.

Outputs

Results are stored in the following folder of the CAPS hierarchy: subjects/<participant_id>/<session_id>/dwi/preprocessing.

The output files are:

  • <source_file>_space-{T1w|b0}_preproc.{bval|bvec|nii.gz}: corrected DWI dataset where the first volume of the dataset is the reference b0.
  • <source_file>_space-{T1w|b0}_brainmask.nii.gz: brain extracted image based on the reference b0.

Note

If you ran the preprocessing pipeline using the T1-weighted image, your DWI dataset will be registered with the T1w image. Otherwise, your DWI dataset will be registered with the reference b0 image.

Describing this pipeline in your paper

Example of paragraph for the dwi-preprocessing-using-t1 pipeline

These results have been obtained using the dwi-preprocessing-using-t1 pipeline of Clinica [Routier et al., 2021; Wen et al., 2020]. For each subject, all the b0 images were rigidly registered to the first b0 image and averaged to create the b0 reference. Then, the raw DWIs were corrected for eddy current induced distortions and subject movements by simultaneously modelling the effects of diffusion eddy currents and movements on the image. This step was performed using the eddy tool [Andersson et al., 2016a] from FSL [Jenkinson et al., 2012] with the replace outliers (--repol) option [Andersson et al., 2016b]. To correct for susceptibility induced distortions, the T1w MRI was used as fieldmap data. The reference b0 image was first skull-stripped. To obtain the transformation flow from the native diffusion space to the T1w MRI space, the skull-stripped b0 image was registered to the T1w MRI in two steps: first a rigid registration using the FSL flirt tool and then a non-linear registration using the SyN algorithm implemented in ANTs [Avants et al., 2008]. SyN is an inverse-consistent registration algorithm allowing EPI induced susceptibility artifact correction [Leow et al., 2007]. The resulting transformation was applied to the DWIs to correct for the susceptibility induced distortions and the diffusion weighting directions were appropriately updated [Leemans & Jones, 2009]. Lastly, the DWI volumes were corrected for nonuniform intensity using the ANTs N4 bias field correction algorithm [Tustison et al., 2010] and implemented in MRtrix3 [Tournier et al., 2019]. A single multiplicative bias field from the reference b0 image was estimated, as suggested in [Jeurissen et al., 2014]. These steps lead to the corrected DWI volumes from which a brain mask was computed with FSL bet [Smith, 2002].

Example of paragraph for the dwi-preprocessing-using-phasediff-fmap pipeline

These results have been obtained using the dwi-preprocessing-using-fmap pipeline of Clinica [Routier et al., 2021]. For each subject, a brain mask was estimated from the DWI volumes [Dhollander et al., 2016] and a first run of the eddy tool [Andersson et al., 2016a] from FSL [Jenkinson et al., 2012] with the replace outliers (--repol) option [Andersson et al., 2016b] was used to align all the b0 images, average them, and create the reference b0 image. The fieldmap image was calibrated with the FSL fugue/prelude tools [Jenkinson, 2002] and registered to the reference b0 image. Head motion, eddy current and magnetic susceptibility distortions were simultaneously estimated and corrected using a second run of eddy with the calibrated fieldmap. Lastly, the DWI volumes were corrected for nonuniform intensity using the ANTs N4 bias field correction algorithm [Tustison et al., 2010]. A single multiplicative bias field from the corrected reference b0 image was estimated, as suggested in [Jeurissen et al., 2014] and implemented in MRtrix3 [Tournier et al., 2019]. These steps lead to the corrected DWI volumes from which a brain mask was computed with FSL bet [Smith, 2002].

Tip

Easily access the papers cited on this page on Zotero.

Support

Contact us !