Diffusion-weighted imaging processing

This section describes all DWI-related pre-processing steps implemented in micapipe, which heavily relies on tools from mrtrix. This includes image processing in preparation for the construction of tractography-based structural connectivity matrices, as well as associated edge length matrices. This processing pipeline has been optimized for multi-shell DWI, but can also handle single-shell data.



This module performs required pre-processing of DWI scans, in addition to deriving useful metrics from diffusion images (e.g. fractional anisotropy, mean diffusivity). For multi-shell data, the Dhollander algorithm is applied to estimate response functions of CSF, gray, and white matter, and multi-shell, multi-tissue constrained spherical deconvolution is used to estimate fibre orientation distributions. For single-shell data, the Tournier algorithm and single-shell, single tissue constrained spherical deconvolution are used for these processing steps, respectively.

Prerequisites 🖐🏼

You need to run -proc_structural before this stage

  • All DWI scans found in the bids directory are aligned using a rigid-body registration, and concatenated.
  • Concatenated DWI images undergo denoising by MP-PCA and Gibbs ring correction. Residuals are also calculated from denoised images
  • Correction of eddy current-induced distortions and motion
  • Non uniformity bias field correction
  • b0 image is linearly registered to the structural image (nativepro)
  • DWI brain mask is generated by registering MNI152 brain mask to DWI space using previously generated transformations
  • Compute fractional anisotropy and mean diffusivity images
  • Estimate response functions of CSF, gray, and white matter for spherical deconvolution
  • Estimate fibre orientation distributions using spherical deconvolution
  • Compute non-linear transformation from DWI (using white matter fibre orientation distribution image) and structural image aligned to the b0 scan
  • Apply inverse non-linear transformation to 5-tissue-type images for anatomically-constrained tractography
  • Compute track density image with 1 million streamlines using the iFOD1 algorithm. This image is mainly generated for quality control of previous DWI pre-processing.


$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -proc_dwi

Docker command:

$ docker -proc_dwi

Optional arguments:

-proc_dwi has several optional arguments:

