|
| 1 | +.. _pipeline: |
| 2 | + |
| 3 | +MICAflow Pipeline |
| 4 | +================ |
| 5 | + |
| 6 | +Overview |
| 7 | +-------- |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +.. tabs:: |
| 12 | + |
| 13 | + .. tab:: Pipeline Structure |
| 14 | + |
| 15 | + The pipeline is organized into several processing stages that are executed in a specific order, with dependencies managed automatically by Snakemake: |
| 16 | + |
| 17 | + 1. **Structural Processing:** |
| 18 | + - Skull stripping of T1w and FLAIR images |
| 19 | + - Bias field correction |
| 20 | + - SynthSeg segmentation |
| 21 | + |
| 22 | + 2. **Registration:** |
| 23 | + - T1w to MNI152 space |
| 24 | + - FLAIR to T1w space |
| 25 | + - DWI to T1w space (if DWI data is available) |
| 26 | + |
| 27 | + 3. **Texture Feature Generation:** |
| 28 | + - Gradient magnitude maps |
| 29 | + - Relative intensity maps |
| 30 | + |
| 31 | + 4. **Diffusion Processing (Optional):** |
| 32 | + - Denoising |
| 33 | + - Motion correction |
| 34 | + - Susceptibility distortion correction |
| 35 | + - Computation of FA and MD maps |
| 36 | + |
| 37 | + 5. **Quality Metrics:** |
| 38 | + - Jaccard similarity for registration accuracy |
| 39 | + |
| 40 | + .. tab:: Inputs & Outputs |
| 41 | + |
| 42 | + **Required Inputs:** |
| 43 | + |
| 44 | + - ``--subject``: Subject ID (e.g., sub-01) |
| 45 | + - ``--output``: Output directory |
| 46 | + - ``--t1w-file``: Path to T1-weighted image file |
| 47 | + |
| 48 | + **Optional Inputs:** |
| 49 | + |
| 50 | + - ``--session``: Session ID (e.g., ses-01) |
| 51 | + - ``--flair-file``: Path to FLAIR image file |
| 52 | + - ``--dwi-file``: Diffusion weighted image |
| 53 | + - ``--bval-file``: B-value file for DWI |
| 54 | + - ``--bvec-file``: B-vector file for DWI |
| 55 | + - ``--inverse-dwi-file``: Inverse (PA) DWI for distortion correction |
| 56 | + |
| 57 | + **Primary Outputs:** |
| 58 | + |
| 59 | + The pipeline generates the following directory structure: |
| 60 | + |
| 61 | + .. code-block:: text |
| 62 | + |
| 63 | + <OUTPUT_DIR>/ |
| 64 | + └── <SUBJECT>/ |
| 65 | + └── <SESSION>/ |
| 66 | + ├── anat/ # Preprocessed anatomical images |
| 67 | + ├── dwi/ # Preprocessed diffusion data (if available) |
| 68 | + ├── metrics/ # Quality assessment metrics |
| 69 | + ├── textures/ # Texture feature maps |
| 70 | + └── xfm/ # Transformation files |
| 71 | +
|
| 72 | + .. tab:: Running the Pipeline |
| 73 | + |
| 74 | + **Command Line Usage:** |
| 75 | + |
| 76 | + .. code-block:: bash |
| 77 | +
|
| 78 | + micaflow pipeline \ |
| 79 | + --subject SUB001 \ |
| 80 | + --session SES01 \ |
| 81 | + --output /path/to/output \ |
| 82 | + --data-directory /path/to/data \ |
| 83 | + --t1w-file /path/to/t1w.nii.gz \ |
| 84 | + [options] |
| 85 | +
|
| 86 | + **Additional Options:** |
| 87 | + |
| 88 | + - ``--threads N``: Number of threads to use (default: 1) |
| 89 | + - ``--cpu``: Force CPU computation instead of GPU |
| 90 | + - ``--dry-run``: Show what would be executed without running commands |
| 91 | + |
| 92 | + **Pipeline Configuration:** |
| 93 | + |
| 94 | + The pipeline can also be configured using a YAML file: |
| 95 | + |
| 96 | + .. code-block:: bash |
| 97 | +
|
| 98 | + micaflow pipeline --config-file config.yaml |
| 99 | +
|
| 100 | + .. tab:: Texture Generation |
| 101 | + |
| 102 | + The texture generation component extracts advanced features from neuroimaging data: |
| 103 | + |
| 104 | + .. code-block:: text |
| 105 | +
|
| 106 | + ╔════════════════════════════════════════════════════════════════╗ |
| 107 | + ║ TEXTURE FEATURE EXTRACTION ║ |
| 108 | + ╚════════════════════════════════════════════════════════════════╝ |
| 109 | +
|
| 110 | + This script generates texture feature maps from neuroimaging data using |
| 111 | + various computational approaches. The features include: |
| 112 | + |
| 113 | + - Gradient magnitude computation for edge and boundary detection |
| 114 | + - Relative intensity calculation for normalized tissue contrast |
| 115 | + - Automatic tissue segmentation into gray matter, white matter, and CSF |
| 116 | + - Masked processing to focus analysis on brain regions only |
| 117 | +
|
| 118 | + **Output Features:** |
| 119 | + |
| 120 | + - **Gradient Magnitude Maps**: Highlight tissue boundaries and structural transitions |
| 121 | + - **Relative Intensity Maps**: Normalize intensity patterns across the brain |
| 122 | + - **Segmentation Maps**: Tissue class probabilities |
| 123 | + |
| 124 | +Implementation Details |
| 125 | +--------------------- |
| 126 | + |
| 127 | +The pipeline implementation follows a modular design where each processing step is encapsulated as a separate rule in the Snakefile: |
| 128 | + |
| 129 | +.. code-block:: python |
| 130 | +
|
| 131 | + # Key pipeline rules from Snakefile |
| 132 | + rule skull_strip: |
| 133 | + # Extract brain tissue from T1w/FLAIR images |
| 134 | + |
| 135 | + rule bias_field_correction: |
| 136 | + # Correct intensity non-uniformities |
| 137 | + |
| 138 | + rule synthseg_t1w: |
| 139 | + # AI-based segmentation of T1w images |
| 140 | + |
| 141 | + rule registration_t1w: |
| 142 | + # Register FLAIR to T1w space |
| 143 | + |
| 144 | + rule registration_mni152: |
| 145 | + # Register T1w to standard space |
| 146 | + |
| 147 | + rule run_texture: |
| 148 | + # Generate texture feature maps |
| 149 | + |
| 150 | + # Additional DWI processing rules when enabled |
| 151 | + if RUN_DWI: |
| 152 | + rule dwi_denoise: |
| 153 | + # Remove noise from diffusion images |
| 154 | + |
| 155 | + rule dwi_motion_correction: |
| 156 | + # Correct for head motion in diffusion data |
| 157 | + |
| 158 | + # ... additional DWI rules ... |
| 159 | +
|
| 160 | +Quality Control |
| 161 | +-------------- |
| 162 | + |
| 163 | +The pipeline includes quality assessment metrics to evaluate the performance of critical processing steps: |
| 164 | + |
| 165 | +1. **Registration Accuracy**: Jaccard similarity metrics between registered images |
| 166 | +2. **Transformation Files**: All transformation matrices and warp fields are saved for inspection |
| 167 | +3. **Intermediate Results**: Preprocessed images at each stage for quality checks |
| 168 | + |
| 169 | +For complete implementation details, refer to the `Snakefile <https://github.com/yourusername/micaflow/blob/main/micaflow/resources/Snakefile>`_ in the repository. |
0 commit comments