DWI Pipeline

__init__

DWI pipeline

Parameters:

Name	Type	Description	Default
subject	object	Subject object	required
session	object	Session object	required
output_path	str	Output path	required
use_which_dwi	str	Which DWI file to use. Defaults to None.	None
use_which_t1w	str	Which T1w file to use. Defaults to None.	None
use_which_flair	str	Which FLAIR file to use. Defaults to None.	None
use_freesurfer_longitudinal	bool	Whether to use FreeSurfer longitudinal processing outpus. Defaults to False.	False
preprocess	bool	Whether to preprocess the DWI data. Defaults to False.	False
output_resolution	float	Output resolution in mm. Defaults to 2.0.	2.0
degibbs	bool	Whether to perform degibbsing. Defaults to True.	True
flip_b_table_axis	list	List of axes to flip the b-table. Defaults to []. [0], [1], [2] for x, y, z axes.	[]
preprocess_method	str	Preprocessing method. 'fdt', 'mrtrix3' or 'post_qsiprep'. Defaults to 'fdt'.	'fdt'
synb0	bool	Whether to use Synb0 for TOPUP. Defaults to False.	False
use_which_reverse_b0	str	Which reverse coded b0 image to use. Defaults to None.	None
dti_fit	bool	Whether to fit DTI model using FSL dtifit. Defaults to True.	False
dwi_t1w_register	bool	Whether to register DWI to T1w space. Defaults to False.	False
dsistudio_gqi	bool	Whether to fit GQI model using DSI Studio. Defaults to False.	False
dsistudio_qsdr	bool	Whether to fit QSDR model using DSI Studio. Defaults to False.	False
amico_noddi	bool	Whether to fit NODDI model using AMICO. Defaults to False.	False
connectome	list	Whether to create a connectome (Global). Defaults to []. Subsets of ['fdt', 'mrtrix3', 'dsistudio'].	[]
tractography	list	Tractography method (ROI-based). Defaults to []. Subsets of ['fdt', 'mrtrix3', 'dsistudio'].	[]
seed_mask	str	Folder name for seed mask. Expected to find /derivatives//sub-/ses-/.nii.gz. Defaults to 'lesion_mask'. Must be in the T1w space.	'lesion_mask'
use_which_mask	str	Which mask file to use (in the processed DWI space). Defaults to None.	None
dtialps	bool	Whether to perform DTI-ALPS analysis. Defaults to False.	False
dtialps_register_method	int	Registration method for DTI-ALPS. 1 for FA + FLIRT, 2 for FA + synthmorph.	1
pved	bool	Whether to perform PVeD analysis. Defaults to False.	False
freewater	list	List of freewater estimation methods. Defaults to []. Subsets of ['single_shell_freewater', 'markvcid_freewater', 'dti_freewater'].	[]
psmd	bool	Whether to perform PSMD analysis. Defaults to False.	False
psmd_exclude_seed_mask	bool	Whether to exclude seed mask in PSMD calculation. Defaults to False.	False
visual_pathway_analysis	bool	Whether to perform visual pathway analysis. Defaults to False. (An ongoing project! Experimental feature.)	False
calculate_dwi_metrics	bool	Whether to calculate DWI scalar maps. Defaults to False.	False
exclude_seed_mask	bool	Whether to exclude seed mask in DWI metrics calculation (For NAWM). Defaults to True.	True
exclude_wmh_mask	bool	Whether to exclude WMH mask in DWI metrics calculation (For NAWM). Defaults to False.	False
extract_from	str	Folder name to extract results from.	None

check_data_requirements

check if the required data is available :return: bool

---

A more detailed description:

DWI Preprocessing

Single-shell and Multi-shell DWI preprocessing

We use customized scripts to preprocess single-shell and multi-shell DWI data, because current popular DWI preprocessing tools (e.g., MRtrix3, QSIPrep) do not provide an easy way to use Synb0-DISCO for distortion correction when no field map is available.

The main steps of our DWI preprocessing pipeline are as follows:

1. If no reverse phase-encoding (PE) b0 image is available, we use Synb0-DISCO to synthesize the undistorted b0 image from T1w image. Otherwise, we directly use the reverse PE b0 image.
2. Denoise and Gibbs ringing removal (Gibbs ringing removal can be optionally applied).
3. FSL's TOPUP and EDDY for distortion and motion correction, using the real or synthesized reverse PE b0 image.
4. Resample the DWI data to a isotropic voxel size.