Optional argument Description
-dwi_main <path> Provide path to DWI scans with N number of directions and b0. This will override the default settings: <bids>/<sub>/dwi/*_dir-AP_dwi.nii\*.
-dwi_rpe <path> Provide path to b0 DWI scan with reverse phase encoding direction. This will override the default settings: <bids>/<subject>/dwi/*_dir-PA_dwi.nii\*
-dwi_processed <path> The specified image will be used for further DWI processing, instead of performing pre-processing inside the script.
-rpe_all If all DWI directions and b-values are acquired twice with opposite phase encoding directions this option can be used (This option requires that both encoding direction files contain the same number of directions, bvecs and bvals).
-regAffine Specify this option to perform an Affine registration ONLY from DWI to T1w. By default, DWI processing in micapipe performs a non linear registration using ANTs-SyN. We recommend this option for DWI acquisitions with low resolution and/or low SNR. Or if the non-linear registration is not optimal.

Multiple inputs: dwi_main and dwi_rpe

If your DWI naming scheme is different than the default, and you want to process multiple shells at the same you can do it using the -dwi_main and -dwi_rpe flags. When multiple input scans are provided, seperate the filenames by commas, with no space. Don’t forget to specify the full path of the images, as shown below; In this example, the shell1 and shell2 scans of sub-01 will be processed:

 mica-pipe -proc_dwi -sub 01 -out <outputDirectory> -bids <BIDS-directory> \
           -dwi_main <BIDS-directory>/sub-01/dwi/sub-01_acq-shell1_dwi.nii.gz,<BIDS-directory>/sub-01/dwi/sub-01_acq-shell2_dwi.nii.gz

Reverse phase encoding flag ⏮

If you use the argument -dwi_rpe but your reverse phase encoding image does not contain a bval or bvec file, the module will assume that all the images are b0s (if more than one). If the file specified under the -dwi_rpe flag contains any weighted image, it will considerably affect most steps of the processing.

Directories created or populated by -proc_dwi:

- <outputDirectory>/micapipe/<sub>/dwi
- <outputDirectory>/micapipe/<sub>/dwi/eddy
- <outputDirectory>/micapipe/<sub>/xfms

Files generated by -proc_dwi:

- DWI pre-processing outputs stored in <outputDirectory>/micapipe/<sub>/dwi. All outputs are in DWI space:

    - Json card with information about DWI processing:

    - DWI residuals from denoising:

    - DWI residuals from Gibbs ring correction:

    - DWI processed with motion, geometric and Bias-field correction:

    - b0 image used for T1w linear registration to DWI space:

    - Subject's T1w image, affine registration to DWI space:

    - DWI brain mask, created from MNI152 mask:

    - Subject's T1w brain mask, affine registration to DWI space:

    - Subject's T1w image, non-linear registration to DWI space:

    - 5-tissue-types segmentation, non-linear registration to DWI space:

    - Diffusion tensor image (DTI):

    - Fractional anisotropy derived from DTI:

    - Mean apparent diffusion coefficient (mean diffusivity) derived from DTI:

    - Normalized fibre orientation distribution for CSF, gray and white matter:

    - Gray/White matter interface mask:

    - Track density image generated from a tractogram of 1 million streamlines, for quality check:

- DWI registration files are found in <outputDirectory>/micapipe/<sub>/xfms

    - Rigid registrations between shells:

    - Affine registration between T1w nativepro and DWI space:

    - Non-linear registrations between T1w in dwi space to wmNorm in dwi space:

- All outputs from FSL eddy are stored in:

A tract density image (TDI) is a low density snapshot of the tractogram that will be generated in the -SC module. It is useful in providing a quick overview of the DWI processing quality. We strongly recommend to take your time in checking the quality of the processed DWI before generating the structural connectomes (-SC). An abnormal TDI image is a reflection of many different issues with the DWI acquisition or processing, such as:

  • Issues with the DWI DICOMS (missing directions, cropped images, low signal, etc);
  • Low signal to noise ratio (low quality or low resolution);
  • Not enough diffusion directions;
  • Registration errors;
  • Bad encoding of the gradient direction tables (bvecs);
  • Bad encoding of the shell values (bvals);
  • Wrong assignation/encoding of the b0 images (bvals);
  • Large motion artifacts…

File: <outputDirectory>/micapipe/<sub>/dwi/<sub>_space-dwi_desc-iFOD1-1M_tdi.mif




This modules computes tractography-based structural connectivity matrices and associated edge length matrices. We apply iFOD2 for this purpose, a probabilistic tractography algorithm.

Prerequisites 🖐🏼

You need to run -proc_structural, -proc_freesurfer, -post_structural, and -proc_dwi before this stage

  • Compute tractogram with specified number of streamlines using iFOD2 algorithm
  • Build structural connectomes and edge length matrices from cortical, subcortical, and cerebellar parcellations non-linearly registered to DWI space
  • If requested, compute automatic bundle segmentation using auto tractography.


$ mica-pipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -SC

Docker command:

$ docker -SC

Optional arguments:

-SC supports different optional arguments:

Optional argument Description
-tracts <num> Number of streamlines used when computing the tractogram (default is 40M, where ‘M’ stands for millions, same as 40,000,000)
-keep_tck If specified, the tractogram will be copied to <outputDirectory>/micapipe/<sub>/dwi/. By default the tractogram is erased at the end of this module given the large file size.
-autoTract Performs automatic bundle segmentation (optional). See Automatic Bundle Segmentation for further information.

Directories created or populated by -SC:

- <outputDirectory>/micapipe/<sub>/dwi
- <outputDirectory>/micapipe/<sub>/dwi/connectomes

Files generated by -SC:

- SC processing outputs stored in <outputDirectory>/micapipe/<sub>/dwi:

    - Track density image generated with specified number of streamlines:

    - Subcortical segmentation in DWI space:

    - Cerebellar parcellation in DWI space:

- Connectome and edge length outputs are stored in <outputDirectory>/micapipe/<sub>/dwi/connectomes:
    - <sub>_space-dwi_atlas-<parcellation>_desc-iFOD2-<tracts>-SIFT2_<nodes>-connectome.txt
    - <sub>_space-dwi_atlas-<parcellation>_desc-iFOD2-<tracts>-SIFT2_<nodes>-edgeLengths.txt

    Note on structural connectomes: <nodes> can be either...
       - cor: Only cortical nodes are represented in the connectomes/edge length matrix
       - sub: Subcortical and cortical nodes are represented in the the connectomes/edge length matrix
       - full: Subcortical, cerebellar, and cortical nodes are represented in the the connectomes/edge length matrix