Metadata-Version: 2.4
Name: mrsiprep
Version: 2.0.6
Summary: BIDS-like preprocessing pipeline for quantified whole-brain MRSI derivatives
Author-email: Federico Lucchetti <federico.lucchetti@unil.ch>
License: CHUV academic non-commercial research license
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: nibabel
Requires-Dist: nilearn
Requires-Dist: matplotlib
Requires-Dist: scikit-image
Requires-Dist: rich
Requires-Dist: nipype>=1.8
Requires-Dist: templateflow
Provides-Extra: ants
Requires-Dist: antspyx; extra == "ants"
Provides-Extra: gui
Requires-Dist: PyQt6; extra == "gui"
Provides-Extra: command-builder
Requires-Dist: streamlit; extra == "command-builder"
Provides-Extra: all
Requires-Dist: antspyx; extra == "all"
Requires-Dist: PyQt6; extra == "all"
Requires-Dist: streamlit; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: test-e2e
Requires-Dist: requests; extra == "test-e2e"
Dynamic: license-file

# *MRSIPrep*: A Robust Preprocessing Pipeline for Whole-Brain MRSI Data



![version](https://img.shields.io/badge/version-v2.0.0-blue)
[![e2e full pipeline](https://img.shields.io/github/actions/workflow/status/MRSI-Psychosis-UP/MRSIPrep/e2e-full-pipeline.yml?label=e2e%20full%20pipeline&color=success)](https://github.com/MRSI-Psychosis-UP/MRSIPrep/actions/workflows/e2e-full-pipeline.yml)
[![codecov](https://codecov.io/gh/MRSI-Psychosis-UP/MRSIPrep/branch/main/graph/badge.svg)](https://codecov.io/gh/MRSI-Psychosis-UP/MRSIPrep)
[![docs](https://app.readthedocs.org/projects/mrsiprep/badge/?version=stable)](https://mrsiprep.readthedocs.io/en/stable/)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/55f24973247f41bbb27885f6b6375389)](https://app.codacy.com/gh/MRSI-Psychosis-UP/MRSIPrep/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![test dataset doi](https://img.shields.io/badge/test%20dataset%20doi-10.5281%2Fzenodo.21477047-blue)](https://doi.org/10.5281/zenodo.21477047)
[![docker](https://img.shields.io/badge/docker-mrsiup%2Fmrsiprep-blue?logo=docker&logoColor=white)](https://hub.docker.com/r/mrsiup/mrsiprep)
[![pypi](https://img.shields.io/pypi/v/mrsiprep?logo=pypi&logoColor=white)](https://pypi.org/project/mrsiprep/)
[![license](https://img.shields.io/badge/license-academic--non--commercial-lightgrey)](LICENSE)

## About

*MRSIPrep* is a magnetic resonance spectroscopic imaging (MRSI) data
preprocessing pipeline that is designed to provide an easily accessible,
robust interface requiring minimal user input, while providing easily
interpretable and comprehensive quality-control reporting. It performs basic
processing steps (registration to anatomical and template space, tissue
segmentation, partial-volume correction, atlas projection, etc.) on already
quantified whole-brain MRSI maps, providing outputs that can be easily
submitted to a variety of group-level analyses, including
[voxel-based analysis](https://github.com/MRSI-Psychosis-UP/VLAD), regional
statistics, and metabolic connectivity.

**Full documentation, installation, and usage instructions are on
[Read the Docs](https://mrsiprep.readthedocs.io/en/stable/).**

![MRSIPrep pipeline schematic](docs/figures/pipeline_schematic.png)

## Design Principles

MRSIPrep was designed according to four main principles:

- **Reproducibility** — distributed as open-source software, executed in
  containerized environments to minimize differences across computing
  platforms.
- **Modularity** — each processing stage is an independent module, so users
  can enable, disable, or replace specific steps according to their
  acquisition protocol and scientific question.
- **Transparency** — automated quality-control reports summarize spatial
  registration, metabolite coverage, voxel-level quality metrics, tissue
  composition, and atlas projection, including the acquisition's
  [MRSinMRS](https://pubmed.ncbi.nlm.nih.gov/33559967/) sequence parameters
  (from an optional `mrsinmrs.json`) and a citation section. Published-study
  parameter sets can be reproduced with `--config-preset <name>`
  (see `--list-presets`), which also credits the source publication in the
  report.
- **Analysis agnosticism** — MRSIPrep does not impose a specific downstream
  analysis; it generates standardized derivatives usable for voxelwise
  analyses, regional analyses, metabolic connectomics, gradient mapping, or
  machine-learning workflows.

See [Read the Docs](https://mrsiprep.readthedocs.io/en/stable/) for the full
workflow architecture and quality-control framework.

## Repository Structure

The `mrsiprep/` package is organized by processing stage, matching the
pipeline's modular design:

```
mrsiprep/
├── cli/            Command-line entry point and argument parsing
├── config/         Default parameters, literature T1/T2 values, nucleus and template definitions
├── connectivity/   Metabolic connectivity matrix construction and export
├── interfaces/     Wrappers around external tools (ANTs, FSL, Chimera/FreeSurfer, BIDS import)
├── io/             BIDS discovery, MRSinMRS parsing, derivative I/O, input validation
├── mrsi/           MRSI-specific operations: masking, resampling, spike filtering, T1 correction, orientation
├── parcellation/   Atlas registration, SynthSeg/Chimera parcellation, region labeling
├── qc/             Quality-control metrics (e.g. ventricle detection)
├── registration/   MRSI-to-T1w and T1w-to-template registration backends and transforms
├── reports/        HTML QC report generation
├── tissue/         Tissue segmentation and partial-volume fraction computation
├── utils/          Shared helpers: logging, provenance tracking, image utilities
└── workflows/      Nipype workflow graphs tying the stages above into the full pipeline
```

Other top-level directories: `docs/` (Read the Docs source), `docker/` (image
build scripts, see `docker/README.md`), `wrapper/` (the `mrsiprep-docker`
PyPI package, a dependency-free Python wrapper that runs the Docker image
using normal BIDS App syntax), `tests/` (unit and integration tests),
`experiments/` (benchmark and validation scripts used to produce the
manuscript's results, not part of the installed package), and `examples/`
(runnable usage examples referenced from the docs).

## Test Dataset

A small, public, synthetic MRSI dataset — **SynthMRSI-Project** — is
available for anyone to download and run through MRSIPrep themselves,
without needing access to real MRSI acquisitions. It pairs real T1w
anatomical images (subsetted from two CC0 OpenNeuro datasets) with
model-synthesized MRSI signal and empirical CRLB/SNR/FWHM quality maps,
following MRSIPrep's own raw-MRSI-input convention.

- Published on Zenodo: [10.5281/zenodo.21477047](https://doi.org/10.5281/zenodo.21477047) (CC0)
- Full download and usage instructions: [PUBLIC_DATASET.md](PUBLIC_DATASET.md)
- Used as the fixture for this repo's automated end-to-end pipeline test (see
  the "e2e full pipeline" badge above)

**SynthMRSI-Project is never modified after publication** — its Zenodo
record is fixed and citable. A separate, unpublished internal dataset,
**SynthMRSI-VBA-Project**, is used instead for voxel-based-analysis
validation work (region-based abnormality injection, ANTs-vs-FSL
registration-backend comparison via `randomise`). It shares the same T1w
subjects as SynthMRSI-Project but is generated independently with
`--inject-abnormal`, so it can carry deliberately-injected ground-truth
abnormalities without touching the published, immutable dataset. See
[`synthMRSI/SYNTHMRSI_PROJECT.md`](synthMRSI/SYNTHMRSI_PROJECT.md) for the
full generation and validation commands.

## Use Cases

Code derived from this pipeline has been used in the following peer-reviewed
publications:

- Lucchetti, F., et al. (2025). Constructing the human brain metabolic
  connectome with MR spectroscopic imaging reveals cerebral biochemical
  organization. *Nature Communications*, 16.
  [doi:10.1038/s41467-025-66124-w](https://doi.org/10.1038/s41467-025-66124-w)
- Céléreau, E., et al. (2026). High-resolution whole-brain
  magnetic resonance spectroscopic imaging in youth at risk for psychosis.
  *Imaging Neuroscience*, 4.
  [doi:10.1162/imag.a.1276](https://doi.org/10.1162/imag.a.1276)
- Céléreau, E., et al. (2026). Sex differences in brain metabolism assessed
  with whole-brain magnetic resonance spectroscopic imaging. *bioRxiv*,
  2026-06.
  [doi:10.64898/2026.06.30.735476](https://doi.org/10.64898/2026.06.30.735476)

## How to Cite

If you use MRSIPrep in your research, please cite:

> Lucchetti, F., Céléreau, E., Jenni, R., Ledoux, J.-B., Eliez, S., Delavari,
> F., Hagmann, P., Alemán-Gómez, Y., Klauser, A., & Klauser, P. (2026).
> MRSIPrep: A Standardized Post-Quantification Framework for Preprocessing
> Whole-Brain Magnetic Resonance Spectroscopic Imaging. *bioRxiv*.
> [doi:10.64898/2026.09.11.750896](https://doi.org/10.64898/2026.09.11.750896)

```bibtex
@article{lucchetti2026mrsiprep,
  title={MRSIPrep: A Standardized Post-Quantification Framework for Preprocessing Whole-Brain Magnetic Resonance Spectroscopic Imaging},
  author={Lucchetti, Federico and Celereau, Edgar and Jenni, Raoul and Ledoux, Jean-Baptiste and Eliez, Stephan and Delavari, Farnaz and Hagmann, Patric and Aleman-Gomez, Yasser and Klauser, Antoine and Klauser, Paul},
  journal={bioRxiv},
  pages={2026--09},
  year={2026},
  publisher={Cold Spring Harbor Laboratory}
}
```

## License

MRSIPrep is distributed under the CHUV academic non-commercial research
license; see [LICENSE](LICENSE) for the full text.

## Attribution

Substantial implementation logic is cropped and refactored by Federico Lucchetti and Edgar Céléreau. The original
license is included in `LICENSE`.

## Acknowledgments

MRSIPrep builds on the work of the ANTs, FreeSurfer, FSL, PETPVC, Chimera,
and TemplateFlow projects.
