Metadata-Version: 2.4
Name: micaflow
Version: 1.0.2
Summary: MicaFlow MRI processing pipeline
Author-email: Ian Goodall-Halliwell <goodallhalliwell@gmail.com>
License: GPL 3.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: absl-py
Requires-Dist: acres
Requires-Dist: antspyx
Requires-Dist: anyio
Requires-Dist: appdirs
Requires-Dist: astunparse
Requires-Dist: attrs
Requires-Dist: batchgenerators
Requires-Dist: blosc
Requires-Dist: certifi
Requires-Dist: charset-normalizer
Requires-Dist: ci-info
Requires-Dist: click
Requires-Dist: ConfigArgParse
Requires-Dist: connection_pool
Requires-Dist: contourpy
Requires-Dist: cycler
Requires-Dist: datrie
Requires-Dist: deepdiff
Requires-Dist: dipy
Requires-Dist: docutils
Requires-Dist: dpath
Requires-Dist: dynamic_network_architectures
Requires-Dist: einops
Requires-Dist: etelemetry
Requires-Dist: exceptiongroup
Requires-Dist: fastjsonschema
Requires-Dist: fft-conv-pytorch
Requires-Dist: filelock
Requires-Dist: flatbuffers
Requires-Dist: fonttools
Requires-Dist: fsspec
Requires-Dist: future
Requires-Dist: gast
Requires-Dist: gitdb
Requires-Dist: GitPython
Requires-Dist: google-pasta
Requires-Dist: graphviz
Requires-Dist: grpcio
Requires-Dist: httpcore
Requires-Dist: httpx
Requires-Dist: humanfriendly
Requires-Dist: idna
Requires-Dist: imagecodecs
Requires-Dist: imageio
Requires-Dist: importlib_resources
Requires-Dist: isodate
Requires-Dist: joblib
Requires-Dist: jsonschema
Requires-Dist: jsonschema-specifications
Requires-Dist: jupyter_core
Requires-Dist: keras
Requires-Dist: kiwisolver
Requires-Dist: lazy_loader
Requires-Dist: libclang
Requires-Dist: looseversion
Requires-Dist: lxml
Requires-Dist: Markdown
Requires-Dist: markdown-it-py
Requires-Dist: MarkupSafe
Requires-Dist: matplotlib
Requires-Dist: mdurl
Requires-Dist: ml-dtypes
Requires-Dist: mpmath
Requires-Dist: msgpack
Requires-Dist: namex
Requires-Dist: nbformat
Requires-Dist: ndindex
Requires-Dist: networkx
Requires-Dist: nibabel
Requires-Dist: nipype
Requires-Dist: numexpr
Requires-Dist: numpy
Requires-Dist: opt_einsum
Requires-Dist: optree
Requires-Dist: orderly-set
Requires-Dist: packaging
Requires-Dist: pandas
Requires-Dist: patsy
Requires-Dist: pillow
Requires-Dist: plac
Requires-Dist: platformdirs
Requires-Dist: protobuf
Requires-Dist: prov
Requires-Dist: psutil
Requires-Dist: PuLP<2.8
Requires-Dist: puremagic
Requires-Dist: py-cpuinfo
Requires-Dist: pydicom
Requires-Dist: pydot
Requires-Dist: Pygments
Requires-Dist: PyHySCO
Requires-Dist: pyparsing
Requires-Dist: python-gdcm
Requires-Dist: pytz
Requires-Dist: PyYAML
Requires-Dist: rdflib
Requires-Dist: referencing
Requires-Dist: requests
Requires-Dist: reretry
Requires-Dist: rich
Requires-Dist: rpds-py
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: seaborn
Requires-Dist: setuptools-scm
Requires-Dist: SimpleITK
Requires-Dist: simplejson
Requires-Dist: six
Requires-Dist: smart-open
Requires-Dist: smmap
Requires-Dist: snakemake
Requires-Dist: statsmodels
Requires-Dist: stopit
Requires-Dist: sympy
Requires-Dist: tabulate
Requires-Dist: tensorboard
Requires-Dist: tensorboard-data-server
Requires-Dist: tensorflow
Requires-Dist: termcolor
Requires-Dist: threadpoolctl
Requires-Dist: throttler
Requires-Dist: tifffile
Requires-Dist: tomli
Requires-Dist: toposort
Requires-Dist: torch
Requires-Dist: tqdm
Requires-Dist: traitlets
Requires-Dist: traits
Requires-Dist: trx-python
Requires-Dist: typing_extensions
Requires-Dist: tzdata
Requires-Dist: webcolors
Requires-Dist: Werkzeug
Requires-Dist: wrapt
Requires-Dist: yacs
Requires-Dist: yte
Requires-Dist: colorama>=0.4
Requires-Dist: lamareg>=1.5.1
Requires-Dist: nnunetv2
Requires-Dist: nilearn
Dynamic: license-file