DSI preprocessing

We use QSIPrep for DSI preprocessing. Our DWI Pipeline starts from QSIPrep preprocessed DSI data for further analysis. TOPUP and EDDY-based distortion and motion correction are not suitable for q-space sampling schemes like DSI, this is the reason why we do not employ DSIStudio for DSI preprocessing.

Concerning the DSI preprocessing pipeline implemented in QSIPrep is time-consuming (e.g., Very long running time qsiprep processing DSI data), we make some modifications to speed up the process (by running the script qsiprep_single.sh):

1. Use DRBUDDI_cuda rather than DRBUDDI for distortion correction. Note that DRBUDDI_cuda requires a CUDA-capable GPU. Another change is to set --DRBUDDI_disable_initial_rigid flag to skip the initial rigid registration for a more stable run on PC.
2. Set shoreline-iters to 1
3. Skip ANTs-based spatial normalization to MNI space by setting --skip-anat-based-spatial-normalization flag. To generate non-linear spatial warps to MNI space (needed for downstream QSIRecon processing), we run a separate registration using mri_synthmorph implemented in Freesurfer 7-dev version.
4. Only use T1w image as anatomical reference. This is ensured by excluding T2w and T2 FLAIR images with nipreps' qsiprep_filter.json file (see How do I select only certain files to be input to fMRIPrep?).

For Chinese readers, notes on using QSIPrep for DSI preprocessing can be found here.

If you are interested in replicating our DSI preprocessing pipeline: please first modify QSIPrep's docker file by using a new tortoise.py, then you can reference the script (qsiprep_single.sh) to run QSIPrep for DSI preprocessing (DWI and reverse b0 images in BIDS format, and put Freesurfer license.txt, DRBUDDI_cuda.sh wrapper script, and qsiprep_filter.json in a folder named code in BIDS root directory).

Reconstruction of Diffusion Models

Tensor Model Fitting

FSL FDT dtifit is used to fit the diffusion tensor model and calculate DTI-derived metrics, including FA, MD, AD, RD, and tensor mode.

Free Water Elimination DTI Model Fitting

Three available options: - Set 'markvcid_freewater' in freewater (Recommended): MarkVCID2 MRI Free Water (FW). As it has been validated on MarkVCID2 study ¹ and external datasets ².

• Set 'single_shell_freewater' in freewater: Single Shell Free Water Elimination Diffusion Tensor Model

• Set 'dti_freewater' in freewater: DIPY free water elimination model. Multi-shell DWI data is required for this method. For our clinical analysis, we mainly focus on the free water component rather than the free water-corrected DTI metrics, this method is not that practical as multi-shell DWI can directly use NODDI model to characterize extracellular water distribution (ISO/FW).

NODDI Model Fitting

AMICO (Accelerated Microstructure Imaging via Convex Optimization) is used to fit the NODDI model and calculate NODDI-derived metrics, including ICVF, ISOVF, and ODI.

DSI Model Fitting

DSIStudio is used to reconstruct the diffusion ODFs and calculate DSI-derived metrics, including GFA, QA etc.

Anatomical Processing

Registration between DWI and anatomiocal Images (fsnative and T1w space)

While QSIPrep register DWI to T1w space during preprocessing using b0 image, we prefer to use FA map for registration because FA map has better contrast for white matter structures.

If corresponding Freesurfer recon-all results are available, some extra processing will be performed for possible subsequent connectome analysis (see below).

DWI-derived Metrics

PSMD

PSMD (Peak Width of Skeletonized Mean Diffusivity), considered a marker of white matter injury, is calculated using psmd script ³. We use a previous version of the script, while the latest version prefers a Docker-based implementation.

DTI-ALPS

DTI-ALPS (Diffusion Tensor Image Analysis along the Perivascular Space) is calculated using a customized script.

The original method was proposed in ⁴. It is important to note that multiple studies have suggested that DTI-ALPS should not be simply interpreted as a reflection of glymphatic function. Instead, DTI-ALPS likely reflects complex changes in brain microstructure, pointing to a more comprehensive neurodegenerative mechanism ⁵.

PVeD

periventricular diffusivity (PVeD) is proposed as a substitute marker reflecting the glymphatic function in the brain ⁶. It is calculated using the official EstPVeD script.

