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: - SynthSeg-based brain extraction (with optional cerebellum removal) - 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 (Patch2Self) - 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 multiple approaches for providing input data to the pipeline:

1. Automated Batch Processing (BIDS):

To automatically process an entire BIDS dataset sequentially, use the bids command. This acts as a wrapper that automatically identifies T1w, FLAIR, and DWI files across all subjects and generates a run summary:

micaflow bids \
  --bids-dir /path/to/bids/dataset \
  --output-dir /path/to/output \
  --participant-label 01 02 \
  --cores 4

2. Single Subject BIDS Directory:

When using a BIDS-compliant dataset for a single run, 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

3. 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:

Automated Batch Processing (bids): - Scans and processes entire datasets sequentially. - Easily filter processing by participant/session labels. - Generates a JSON summary tracking the status of all runs.
Single Subject BIDS (pipeline): - Simpler command line with fewer parameters for a single specific run. - Automatic file discovery based on BIDS naming conventions.
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.