MICAFlow: Accessible, fast, and pythonic MRI processing pipeline

MICAFlow is a comprehensive neuroimaging pipeline designed for processing structural and diffusion MRI data. It offers modular components that can be used as part of a cohesive workflow or as standalone tools.

Overview

MICAFlow provides a robust and flexible framework for neuroimaging processing. By chaining together deep learning-based segmentation and advanced numerical solutions, it generates precise outputs even for modalities with low signal-to-noise ratio or strong geometric distortions.

Features

• Structural MRI Processing: T1w and FLAIR image processing
• Diffusion MRI Processing: Complete pipeline for DWI processing
• Brain Extraction: SynthSeg-based brain extraction with optional cerebellum removal
• Deep Learning Segmentation: SynthSeg for brain segmentation and parcellation
• Image Registration: Multi-modal coregistration and spatial normalization to standard spaces
• Texture Features: Advanced texture feature generation
• Quality Control: Built-in QC metrics and visualization
• Batch Processing: Automated BIDS directory scanning and processing
• Brain-Extracted Outputs: Optional dedicated directory for all skull-stripped images
• Temporary File Management: Option to preserve intermediate files for debugging
• Modular Design: Components can be used independently or as a complete pipeline
• Flexible Configuration: Via command line arguments or YAML configuration files

Installation

pip install 
# Verify installation
micaflow

Usage

MICAFlow can be used as a complete pipeline or as individual modules:

Running the Full Pipeline

# Basic usage with T1w only
micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /path/to/data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --output /output/path --cores 4

# With FLAIR image
micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /path/to/data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --flair-file sub-001_ses-01_FLAIR.nii.gz --output /output/path \
  --cores 4

# With diffusion data
micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /path/to/data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --dwi-file sub-001_ses-01_dwi.nii.gz \
  --bval-file sub-001_ses-01_dwi.bval --bvec-file sub-001_ses-01_dwi.bvec \
  --inverse-dwi-file sub-001_ses-01_acq-PA_dwi.nii.gz \
  --output /output/path --cores 4

Batch Processing (BIDS)

To process an entire BIDS dataset automatically using the batch command:

micaflow bids --bids-dir /path/to/bids_root --output-dir /path/to/derivatives \
  --cores 4 --gpu

This command will:

1. Scan the BIDS directory for valid subjects and sessions.
2. Automatically identify T1w, FLAIR (optional), and DWI (optional) files based on suffixes.
3. Run the pipeline sequentially for each session found.
4. Generate a micaflow_runs_summary.json in the output directory tracking execution status.

key arguments:

• --bids-dir: Root path to the BIDS dataset.
• --output-dir: Path where derivatives will be saved.
• --participant-label: (Optional) Space-separated list of subject IDs to process (e.g., 001 002).
• --session-label: (Optional) Space-separated list of session IDs to process.
• --t1w-suffix, --dwi-suffix, etc.: Customize matching patterns for input files.

Using Individual Modules

Each module can be used independently:

Brain Extraction

micaflow bet --input t1w.nii.gz --output brain.nii.gz --parcellation segmentation.nii.gz --output-mask mask.nii.gz

Brain Segmentation (SynthSeg)

micaflow synthseg --i t1w.nii.gz --o segmentation.nii.gz --parc --fast --threads 4

Image Registration

micaflow coregister --fixed-file target.nii.gz --moving-file source.nii.gz \
  --output registered.nii.gz --warp-file warp.nii.gz --affine-file affine.mat

Apply Transformations

micaflow apply_warp --moving image.nii.gz --reference target.nii.gz \
  --warp warp.nii.gz --affine affine.mat --output warped.nii.gz

Diffusion Processing

# Denoise DWI data
micaflow denoise --input dwi.nii.gz --bval dwi.bval --bvec dwi.bvec --output denoised_dwi.nii.gz

# Motion correction
micaflow motion_correction --denoised denoised_dwi.nii.gz --input-bvecs dwi.bvec --output-bvecs corrected.bvec --output motion_corrected_dwi.nii.gz

# Susceptibility distortion correction
micaflow SDC --input motion_corrected_dwi.nii.gz --reverse-image reverse_phase_dwi.nii.gz \
  --output corrected_dwi.nii.gz --output-warp sdc_warpfield.nii.gz

# Compute DTI metrics
micaflow compute_fa_md --input preprocessed_dwi.nii.gz --bval dwi.bval --bvec dwi.bvec \
  --output-fa fa_map.nii.gz --output-md md_map.nii.gz

Texture Feature Extraction

micaflow texture_generation --input image.nii.gz --mask mask.nii.gz --output texture_features

Pipeline Workflow

The pipeline performs the following processing steps:

1. Brain Extraction: Using SynthSeg-based segmentation for T1w, FLAIR, and DWI
   • Optionally remove cerebellum with --rm-cerebellum
2. Bias Field Correction: Using N4 bias field correction
3. Brain Segmentation: Using SynthSeg for T1w and FLAIR
4. Registration:
   • FLAIR to T1w space
   • T1w to MNI152 standard space
5. DWI Processing (if enabled):
   • Denoising with Patch2Self
   • Motion correction
   • Susceptibility distortion correction
   • Tensor fitting and DTI metrics calculation
   • Registration to T1w space
6. Texture Feature Generation: On normalized images
7. Brain-Extracted Outputs (if --extract-brain enabled):
   • Creates skull-stripped versions of all outputs in dedicated directory
   • Normalized versions also created
8. Quality Control: Calculating quality metrics
9. Cleanup: Removes temporary files (unless --keep-temp is specified)

Output Structure

The pipeline creates a structured output directory:

output/
├── <subject>/
│   └── <session>/
│       ├── anat/             # Anatomical images (brain-extracted, bias-corrected)
│       ├── dwi/              # Processed diffusion data and DTI metrics
│       ├── metrics/          # Quality metrics and DICE scores
│       ├── textures/         # Texture features
│       └── xfm/              # Transformation matrices and warps

Configuration

MICAFlow can be configured via:

1. Command Line Arguments: For quick setup and individual module usage
2. Configuration File: YAML file for complex setups (specify with --config-file)
3. Default Configuration: Located in config.yaml

System Requirements

• CPU: Multi-core recommended for parallel processing
• RAM: 8GB minimum, 16GB+ recommended
• GPU: Optional but recommended for faster processing (CUDA compatible)
• Disk Space: Depends on dataset size, minimum 10GB recommended

Supported Image Formats

• NIfTI (.nii, .nii.gz)
• BIDS-compatible directory structures

Support and Contact

For issues, questions or feature requests, please open an issue on the GitHub repository.