DWIForge v2.1

A modular, checkpoint-based diffusion MRI preprocessing and analysis pipeline for single-shell and multi-shell acquisitions. Designed for any BIDS-compliant dataset.

See CHANGELOG.md for release notes.

Pipeline Stages

Stage	Name	Description
00	QC BIDS	Validate BIDS layout, compute SNR, detect acquisition parameters
01	recon-all	FreeSurfer cortical reconstruction
02	Preprocessing	MP-PCA denoising → Gibbs unringing (MRtrix3)
03	T1w Prep	Reorientation → N4 bias correction → SynthStrip skull-stripping
04	EPI Correction	Synb0-DisCo synthetic b0 → topup field estimation
05	DESIGNER	topup + eddy + Rician denoising (DESIGNER2)
12	GNC (optional, off by default)	Gradient nonlinearity correction — spatial distortion only, see stages/12_gnc.sh
06	Tensor Fitting	DTI via tmi (DESIGNER2); FA, MD, AD, RD, eigenvectors
07	NODDI	AMICO 2.x NODDI fitting; NDI, ODI, ISOVF
08	Response Functions	dhollander 3-tissue response estimation
09	Tractography	SS3T-CSD FODs → iFOD2 ACT (10M) → SIFT2 → DK84 connectome
10	QC Report	Per-subject PDF with slice mosaics, metrics table, connectome matrix
11	Connectome Stats	CLR transform of the SIFT2-weighted connectome (compositional-data correction for group-level stats)

Requirements

• MRtrix3 ≥ 3.0.8
• MRtrix3Tissue (for ss3t_csd_beta1) — patch mrtrix3.py for Python 3.12:

  cp ~/mrtrix3/bin/mrtrix3.py ~/MRtrix3Tissue/bin/mrtrix3.py

• FSL ≥ 6.0
• FreeSurfer ≥ 7.x
• ANTs ≥ 2.4
• Docker (for Synb0-DisCo) or Apptainer/Singularity
• Python 3.12 with neuroimaging_env (see env/)
  • DESIGNER2 (designer2, tmi)
  • AMICO 2.x
  • dipy ≥ 1.12, nibabel, matplotlib, scipy
• gradunwarp (gradient_unwarp.py) — optional, only needed if run_gnc = true:

  pip install git+https://github.com/Washington-University/gradunwarp.git

  Also requires a vendor-supplied gradient coefficient file (e.g. Siemens coeff.grad), obtained from your site physicist or scanner vendor — not redistributable, so it isn't bundled here.

See env/DEPENDENCIES.md and env/Environment_Instructions.md for full setup.

Quick Start

# 1. Copy and configure
cp dwiforge.toml my_study.toml
# Edit my_study.toml — set [paths] source, work, output, freesurfer, logs

# 2. Run a single subject
./dwiforge.sh --config my_study.toml --subject sub-001

# 3. Run specific stages only
./dwiforge.sh --config my_study.toml --subject sub-001 --only-stage tensor-fitting

# 4. Resume after a failure
./dwiforge.sh --config my_study.toml --subject sub-001 --resume

# 5. Rerun a specific stage
./dwiforge.sh --config my_study.toml --subject sub-001 \
    --only-stage noddi --rerun-stage noddi

Configuration

All paths and options are set in dwiforge.toml. The key sections are:

[paths]
source     = "/path/to/BIDS"        # BIDS input directory
work       = "/path/to/work"         # per-subject working directory
output     = "/path/to/output"       # final outputs
freesurfer = "/path/to/freesurfer"  # FreeSurfer subjects dir
logs       = "/path/to/logs"

[runtime]
designer_bin         = ""  # auto-detected if empty
designer_python_path = ""  # auto-detected if empty

Multi-subject / SLURM

See container/slurm_example.sh for a SLURM array job template.

The responsemean step (stage 08→09 barrier) must run after all subjects complete stage 08:

# After all stage-08 jobs complete:
PYTHONPATH=/path/to/mrtrix3/lib \
    responsemean Work/group/responses/*/response_wm.txt \
    Work/group/group_response_wm.txt -force
# repeat for gm, csf
touch Work/group/responsemean.done

Notes

• Synb0-DisCo runs via Docker (leonyichencai/synb0-disco:v3.1 --notopup)
• DESIGNER output uses eddy-rotated bvecs when building dwi_preprocessed.mif — critical for correct tensor orientation
• Single-shell NODDI (b=1000, ~32 dirs) gives valid but lower-precision estimates vs multi-shell
• Parcellation is registered from T1w → DWI space before connectome construction

Citation

If you use DWIForge in your research, please cite the pipeline and the underlying tools:

DWIForge

DWIForge v2 (2026). Zenodo. https://doi.org/10.5281/zenodo.19740322

Underlying tools — please also cite the tools that do the work:

Stage	Tool	Citation
02	MP-PCA denoising	Veraart et al. (2016) NeuroImage 142:394–406
02	Gibbs unringing	Kellner et al. (2016) MRM 76(5):1574–1581
03	SynthStrip	Hoopes et al. (2022) NeuroImage 260:119474
04	Synb0-DisCo	Schilling et al. (2020) MRI 73:186–193
05	DESIGNER2 / eddy	Ades-Aron et al. (2018) NeuroImage 183:55–68; Andersson & Sotiropoulos (2016) NeuroImage 125:1063–1078
06	Tensor fitting (tmi)	DESIGNER2 — as above
07	NODDI	Zhang et al. (2012) NeuroImage 61(4):1000–1016
07	AMICO	Daducci et al. (2015) NeuroImage 105:517–523
08–09	MRtrix3	Tournier et al. (2019) NeuroImage 202:116137
08–09	SS3T-CSD	Dhollander et al. (2016) ISMRM; Dell'Acqua & Tournier (2019) NMR Biomed 32(4):e3997
09	iFOD2 / ACT	Smith et al. (2012) NeuroImage 62(3):1924–1938
09	SIFT2	Smith et al. (2015) NeuroImage 119:338–351
12	gradunwarp (GNC)	Glasser et al. (2013) NeuroImage 80:105–124 (HCP Pipelines, gradient nonlinearity correction)
01, 09	FreeSurfer	Fischl (2012) NeuroImage 62(2):774–781
11	CLR / CoDa	Aitchison (1982) J. R. Stat. Soc. B 44(2):139–177; Pawlowsky-Glahn et al. (2015) Modeling and Analysis of Compositional Data, Wiley