MICAflow Pipeline

Overview

The MICAflow pipeline provides a comprehensive framework for processing structural and diffusion MRI data through a series of coordinated steps implemented as a Snakemake workflow.

The pipeline is organized into several processing stages that are executed in a specific order, with dependencies managed automatically by Snakemake:

Structural Processing: - Skull stripping of T1w and FLAIR images - Bias field correction - SynthSeg segmentation
Registration: - T1w to MNI152 space - FLAIR to T1w space - DWI to T1w space (if DWI data is available)
Texture Feature Generation: - Gradient magnitude maps - Relative intensity maps
Diffusion Processing (Optional): - Denoising - Motion correction - Susceptibility distortion correction - Computation of FA and MD maps
Quality Metrics: - Jaccard similarity for registration accuracy

Required Inputs:

--subject: Subject ID (e.g., sub-01)
--output: Output directory
--t1w-file: Path to T1-weighted image file

Optional Inputs:

--session: Session ID (e.g., ses-01)
--flair-file: Path to FLAIR image file
--dwi-file: Diffusion weighted image
--bval-file: B-value file for DWI
--bvec-file: B-vector file for DWI
--inverse-dwi-file: Inverse (PA) DWI for distortion correction

Primary Outputs:

The pipeline generates the following directory structure:

<OUTPUT_DIR>/
└── <SUBJECT>/
    └── <SESSION>/
        ├── anat/                    # Preprocessed anatomical images
        ├── dwi/                     # Preprocessed diffusion data (if available)
        ├── metrics/                 # Quality assessment metrics
        ├── textures/                # Texture feature maps
        └── xfm/                     # Transformation files

Command Line Usage:

micaflow pipeline \
  --subject SUB001 \
  --session SES01 \
  --output /path/to/output \
  --data-directory /path/to/data \
  --t1w-file /path/to/t1w.nii.gz \
  [options]

Additional Options:

--threads N: Number of threads to use (default: 1)
--cpu: Force CPU computation instead of GPU
--dry-run: Show what would be executed without running commands

Pipeline Configuration:

The pipeline can also be configured using a YAML file:

micaflow pipeline --config-file config.yaml

Example Configuration File (config.yaml):

# Example configuration for micaflow pipeline
subject: "sub-01"                             # Subject ID
session: "ses-01"                             # Session ID

# Input data paths
t1w_file: "/data/bids/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz"
flair_file: "/data/bids/sub-01/ses-01/anat/sub-01_ses-01_FLAIR.nii.gz"
dwi_file: "/data/bids/sub-01/ses-01/dwi/sub-01_ses-01_dir-AP_dwi.nii.gz"
bval_file: "/data/bids/sub-01/ses-01/dwi/sub-01_ses-01_dir-AP_dwi.bval"
bvec_file: "/data/bids/sub-01/ses-01/dwi/sub-01_ses-01_dir-AP_dwi.bvec"
inverse_dwi_file: "/data/bids/sub-01/ses-01/dwi/sub-01_ses-01_dir-PA_dwi.nii.gz"

# Output settings
output: "/results/micaflow"
data_directory: "/data/bids"

# Processing options
threads: 8               # Number of CPU threads to use
cpu: true                # Force CPU processing (set to false for GPU)
run_dwi: true            # Whether to process DWI data

# Advanced options (optional)
dry_run: false           # Just show commands without executing
cleanup: true            # Remove temporary files after completion

This configuration can be adapted for different subjects and datasets by updating the paths and processing parameters accordingly.

MICAflow supports two approaches for providing input data to the pipeline:

1. BIDS Directory Approach:

When using a BIDS-compliant dataset, you can specify the root directory and the pipeline will automatically locate files based on subject and session IDs:

micaflow pipeline \
  --subject sub-01 \
  --session ses-01 \
  --data-directory /path/to/bids/dataset \
  --output /path/to/output

In this case, the pipeline will look for files at standard BIDS locations:

/path/to/bids/dataset/
└── sub-01/
    └── ses-01/
        ├── anat/
        │   ├── sub-01_ses-01_T1w.nii.gz
        │   └── sub-01_ses-01_FLAIR.nii.gz
        └── dwi/
            ├── sub-01_ses-01_dwi.nii.gz
            ├── sub-01_ses-01_dwi.bval
            └── sub-01_ses-01_dwi.bvec

2. Direct File Path Approach:

For datasets that are not BIDS-compliant or when working with specific files, you can directly specify the path to each input file:

micaflow pipeline \
  --subject SUB001 \
  --session SES01 \
  --t1w-file /path/to/t1w.nii.gz \
  --flair-file /path/to/flair.nii.gz \
  --dwi-file /path/to/dwi.nii.gz \
  --output /path/to/output

Advantages of Each Approach:

BIDS Directory: - Simpler command line with fewer parameters - Automatic file discovery based on BIDS naming conventions - Better for batch processing multiple subjects with consistent naming
Direct File Paths: - Works with any directory structure - Flexible for non-standard file naming - Allows processing specific files from different locations

Both approaches can be used in the YAML configuration file as well:

# BIDS Directory approach
subject: "sub-01"
session: "ses-01"
data_directory: "/path/to/bids/dataset"

# OR Direct File Paths approach
subject: "SUB001"
session: "SES01"
t1w_file: "/path/to/t1w.nii.gz"
flair_file: "/path/to/flair.nii.gz"
dwi_file: "/path/to/dwi.nii.gz"

Implementation Details

The pipeline implementation follows a modular design where each processing step is encapsulated as a separate rule in the Snakefile:

# Key pipeline rules from Snakefile
rule skull_strip:
    # Extract brain tissue from T1w/FLAIR images

rule bias_field_correction:
    # Correct intensity non-uniformities

rule synthseg_t1w:
    # AI-based segmentation of T1w images

rule registration_t1w:
    # Register FLAIR to T1w space

rule registration_mni152:
    # Register T1w to standard space

rule run_texture:
    # Generate texture feature maps

# Additional DWI processing rules when enabled
if RUN_DWI:
    rule dwi_denoise:
        # Remove noise from diffusion images

    rule dwi_motion_correction:
        # Correct for head motion in diffusion data

    # ... additional DWI rules ...

Quality Control

The pipeline includes quality assessment metrics to evaluate the performance of critical processing steps:

Registration Accuracy: Jaccard similarity metrics between registered images
Transformation Files: All transformation matrices and warp fields are saved for inspection
Intermediate Results: Preprocessed images at each stage for quality checks

For complete implementation details, refer to the Snakefile in the repository.