Examples

Example Workflows

Here are some example workflows to help you get started with MicaFlow.

Structural MRI Processing

Running basic T1w processing:

micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --out-dir /output --cores 4

Diffusion MRI Processing

Complete DWI processing pipeline:

micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --run-dwi --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 \
  --out-dir /output --cores 4

Registration Example

This example shows how to use SynthSeg for contrast-agnostic registration:

  1#!/usr/bin/env python3
  2"""
  3Example script for contrast-agnostic registration using SynthSeg
  4
  5This script demonstrates a full registration pipeline that uses SynthSeg's brain 
  6parcellation to enable registration between images of different contrasts:
  7
  81. Generate parcellations of both input and reference images using SynthSeg
  92. Register the parcellations to each other (contrast-agnostic)
 103. Apply the resulting transformation to the original input image
 11
 12This approach is useful for registering images with very different contrasts 
 13(e.g., T1w to T2w, FLAIR to T1w, etc.) where direct intensity-based 
 14registration might fail.
 15"""
 16
 17import os
 18import argparse
 19import subprocess
 20import sys
 21
 22
 23def synthseg_registration(input_image, reference_image, output_image, output_dir=None):
 24    """
 25    Perform contrast-agnostic registration using SynthSeg parcellation.
 26    
 27    Parameters
 28    ----------
 29    input_image : str
 30        Path to the input image to be registered
 31    reference_image : str
 32        Path to the reference image (target space)
 33    output_image : str
 34        Path where to save the registered input image
 35    output_dir : str, optional
 36        Directory to save intermediate files (default: current directory)
 37    """
 38    # Create output directory if specified
 39    if output_dir is None:
 40        output_dir = os.getcwd()
 41    os.makedirs(output_dir, exist_ok=True)
 42    
 43    # Define paths for intermediate files
 44    input_parc = os.path.join(output_dir, "input_parcellation.nii.gz")
 45    reference_parc = os.path.join(output_dir, "reference_parcellation.nii.gz")
 46    affine_transform = os.path.join(output_dir, "affine_transform.mat")
 47    warp_field = os.path.join(output_dir, "warp_field.nii.gz")
 48    inverse_warp = os.path.join(output_dir, "inverse_warp_field.nii.gz")
 49    
 50    print(f"Processing input image: {input_image}")
 51    print(f"Reference image: {reference_image}")
 52    print(f"Intermediate files will be saved in: {output_dir}")
 53    
 54    try:
 55        # Step 1: Generate parcellations with SynthSeg
 56        print("\n--- Step 1: Generating brain parcellations with SynthSeg ---")
 57        subprocess.run([
 58            "micaflow", "synthseg",
 59            "--i", input_image,
 60            "--o", input_parc,
 61            "--parc",
 62            "--cpu"
 63        ], check=True)
 64        
 65        subprocess.run([
 66            "micaflow", "synthseg",
 67            "--i", reference_image,
 68            "--o", reference_parc,
 69            "--parc",
 70            "--cpu"
 71        ], check=True)
 72        
 73        # Step 2: Register parcellations using coregister
 74        print("\n--- Step 2: Coregistering parcellated images ---")
 75        subprocess.run([
 76            "micaflow", "coregister",
 77            "--fixed-file", reference_parc,
 78            "--moving-file", input_parc,
 79            "--output", os.path.join(output_dir, "registered_parcellation.nii.gz"),
 80            "--affine-file", affine_transform,
 81            "--warp-file", warp_field,
 82            "--rev-warp-file", inverse_warp,
 83            "--rev-affine-file", os.path.join(output_dir, "inverse_affine_transform.mat")
 84        ], check=True)
 85        
 86        # Step 3: Apply transformation to the original input image
 87        print("\n--- Step 3: Applying transformation to original input image ---")
 88        subprocess.run([
 89            "micaflow", "apply_warp",
 90            "--moving", input_image,
 91            "--reference", reference_image,
 92            "--affine", affine_transform,
 93            "--warp", warp_field,
 94            "--output", output_image
 95        ], check=True)
 96        
 97        print(f"\nSuccess! Registered image saved to: {output_image}")
 98        
 99    except subprocess.CalledProcessError as e:
100        print(f"Error during processing: {e}", file=sys.stderr)
101        sys.exit(1)
102
103
104if __name__ == "__main__":
105    parser = argparse.ArgumentParser(description="Contrast-agnostic registration using SynthSeg")
106    parser.add_argument("--input", required=True, help="Input image to be registered")
107    parser.add_argument("--reference", required=True, help="Reference image (target space)")
108    parser.add_argument("--output", required=True, help="Output registered image")
109    parser.add_argument("--workdir", help="Directory for intermediate files (default: current directory)")
110    
111    args = parser.parse_args()
112    
113    synthseg_registration(
114        input_image=args.input,
115        reference_image=args.reference,
116        output_image=args.output,
117        output_dir=args.workdir
118    )