mouse-brain-mri-pipeline

Integrated Mouse Brain MRI Processing Pipeline

A complete, automated workflow for mouse brain MRI analysis: nnU-Net deep-learning skull stripping, multi-template registration with consensus, and regional volume extraction.

This Hugging Face repository bundles the code, an inference-only (slim) nnU-Net model, and a small example atlas so the pipeline runs end-to-end out of the box. A full/alternative atlas can be swapped in (see Atlas setup).

License note: the license field above is set to other as a placeholder. Set it to whatever license you intend to release your code and model weights under before making the repo public.

Features

• Automated skull stripping — trained nnU-Net model (reported ~99% mean Dice), no manual intervention
• Robust registration — multi-template registration with voxel-wise consensus voting and confidence maps
• Regional volume extraction — per-region volumes from a provided structure key
• Single-file and batch processing
• Configurable & reproducible — all parameters in a JSON config, with detailed logging

About the bundled model (slim / inference-only)

The checkpoint in models/ has been stripped to the tensors needed for inference (network_weights, trainer_name, init_args, inference_allowed_mirroring_axes). Optimizer state, the duplicate checkpoint_latest.pth, and training artifacts (logs, progress.png, debug.json) were removed. This reduces the model from ~478 MB to ~125 MB with no change to inference output. It is not suitable for resuming training.

Getting the repository

# Requires git-lfs (https://git-lfs.com) for the .pth weights
git lfs install
git clone https://huggingface.co/<your-username>/<your-repo-name>
cd <your-repo-name>

Or download just the weights in Python:

from huggingface_hub import snapshot_download
snapshot_download(repo_id="<your-username>/<your-repo-name>", local_dir="mouse_brain_pipeline")

Installation

1. Create the conda environment

conda env create -f environment.yaml
conda activate mouse-mri

2. Verify the model layout

The bundled model is already in place at:

models/
  Dataset001_MouseBrain/
    nnUNetTrainer__nnUNetPlans__3d_fullres/
      dataset.json
      plans.json
      fold_0/
        checkpoint_best.pth        # slim, inference-only

pipeline_config.json already points nnunet.model_path at models, so no change is needed.

3. Atlas: bundled example & alternatives

A small example atlas is bundled at example_atlas/NeAt_in_vivo/, and pipeline_config.json already points atlas_parent at it — so registration works out of the box with no extra download.

It contains skull-stripped NeAt in-vivo templates (C57BL/6J) plus matching label maps. Note the upstream atlas ships only whole-head templates; the pipeline registers skull-stripped subjects, so these skull-stripped templates (a GPLv3 derivative, not in the upstream repo) are provided here for convenience. See example_atlas/NeAt_in_vivo/README.md for provenance, license, and citation.

To use the full multi-template atlas, the ex-vivo atlas, or a different strain, download it from the upstream source and point atlas_parent at a folder containing template/ (skull-stripped) and label/ subdirectories:

• GitHub: https://github.com/dama-lab/mouse-brain-atlas (NeAt/in_vivo)
• Zenodo (DOI): https://zenodo.org/badge/latestdoi/166476589

"atlas_parent": "/path/to/mouse-brain-atlas/NeAt/in_vivo"

Please cite the original atlas authors (Ma et al., 2005; 2008) if you use it — see Citation.

Usage

python mouse_brain_pipeline.py <input_path> --config pipeline_config.json [OPTIONS]

• <input_path> — a single NIfTI file (.nii/.nii.gz) or a directory of them
• --config — path to pipeline_config.json

Examples

# Single image
python mouse_brain_pipeline.py /path/to/subject_01.nii --config pipeline_config.json

# Batch (directory)
python mouse_brain_pipeline.py /path/to/images/ --config pipeline_config.json

# Custom output location, more registration runs / workers
python mouse_brain_pipeline.py /path/to/images/ --config pipeline_config.json \
    --output-root /path/to/results/ --runs 20 --workers 8

Command-line options

A note on input resolution

The model expects voxel spacing of ~0.125 × 0.125 × 0.125 mm (125 µm), matching the training data. By default the validator auto-resamples mismatched images to the expected resolution so segmentation works without intervention. Pass --interactive to be prompted (exit / resample / custom spacing) instead.

Output structure

<output_root>/
├── skull_stripped/<subject_id>/     # skull_stripped.nii, brain_mask.nii
├── registration/<subject_id>/       # reference_transformed.nii, registered_labels_consensus.nii,
│                                     # registration_confidence.nii, consensus_verification.png
├── volumes/<subject_id>/            # brain_volumes.csv
├── tmp/<subject_id>/                # temporary files (auto-deleted unless --debug)
└── processing_log_YYYYMMDD_HHMMSS.json

Volume CSV columns

Label, Region_Name, Hemisphere, Voxel_Count, Volume_mm3, Mean_Intensity.

Pipeline stages

1. Skull stripping (nnU-Net) — fully automated brain extraction; handles .nii and .nii.gz.
2. Multi-template registration (ANTs) — tests multiple atlas templates, runs registration repeatedly, builds a consensus label map by voxel-wise voting, and emits a confidence map.
3. Volume extraction — per-region voxel counts and volumes (mm³), hemisphere split out into its own column.

Troubleshooting

• "nnU-Net is not installed" — conda activate mouse-mri then pip install nnunetv2==2.5.1.
• "Model not found" / "Cannot find dataset" — confirm files exist under models/Dataset001_MouseBrain/nnUNetTrainer__nnUNetPlans__3d_fullres/fold_0/.
• Atlas errors during registration — confirm atlas_parent points at the folder containing template/ and label/.
• Slow processing — nnU-Net on CPU is ~2–5 min/image; set "device": "cuda" in the config for GPU. Tune --workers for registration.

Citation

If you use this pipeline, please cite the underlying tools and the atlas:

• nnU-Net — Isensee et al., nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation, Nature Methods (2021).
• ANTs — Avants et al., A reproducible evaluation of ANTs similarity metric performance in brain image registration, NeuroImage (2011).
• NeAt atlas — Ma et al., In Vivo 3D Digital Atlas Database of the Adult C57BL/6J Mouse Brain by Magnetic Resonance Microscopy, Front. Neuroanat. (2008); Ma et al., Neuroscience (2005). Atlas repository: https://github.com/dancebean/mouse-brain-atlas (GPLv3).

License

TODO: choose and state your license for the pipeline code and model weights here, and update the license field in the header above.

Note the bundled example atlas (example_atlas/NeAt_in_vivo/) is a derivative of the NeAt atlas and is distributed under the GNU GPL v3, with its own LICENSE and provenance/citation in that folder. It is a separate work aggregated alongside the pipeline; it does not impose GPLv3 on your own code.