Diffusion MRI Processing Pipeline

A comprehensive end-to-end diffusion MRI processing pipeline built with DIPY. Supports multiple reconstruction methods, multi-method fiber tracking, registration, and bundle segmentation.

Features

• Dataset Information:

  • Automatic DIPY info reporting (image dimensions, b-values, gradient directions)

• Preprocessing:

  • B0 volume extraction and validation
  • Brain extraction (median_otsu)
  • Gibbs ringing correction
  • Motion correction with affine registration
  • Bias field correction
  • Patch2Self denoising
  • S0 signal replacement using DTI prediction

• Multi-Method Reconstruction:

  • DTI (Diffusion Tensor Imaging) - always runs
  • DKI (Diffusion Kurtosis Imaging) - requires 3+ b-values
  • CSD (Constrained Spherical Deconvolution) - single-shell HARDI
  • CSA (Constant Solid Angle)
  • GQI (Generalized Q-Sampling Imaging)
  • MAPMRI (Mean Apparent Propagator MRI)

• Multi-Method Tractography:

  • Deterministic fiber tracking for each reconstruction method
  • Method-specific tractogram outputs
  • Flexible method selection

• Registration & Segmentation:

  • StreamLine-based Linear Registration (SLR) to atlas space
  • Recobundles-based bundle segmentation
  • Support for processing multiple methods in parallel

Requirements

• Python 3.x
• DIPY (with all workflow modules)
• Nibabel
• NumPy

Usage

Basic Usage

./pipeline.sh <dwi.nii.gz> <bvals> <bvecs> <output_dir>

The pipeline will prompt you interactively for:

• Which steps to run (all, skip some, or only selected)
• Which reconstruction methods to use
• Which methods to use for tracking, registration, and segmentation

Advanced Usage

./pipeline.sh <dwi.nii.gz> <bvals> <bvecs> <output_dir> [steps] [recon_methods] [ref_atlas] [atlas_dir] [--dry-run] [--start N]

Parameters:

• steps: Step selection strategy

  • all - Run all steps
  • skip:7,8 - Run all except steps 7 and 8
  • only:0,1,2,6 - Run only specific steps

• recon_methods: Comma-separated method numbers (DTI always runs)

  • 1 = DKI, 2 = CSD, 3 = CSA, 4 = GQI, 5 = MAPMRI
  • Example: 1,2,3 for DKI, CSD, and CSA
  • Leave empty to be prompted interactively

• ref_atlas: Reference tractogram atlas (required for step 9 - registration)

• atlas_dir: Directory containing bundle atlas .trx files (required for step 10 - segmentation)

• --dry-run: Show what would run without executing commands

• --start N: Resume from step N (skip steps 0 through N-1)

Interactive Prompts

When parameters are omitted, the pipeline provides interactive prompts:

Reconstruction Methods:

• Enter numbers separated by commas (e.g., 1,2,4)
• Press Enter for all methods (recommended)
• Enter * for none (DTI only)
• Spaces are handled automatically (e.g., 1, 2, 4 works fine)

Tracking/Registration/Segmentation Methods:

• Choose which reconstruction outputs to process
• Press Enter to process all available methods
• Enter specific numbers to select subset

Examples

# Run full pipeline interactively
./pipeline.sh dwi.nii.gz bvals bvecs output/

# Run all steps with all reconstruction methods
./pipeline.sh dwi.nii.gz bvals bvecs output/ all "" ref_atlas.trx bundle_atlas/

# Run only DKI and CSD, skip S0 replacement and tracking
./pipeline.sh dwi.nii.gz bvals bvecs output/ skip:6,8 1,2

# Dry run to preview commands
./pipeline.sh dwi.nii.gz bvals bvecs output/ --dry-run

# Resume from step 7 (reconstruction) after fixing an issue
./pipeline.sh dwi.nii.gz bvals bvecs output/ --start 7

Output Structure

The output directory structure supports multiple reconstruction methods:

