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.
-proc_dwi
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.
Terminal:
$ micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -proc_dwi
Optional arguments:
-proc_dwi has several optional arguments:
Optional argument |
Description |
|---|---|
|
Provide path to DWI scans with N number of directions and b0. This will override the default settings: |
|
Provide path to b0 DWI scan with reverse phase encoding direction. This will override the default settings: |
|
The specified image will be used for further DWI processing, instead of performing pre-processing inside the script. |
|
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). |
|
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. |
|
Provide a string with this this flag to process new DWI acquisition. This will create a new directory here: dwi/acq-<dwi_acq> |
|
Specifies the b-value threshold for determining those image volumes that correspond to b=0. Default = 61 . This value will vary from DWI acquisition and from scanner to scanner (3T or 7T). |
|
isable scaling of diffusion b-values by the square of the corresponding DW gradient norm. Default is scaling. See more on MRtrix3 documentation |
|
Specify this option to perform the registration based on synthseg. |
|
Use this flag to upsample the DWI to 1.25x1.25x1.25 to increase anatomical contrast (e.g. Low resolution DWI datasets). |
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:
1 micapipe -proc_dwi -sub 01 -out <outputDirectory> -bids <BIDS-directory> \
2 -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_v0.2.0/<sub>/dwi
- <outputDirectory>/micapipe_v0.2.0/<sub>/dwi/eddy
- <outputDirectory>/micapipe_v0.2.0/<sub>/xfm
Files generated by -proc_dwi:
- DWI pre-processing outputs stored in <outputDirectory>/micapipe_v0.2.0/<sub>/dwi.
- All outputs are in DWI space.
- DWI processed with motion, geometric and Bias-field correction and json card:
<sub>_space-dwi_desc-dwi_preproc.mif
<sub>_desc-preproc_dwi.json
- b0 image used for T1w linear registration to DWI space:
<sub>_space-dwi_desc-b0.nii.gz
- DWI brain mask, created from MNI152 mask:
<sub>_space-dwi_desc-brain_mask.nii.gz
- Subject's T1w image, non-linear registration to DWI space:
<sub>_space-dwi_desc-T1w_nativepro_SyN.nii.gz
- 5-tissue-types segmentation, non-linear registration to DWI space:
<sub>_space-dwi_desc-5tt.nii.gz
- Gray/White matter interface mask:
<sub>_space-dwi_desc-gmwmi-mask.nii.gz
- Subcortical segmentation in DWI space:
<sub>_space-dwi_atlas-subcortical.nii.gz
- Cerebellar parcellation in DWI space:
<sub>_space-dwi_atlas-cerebellum.nii.gz
- Diffusion tensor image (DTI):
<sub>_space-dwi_model-DTI.nii.gz
- Fractional anisotropy derived from DTI:
<sub>_space-dwi_model-DTI_map-FA.nii.gz
- Mean apparent diffusion coefficient (mean diffusivity) derived from DTI:
<sub>_space-dwi_model-DTI_map-ADC.nii.gz
- Normalized fibre orientation distribution for white matter:
<sub>_space-dwi_model-CSD_map-FOD_desc-wmNorm.nii.gz
- DWI registration files are found in <outputDirectory>/micapipe_v0.2.0/<sub>/xfms
- Affine registration between T1w nativepro and DWI space:
<sub>*_space-dwi_from-dwi_to-nativepro_mode-image_desc-affine_0GenericAffine.mat
- Non-linear registrations between T1w in dwi space to dwi:
*<sub>*_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_0GenericAffine.mat
*<sub>*_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_1InverseWarp.nii.gz
*<sub>*_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_1Warp.nii.gz
- All outputs from FSL eddy are stored in:
*<outputDirectory>/micapipe_v0.2.0/<sub>/dwi/eddy
-SC
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_surf, -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.
Terminal:
$ micapipe -sub <subject_id> -out <outputDirectory> -bids <BIDS-directory> -SC
Optional arguments:
-SC supports different optional arguments:
Optional argument |
Description |
|---|---|
|
Number of streamlines used when computing the tractogram (default is 40M, where ‘M’ stands for millions, same as 40,000,000) |
|
If specified, the tractogram will be copied to <outputDirectory>/micapipe_v0.2.0/<sub>/dwi/. By default the tractogram is erased at the end of this module given the large file size. |
|
Performs automatic bundle segmentation (optional). See Automatic Bundle Segmentation for further information. |
|
Provide the acquisition name from DWI which will be use to generate the SC, if it is different from default. |
|
Weight the SC by a quantitative map in DWI space (e.g. FA, ADC, qT1 or MT). None by default. |
|
Provide a pre-calculated whole brain tractography (tck) in DWI space to generate the connectomes. |
Directories created or populated by -SC:
- <outputDirectory>/micapipe_v0.2.0/<sub>/dwi
- <outputDirectory>/micapipe_v0.2.0/<sub>/dwi/connectomes
Files generated by -SC:
- SC processing outputs stored in <outputDirectory>/micapipe_v0.2.0/<sub>/dwi:
- Track density image generated with specified number of streamlines:
<sub>_space-dwi_desc-iFOD2-<num>_tdi.nii.gz
<sub>_space-dwi_desc-iFOD2-<num>_tractography.json
- Connectome and edge length outputs are stored in <outputDirectory>/micapipe_v0.2.0/<sub>/dwi/connectomes:
- <sub>_space-dwi_atlas-<parcellation>_desc-iFOD2-<tracts>-SIFT2_full-connectome.shape.gii
- <sub>_space-dwi_atlas-<parcellation>_desc-iFOD2-<tracts>-SIFT2_full-edgeLengths.shape.gii
- fsLR-5k connectomes:
- <sub>_surf-fsLR-5k_desc-iFOD2-<tracts>-SIFT2_full-connectome.shape.gii
- <sub>_surf-fsLR-5k_desc-iFOD2-<tracts>-SIFT2_full-edgeLengths.shape.gii
Note on structural connectomes: full include Subcortical, cerebellar, and cortical nodes are represented in the the connectomes/edge length matrix
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_v0.2.0/<sub>/dwi/<sub>_space-dwi_desc-iFOD2-<tracts>_tdi.mif