![MICAFlow logo](https://raw.githubusercontent.com/MICA-MNI/micaflow/main/docs/source/_static/images/logo.png)
# MICAFlow: Accessible, fast, and pythonic MRI processing pipeline

<div align="left">

[![Version](https://img.shields.io/github/v/tag/MICA-MNI/micaflow)](https://github.com/MICA-MNI/micaflow)
[![PyPI version](https://img.shields.io/pypi/v/micaflow.svg)](https://pypi.org/project/micaflow/)
[![PyPI downloads](https://img.shields.io/pypi/dm/micaflow.svg)](https://pypi.org/project/micaflow/)
[![GitHub issues](https://img.shields.io/github/issues/MICA-MNI/micaflow?color=brightgreen)](https://github.com/MICA-MNI/micaflow/issues)
[![GitHub stars](https://img.shields.io/github/stars/MICA-MNI/micaflow.svg?style=flat&label=%E2%AD%90%EF%B8%8F%20stars&color=brightgreen)](https://github.com/MICA-MNI/micaflow/stargazers)

</div>

MICAFlow is a comprehensive neuroimaging pipeline designed for processing structural and diffusion MRI data. It offers modular components that can be used as part of a cohesive workflow or as standalone tools.

## Overview

MICAFlow provides a robust and flexible framework for neuroimaging processing. By chaining together deep learning-based segmentation and advanced numerical solutions, it generates precise outputs even for modalities with low signal-to-noise ratio or strong geometric distortions.

## Features

- **Structural MRI Processing**: T1w and FLAIR image processing
- **Diffusion MRI Processing**: Complete pipeline for DWI processing
- **Brain Extraction**: SynthSeg-based brain extraction with optional cerebellum removal
- **Deep Learning Segmentation**: SynthSeg for brain segmentation and parcellation
- **Image Registration**: Multi-modal coregistration and spatial normalization to standard spaces
- **Texture Features**: Advanced texture feature generation
- **Quality Control**: Built-in QC metrics and visualization
- **Batch Processing**: Automated BIDS directory scanning and processing
- **Brain-Extracted Outputs**: Optional dedicated directory for all skull-stripped images
- **Temporary File Management**: Option to preserve intermediate files for debugging
- **Modular Design**: Components can be used independently or as a complete pipeline
- **Flexible Configuration**: Via command line arguments or YAML configuration files

## Installation

```bash
pip install 
# Verify installation
micaflow
```

## Usage

MICAFlow can be used as a complete pipeline or as individual modules:

### Running the Full Pipeline

```bash
# Basic usage with T1w only
micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /path/to/data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --output /output/path --cores 4

# With FLAIR image
micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /path/to/data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --flair-file sub-001_ses-01_FLAIR.nii.gz --output /output/path \
  --cores 4

# With diffusion data
micaflow pipeline --subject sub-001 --session ses-01 \
  --data-directory /path/to/data --t1w-file sub-001_ses-01_T1w.nii.gz \
  --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 \
  --output /output/path --cores 4
```

### Batch Processing (BIDS)

To process an entire BIDS dataset automatically using the batch command:

```bash
micaflow bids --bids-dir /path/to/bids_root --output-dir /path/to/derivatives \
  --cores 4 --gpu
```

This command will:
1. Scan the BIDS directory for valid subjects and sessions.
2. Automatically identify T1w, FLAIR (optional), and DWI (optional) files based on suffixes.
3. Run the pipeline sequentially for each session found.
4. Generate a `micaflow_runs_summary.json` in the output directory tracking execution status.

**key arguments:**
- `--bids-dir`: Root path to the BIDS dataset.
- `--output-dir`: Path where derivatives will be saved.
- `--participant-label`: (Optional) Space-separated list of subject IDs to process (e.g., `001 002`).
- `--session-label`: (Optional) Space-separated list of session IDs to process.
- `--t1w-suffix`, `--dwi-suffix`, etc.: Customize matching patterns for input files.

### Using Individual Modules

Each module can be used independently:

#### Brain Extraction

```bash
micaflow bet --input t1w.nii.gz --output brain.nii.gz --parcellation segmentation.nii.gz --output-mask mask.nii.gz
```

#### Brain Segmentation (SynthSeg)

```bash
micaflow synthseg --i t1w.nii.gz --o segmentation.nii.gz --parc --fast --threads 4
```

#### Image Registration

```bash
micaflow coregister --fixed-file target.nii.gz --moving-file source.nii.gz \
  --output registered.nii.gz --warp-file warp.nii.gz --affine-file affine.mat
```

#### Apply Transformations

```bash
micaflow apply_warp --moving image.nii.gz --reference target.nii.gz \
  --warp warp.nii.gz --affine affine.mat --output warped.nii.gz
```

#### Diffusion Processing

```bash
# Denoise DWI data
micaflow denoise --input dwi.nii.gz --bval dwi.bval --bvec dwi.bvec --output denoised_dwi.nii.gz

# Motion correction
micaflow motion_correction --denoised denoised_dwi.nii.gz --input-bvecs dwi.bvec --output-bvecs corrected.bvec --output motion_corrected_dwi.nii.gz

# Susceptibility distortion correction
micaflow SDC --input motion_corrected_dwi.nii.gz --reverse-image reverse_phase_dwi.nii.gz \
  --output corrected_dwi.nii.gz --output-warp sdc_warpfield.nii.gz

# Compute DTI metrics
micaflow compute_fa_md --input preprocessed_dwi.nii.gz --bval dwi.bval --bvec dwi.bvec \
  --output-fa fa_map.nii.gz --output-md md_map.nii.gz
```

#### Texture Feature Extraction

```bash
micaflow texture_generation --input image.nii.gz --mask mask.nii.gz --output texture_features
```

## Pipeline Workflow

The pipeline performs the following processing steps:

1. **Brain Extraction**: Using SynthSeg-based segmentation for T1w, FLAIR, and DWI
   - Optionally remove cerebellum with `--rm-cerebellum`
2. **Bias Field Correction**: Using N4 bias field correction
3. **Brain Segmentation**: Using SynthSeg for T1w and FLAIR
4. **Registration**: 
   - FLAIR to T1w space
   - T1w to MNI152 standard space
5. **DWI Processing** (if enabled):
   - Denoising with Patch2Self
   - Motion correction
   - Susceptibility distortion correction
   - Tensor fitting and DTI metrics calculation
   - Registration to T1w space
6. **Texture Feature Generation**: On normalized images
7. **Brain-Extracted Outputs** (if `--extract-brain` enabled):
   - Creates skull-stripped versions of all outputs in dedicated directory
   - Normalized versions also created
8. **Quality Control**: Calculating quality metrics
9. **Cleanup**: Removes temporary files (unless `--keep-temp` is specified)

## Output Structure

The pipeline creates a structured output directory:

```
output/
├── <subject>/
│   └── <session>/
│       ├── anat/             # Anatomical images (brain-extracted, bias-corrected)
│       ├── dwi/              # Processed diffusion data and DTI metrics
│       ├── metrics/          # Quality metrics and DICE scores
│       ├── textures/         # Texture features
│       └── xfm/              # Transformation matrices and warps
```

## Configuration

MICAFlow can be configured via:

1. **Command Line Arguments**: For quick setup and individual module usage
2. **Configuration File**: YAML file for complex setups (specify with `--config-file`)
3. **Default Configuration**: Located in config.yaml

## System Requirements

- **CPU**: Multi-core recommended for parallel processing
- **RAM**: 8GB minimum, 16GB+ recommended
- **GPU**: Optional but recommended for faster processing (CUDA compatible)
- **Disk Space**: Depends on dataset size, minimum 10GB recommended

## Supported Image Formats

- NIfTI (.nii, .nii.gz)
- BIDS-compatible directory structures

## Support and Contact


For issues, questions or feature requests, please open an issue on the GitHub repository.
