Sdc === SDC - Susceptibility Distortion Correction for Echo-Planar Imaging Part of the micaflow processing pipeline for neuroimaging data. This module corrects geometric distortions in echo-planar imaging (EPI) MRI data caused by magnetic field (B0) inhomogeneities. EPI sequences, commonly used for functional MRI and diffusion MRI, are highly susceptible to distortions from field inhomogeneities that cause compression, stretching, and signal loss in brain regions near air-tissue interfaces. What are Susceptibility Distortions? ------------------------------------ Susceptibility artifacts in EPI occur due to: - Variations in magnetic susceptibility at tissue boundaries - Air-tissue interfaces (e.g., frontal sinuses, ear canals) - Bone-tissue interfaces - Rapid gradient switching in EPI readout Effects of distortions: - Geometric warping (stretching/compression) along phase-encoding direction - Signal dropout in affected regions (orbitofrontal cortex, temporal poles) - Misalignment with structural images - Incorrect spatial localization of brain activity/structure - Poor registration quality Common affected regions: - Orbitofrontal cortex (near frontal sinuses) - Inferior temporal lobes (near ear canals) - Brainstem (near skull base) - Any region near air-tissue interface HYSCO Algorithm: --------------- This implementation uses HYSCO (HYperellastic Susceptibility artifact COrrection): - Estimates B0 field inhomogeneity from blip-up/blip-down image pairs - Uses opposite phase-encoding acquisitions (e.g., AP and PA) - Employs hyperelastic regularization for smooth field estimates - Optimizes using ADMM (Alternating Direction Method of Multipliers) - Produces both corrected images and displacement fields How It Works: 1. Acquire two images with opposite phase-encoding directions 2. Register images using ANTs affine transformation 3. Estimate B0 field map using HYSCO optimization 4. Apply displacement field to unwarp distorted images 5. Output corrected image and field map Features: -------- - HYSCO-based B0 field estimation with hyperelastic regularization - GPU acceleration with PyTorch (CUDA support when available) - Automatic initial alignment using ANTs affine registration - ADMM optimization for robust field estimation - Handles both 3D and 4D (multi-volume) datasets - Outputs corrected images and displacement fields - Supports all common phase-encoding directions (AP/PA, LR/RL, SI/IS) - Automatic dimension handling and warp application - Temporary file management for clean processing When to Use: ----------- - Always for EPI-based sequences (fMRI, DWI) - Before registration to structural images - After motion correction (for DWI) - Before group-level analysis Requirements: ------------ - Two EPI images with opposite phase-encoding directions - Images should be from the same session/subject - For DWI: typically use b=0 volumes from AP and PA acquisitions - GPU recommended for faster processing (10-30x speedup) Command-Line Usage: ------------------ # Basic AP/PA correction (default) micaflow SDC \ --input \ --reverse-image \ --output \ --output-warp # LR/RL phase-encoding micaflow SDC \ --input \ --reverse-image \ --output \ --output-warp \ --phase-encoding lr # SI/IS phase-encoding micaflow SDC \ --input \ --reverse-image \ --output \ --output-warp \ --phase-encoding si Python API Usage: ---------------- >>> from micaflow.scripts.SDC import run >>> >>> # Basic AP/PA correction >>> run( ... data_image="ap_b0.nii.gz", ... reverse_image="pa_b0.nii.gz", ... output_name="corrected_b0.nii.gz", ... output_warp="fieldmap.nii.gz" ... ) >>> >>> # With specific phase-encoding >>> run( ... data_image="lr_epi.nii.gz", ... reverse_image="rl_epi.nii.gz", ... output_name="corrected_epi.nii.gz", ... output_warp="fieldmap.nii.gz", ... phase_encoding="lr" ... ) Pipeline Integration: -------------------- Susceptibility distortion correction is typically applied AFTER motion correction but BEFORE registration to structural images: Diffusion MRI Pipeline: 1. Denoising (denoise) 2. Motion/eddy correction (motion_correction) 3. Susceptibility correction (SDC) 4. B0 extraction (extract_b0) 5. Registration to T1w (coregister) 6. DTI metrics (compute_fa_md) Functional MRI Pipeline: 1. Motion correction 2. Susceptibility correction (SDC) 3. Registration to anatomical 4. Smoothing 5. Statistical analysis Exit Codes: ---------- 0 : Success - distortion correction completed 1 : Error - invalid inputs, file not found, or processing failure Technical Notes: --------------- - Algorithm: HYSCO (HYperellastic Susceptibility artifact COrrection) - Optimization: ADMM (Alternating Direction Method of Multipliers) - Regularization: Hyperelastic regularization with Laplacian operator - ADMM parameters: * max_iter: 500 iterations * rho_max: 1e6 (maximum penalty parameter) * rho_min: 1e1 (minimum penalty parameter) * max_iter_pcg: 20 (preconditioned conjugate gradient iterations) - Initial alignment: ANTs affine registration - Interpolation: Linear (order=1) with nearest-neighbor extrapolation - Phase-encoding dimension mapping: * AP/PA → y-axis (dimension 2) * LR/RL → x-axis (dimension 1) * SI/IS → z-axis (dimension 3) - Supports 4D data: applies correction to all volumes - Field map saved for applying to other images Phase-Encoding Directions: ------------------------- - AP (Anterior-Posterior): Front to back, most common - PA (Posterior-Anterior): Back to front - LR (Left-Right): Left to right - RL (Right-Left): Right to left - SI (Superior-Inferior): Top to bottom - IS (Inferior-Superior): Bottom to top Acquisition Requirements: ------------------------ To use this correction, you need: 1. Two EPI images with OPPOSITE phase-encoding directions 2. Same subject, same session 3. Same acquisition parameters (except PE direction) 4. Minimal head motion between acquisitions Common acquisition protocols: - DWI: b=0 volumes with AP and PA encoding - fMRI: Short EPI runs with opposite PE directions - Separate "blip-up/blip-down" reference scans See Also: -------- - motion_correction : Apply before SDC for DWI - extract_b0 : Extract b=0 volumes for SDC input - coregister : Register corrected images to structural - apply_warp : Apply field map to other volumes References: ---------- Julian, Abigail, and Lars Ruthotto. "PyHySCO: GPU-enabled susceptibility artifact distortion correction in seconds." Frontiers in Neuroscience 18 (2024): 1406821. Command Line Usage ----------------- .. code-block:: bash micaflow SDC [options] Source Code ----------- View the source code: `GitHub Repository `_ Description ----------- This script corrects geometric distortions in echo-planar imaging (EPI) MR images caused by magnetic field (B0) inhomogeneities. It uses the HYSCO algorithm with a pair of images acquired with opposite phase-encoding directions to estimate and correct distortions. Full Help --------- .. code-block:: text ╔════════════════════════════════════════════════════════════════╗ ║ SUSCEPTIBILITY DISTORTION CORRECTION ║ ╚════════════════════════════════════════════════════════════════╝ This script corrects geometric distortions in echo-planar imaging (EPI) MR images caused by magnetic field (B0) inhomogeneities. It uses the HYSCO algorithm with a pair of images acquired with opposite phase-encoding directions to estimate and correct distortions. ────────────────────────── USAGE ────────────────────────── micaflow SDC [options] ─────────────────── REQUIRED ARGUMENTS ─────────────────── --input : Path to the main EPI image (.nii.gz) --reverse-image : Path to the reverse phase-encoded image (.nii.gz) --output : Output path for the corrected image (.nii.gz) --output-warp : Output path for the field map (.nii.gz) ─────────────────── OPTIONAL ARGUMENTS ─────────────────── --phase-encoding: Phase-encoding direction Choices: 'ap', 'pa', 'lr', 'rl', 'si', 'is' Default: 'ap' (Anterior-Posterior) ──────────────────── EXAMPLE USAGE ─────────────────────── # Example 1: AP/PA correction (most common for DWI) micaflow SDC \ --input ap_b0.nii.gz \ --reverse-image pa_b0.nii.gz \ --output corrected_b0.nii.gz \ --output-warp fieldmap.nii.gz # Example 2: LR/RL phase-encoding micaflow SDC \ --input lr_epi.nii.gz \ --reverse-image rl_epi.nii.gz \ --output corrected_epi.nii.gz \ --output-warp fieldmap.nii.gz \ --phase-encoding lr # Example 3: SI/IS phase-encoding micaflow SDC \ --input si_fmri.nii.gz \ --reverse-image is_fmri.nii.gz \ --output corrected_fmri.nii.gz \ --output-warp fieldmap.nii.gz \ --phase-encoding si ─────── WHAT ARE SUSCEPTIBILITY DISTORTIONS? ──────────── Definition: Geometric distortions in EPI images caused by B0 field inhomogeneities at tissue boundaries, especially near air-tissue interfaces. Causes: • Magnetic susceptibility differences at boundaries • Air-tissue interfaces (sinuses, ear canals) • Bone-tissue interfaces • Rapid EPI readout susceptibility Effects: • Stretching/compression along phase-encode direction • Signal dropout in affected regions • Misalignment with structural images • Poor registration quality Commonly Affected Regions: • Orbitofrontal cortex (frontal sinuses) • Inferior temporal lobes (ear canals) • Brainstem (skull base) ────────────────── HYSCO ALGORITHM ────────────────────── Method: 1. Acquire images with opposite phase-encoding (blip-up/down) 2. Initial alignment using ANTs affine registration 3. Estimate B0 field map using ADMM optimization 4. Apply hyperelastic regularization for smoothness 5. Generate displacement field and correct images Optimization: • ADMM (Alternating Direction Method of Multipliers) • Hyperelastic regularization • 500 iterations with adaptive penalty parameter • Preconditioned conjugate gradient solver ───────────── PHASE-ENCODING DIRECTIONS ───────────────── AP (Anterior-Posterior): Front → Back [Most common for DWI] PA (Posterior-Anterior): Back → Front LR (Left-Right): Left → Right RL (Right-Left): Right → Left SI (Superior-Inferior): Top → Bottom IS (Inferior-Superior): Bottom → Top ────────────────────────── NOTES ───────────────────────── • Requires TWO images with OPPOSITE phase-encoding directions • Images must be from same subject, same session • For DWI: typically use b=0 volumes (one AP, one PA) • Field map can be applied to other volumes • Supports both 3D and 4D (multi-volume) inputs • Always apply AFTER motion correction (for DWI) • Apply BEFORE registration to structural images ──────────────── ACQUISITION REQUIREMENTS ─────────────── Essential: • Two EPI acquisitions with opposite PE directions • Same subject, same session • Same acquisition parameters (except PE direction) • Minimal head motion between acquisitions Common Protocols: • DWI: b=0 volumes with AP and PA • fMRI: Short runs with opposite PE • Separate "fieldmap" scans ─────────────── PIPELINE POSITION ─────────────────────── Diffusion Pipeline: 1. Denoising (denoise) 2. Motion correction (motion_correction) 3. Susceptibility correction (SDC) 4. B0 extraction (extract_b0) 5. Registration (coregister) fMRI Pipeline: 1. Motion correction 2. Susceptibility correction (SDC) 3. Registration to anatomical 4. Analysis ────────────────────── EXIT CODES ─────────────────────── 0 : Success - distortion correction completed 1 : Error - invalid inputs, file not found, or processing failure ───────────────── COMMON ISSUES ───────────────────────── Issue: "Out of memory" error Solution: Use GPU if available, or reduce image resolution Issue: Poor correction quality Solution: Check PE directions match acquisition, ensure minimal motion Issue: Very slow processing Solution: Use GPU acceleration (10-30x faster) Issue: Field map dimensions don't match Solution: Script auto-crops; check input image dimensions