SnakePrep: Automated MRI Preprocessing Pipeline

SnakePrep is a modular, Snakemake-based workflow for preprocessing T1-weighted brain MRI datasets.
It integrates FreeSurfer, ANTs, SynthSeg, and intensity normalization tools to streamline large-scale MRI analysis.

The preprocessing steps resemble those in https://github.com/LemuelPuglisi/turboprep

---

Features

• Batch preprocessing of T1w MRI images.
• Bias field correction using ANTs N4 algorithm.
• Affine registration to MNI152 template with ANTs.
• Skull-stripping and brain extraction via SynthStrip.
• Tissue segmentation using SynthSeg.
• Intensity normalization using WhiteStripe.
• Quality control metrics automatically generated for affine registration and segmentation.

---

Requirements

• OS: Linux (tested on Ubuntu 20.04+)
• Python: 3.11 recommended
• GPU: Optional, required for SynthSeg processing
• Dependencies (managed via Conda or virtual environment):
  • Snakemake
  • ANTs (antspyx)
  • Nibabel
  • Intensity-normalization (WhiteStripe)
  • FreeSurfer 8.1.0
  • SynthSeg (surfa)
  • Matplotlib

---

Installation

1. Clone the repository

git clone https://github.com/yourusername/SnakePrep.git
cd SnakePrep

2. Create and activate the Conda environment

conda create -n snakeprep -c conda-forge -c bioconda snakemake antspyx nibabel intensity-normalization
conda activate snakeprep

3. Configure FreeSurfer

Set your FreeSurfer paths and license:

export FREESURFER_HOME=/home/maia-user/opt/freesurfer-8.1.0
export FS_LICENSE=$FREESURFER_HOME/license.txt
export PATH=$FREESURFER_HOME/bin:$PATH

---

Configuration

Edit config/config.yaml to set:

raw_mri_path: "/path/to/raw/mri/dataset"
outdir: "/path/to/output/directory"
template: "/path/to/mni_icbm152_t1_tal_nlin_asym_09c.nii"
fs_license: "/path/to/freesurfer/license.txt"

• raw_mri_path: directory containing subfolders for each subject with their T1w image.
• outdir: directory where preprocessed outputs will be saved.
• template: MNI template for registration.
• fs_license: path to FreeSurfer license file.

---

Usage

Run the pipeline with Snakemake:

snakemake --cores 7 --resources gpu=1 mem_mb=14010 --use-conda --rerun-incomplete --rerun-triggers mtime --keep-going

• --cores: Number of CPU threads to use.
• --resources gpu=1: Ensures only one GPU-intensive job runs at a time.
• --use-conda: Automatically activates environment for each rule.

---

Output Structure

After running the pipeline, your output directory will have:

outdir/
├── <SUBJECT_ID>/
│   └── mri/
│       ├── orig/001.mgz           # Original T1w image
│       ├── orig_conform.mgz       # Conformed image
│       ├── orig_nu.mgz            # N4 bias-corrected
│       ├── orig_nu_reg.nii.gz     # Registered to MNI template
│       ├── brain.mgz               # Skull-stripped brain
│       ├── aparc+aseg.mgz         # SynthSeg segmentation
│       ├── brain_reg_ws_norm.nii.gz  # WhiteStripe normalized brain
│       └── qc_*.csv                # Quality control metrics

---

Notes

• The pipeline supports GPU acceleration for SynthSeg; rules are configured to avoid simultaneous GPU usage.
• Registration quality is automatically measured using mutual information.
• Intensity normalization uses WhiteStripe; images should be skull-stripped prior to normalization.

---

License

This project is licensed under the MIT License. See LICENSE for details.