Things to concern: A region growing method is used to determine the periventricular region. However, if there are lesions (such as lacunar infarcts with high MD values) in this region, these lesion areas will be ignored, leading to variability in the periventricular region among subjects.

Connectome Analysis

Note

FreeSurfer recon-all results are required for this part of analysis.

MRtrix3-based Connectome Construction

Mrtrix3 is recommended for connectome construction. The main steps are as follows:

1. dwi2response dhollander/tournier to estimate the response functions for different tissue types (for single-shell data, only WM response function is estimated).

2. dwi2fod msmt_csd/csd to calculate the fiber orientation distributions (FODs) using constrained spherical deconvolution (CSD) (for multi-shell/single-shell data, respectively).

3. mtnormalise to perform multi-tissue informed log-domain intensity normalization on FODs.

4. 5ttgen freesurfer to generate the 5-tissue-type (5TT) image from Freesurfer recon-all results. That's why Freesurfer results are required for this part of analysis. It is convenient to use Freesurfer parcellation as brain atlas for connectome construction, and outperforms 5ttgen fsl in our experience (especially for subjects with severe WMH and Lacunes).

5. 5tt2gmwmi to generate the gray matter-white matter interface (GM-WM interface) from the 5TT image.

6. tckgen to generate 1000000 streamlines using the iFOD2 probabilistic tracking algorithm with anatomically constrained tractography (ACT) framework. The GM-WM interface is used as seeding mask.

7. tcksift2 to compute the cross-sectional area multipliers for each streamline using SIFT2 method.

8. tck2connectome to generate the connectome matrix using Freesurfer parcellation as brain atlas (Currently using aparc and aparc+aseg). The connectome weights are set as SIFT2-weighted streamline count.

References

---

1. Pauline Maillard, Laura J Hillmer, Hanzhang Lu, Konstantinos Arfanakis, Brian T Gold, Christopher E Bauer, Joel H Kramer, Adam M Staffaroni, Lara Stables, Danny JJ Wang, and others. Mri free water as a biomarker for cognitive performance: validation in the markvcid consortium. Alzheimer's & Dementia: Diagnosis, Assessment & Disease Monitoring, 14(1):e12362, 2022. ↩

2. Miao Lin, Shuyue Wang, Hui Hong, Yao Zhang, Linyun Xie, Lei Cui, Lingyun Liu, Yeerfan Jiaerken, Xinfeng Yu, Minming Zhang, and others. Longitudinal changes in white matter free water in cerebral small vessel disease: relationship to cerebral blood flow and white matter fiber alterations. Journal of Cerebral Blood Flow & Metabolism, 45(5):932–944, 2025. ↩

3. Maria Clara Zanon Zotin, Pinar Yilmaz, Lukas Sveikata, Dorothee Schoemaker, Susanne J van Veluw, Mark R Etherton, Andreas Charidimou, Steven M Greenberg, Marco Duering, and Anand Viswanathan. Peak width of skeletonized mean diffusivity: a neuroimaging marker for white matter injury. Radiology, 306(3):e212780, 2023. ↩

4. Toshiaki Taoka, Yoshitaka Masutani, Hisashi Kawai, Toshiki Nakane, Kiwamu Matsuoka, Fumihiko Yasuno, Toshifumi Kishimoto, and Shinji Naganawa. Evaluation of glymphatic system activity with the diffusion mr technique: diffusion tensor image analysis along the perivascular space (dti-alps) in alzheimer’s disease cases. Japanese journal of radiology, 35(4):172–178, 2017. ↩

5. Sihui Li, Ruike Chen, Zuozhen Cao, Qinfeng Zhu, Yihan Ma, Keqing Zhu, Zixuan Lin, Dan Wu, and Alzheimer’s Disease Neuroimaging Initiative. Microstructural bias in the assessment of periventricular flow as revealed in postmortem brains. Radiology, 316(3):e250753, 2025. ↩

6. Chang-Le Chen, Sang Joon Son, Noah Schweitzer, Hecheng Jin, Jinghang Li, Linghai Wang, Shaolin Yang, Chang Hyung Hong, Hyun Woong Roh, Bumhee Park, and others. Periventricular diffusivity reflects apoe $\varepsilon $4–modulated amyloid accumulation and cognitive impairment in the alzheimer's disease continuum. Alzheimer's & Dementia, 21(9):e70659, 2025. ↩