output/
├── pipeline.log                      # Complete pipeline log
├── b0.nii.gz                        # Extracted b0 image
├── mask.nii.gz                      # Brain mask
├── masked.nii.gz                    # Brain-extracted DWI
├── masked_gibbs.nii.gz              # Gibbs-corrected DWI
├── masked_corrected.nii.gz          # Motion-corrected DWI
├── motion_affine.txt                # Motion correction affines
├── masked_bias.nii.gz               # Bias-corrected DWI
├── masked_denoised.nii.gz           # Denoised DWI
├── masked_denoised_s0replaced.nii.gz # S0-replaced DWI
├── dti/                             # DTI reconstruction outputs
│   ├── fa.nii.gz                    # Fractional Anisotropy
│   ├── md.nii.gz                    # Mean Diffusivity
│   ├── rd.nii.gz                    # Radial Diffusivity
│   ├── ad.nii.gz                    # Axial Diffusivity
│   ├── color_fa.nii.gz              # Color-coded FA
│   └── fit_peaks.pam5               # Peak directions for tracking
├── dki/                             # DKI reconstruction outputs
│   └── fit_peaks.pam5
├── csd/                             # CSD reconstruction outputs
│   └── fit_peaks.pam5
├── csa/                             # CSA reconstruction outputs
│   └── fit_peaks.pam5
├── gqi/                             # GQI reconstruction outputs
│   └── fit_peaks.pam5
├── mapmri/                          # MAPMRI reconstruction outputs
│   └── fit_peaks.pam5
├── tractogram_dti.trx               # DTI tractogram
├── tractogram_dki.trx               # DKI tractogram
├── tractogram_csd.trx               # CSD tractogram
├── moved_dti.trx                    # DTI registered tractogram
├── moved_dki.trx                    # DKI registered tractogram
├── moved_csd.trx                    # CSD registered tractogram
├── segment_dti/                     # DTI bundle segmentation
│   ├── bundle1.trx
│   ├── bundle2.trx
│   └── ...
├── segment_dki/                     # DKI bundle segmentation
└── segment_csd/                     # CSD bundle segmentation

Processing Steps

The pipeline consists of 11 steps (0-10):

Step 0: B0 Detection

• Detects b=0 volumes (threshold: 50)
• Extracts mean b0 image for brain extraction

Step 1: Brain Extraction

• Uses DIPY's median_otsu method
• Generates brain mask and masked DWI volume

Step 2: Gibbs Ringing Correction

• Removes Gibbs ringing artifacts using local subvoxel-shift method

Step 3: Motion Correction

• Aligns all volumes using affine registration
• Corrects gradient directions accordingly

Step 4: Bias Field Correction

• Removes intensity inhomogeneities using B0-based correction

Step 5: Denoising

• Applies Patch2Self self-supervised denoising algorithm

Step 6: S0 Replacement

• Predicts S0 signal from b=1000 shell using DTI
• Replaces original b=0 volumes with predicted S0
• Improves data quality for model fitting

Step 7: Model Fitting (Multi-Method)

• Fits selected diffusion models (DTI + optional advanced methods)
• Uses S0-replaced data if available, otherwise uses denoised data
• Generates peaks/PAM files for tracking
• Each method outputs to its own subdirectory

Step 8: Fiber Tracking (Multi-Method)

• Deterministic tracking using peaks from each selected method
• Seed density: 2 seeds per voxel
• Outputs method-specific tractograms (.trx format)

Step 9: Registration (Multi-Method)

• StreamLine-based Linear Registration (SLR) to atlas space
• Registers each selected method's tractogram independently

Step 10: Segmentation (Multi-Method)

• Recobundles-based bundle identification
• Segments each registered tractogram using atlas bundles

Pipeline Summary

At completion, the pipeline displays:

• Total runtime
• Per-step timing summary
• Failed/skipped steps

Example summary:

📊 Pipeline Summary
--------------------------------------------------
Step  | Name                 | Time
--------------------------------------------------
0     | extract b0           | 3s
1     | brain extraction     | 45s
2     | gibbs ringing        | 12s
3     | motion correction    | 234s
4     | bias correction      | 18s
5     | denoising            | 156s
6     | S0 replacement       | 8s
7     | model fitting        | 423s
8     | fiber tracking       | 892s
9     | registration         | 134s
10    | segmentation         | 67s
--------------------------------------------------

Error Handling & Recovery

The pipeline includes robust error handling:

• Validation: Checks for expected outputs after each step
• Logging: All commands and outputs logged to pipeline.log
• Resume capability: Use --start N to resume from any step
• Graceful degradation: Continues processing other methods if one fails
• Clear error messages: Shows which step failed and how to resume

If a step fails:

# Pipeline will show:
❌ Pipeline failed at step 7 (model fitting)
❌ To resume from this step, run with: --start 7

# Resume with:
./pipeline.sh dwi.nii.gz bvals bvecs output/ --start 7

Tips

• Use --dry-run first to verify the pipeline configuration
• For multi-shell data (3+ b-values), consider running all methods
• Press Enter at prompts to select all available methods
• DKI requires at least 3 unique b-values
• CSD works best with single-shell HARDI (b ≥ 1000)
• Each method's tractogram can reveal different fiber populations
• Use the log file for debugging: output/pipeline.log