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

MRSIPrep is a preprocessing and derivative-generation pipeline for already quantified whole-brain MRSI maps, run as a BIDS App via Docker.

version e2e mni-norm e2e parc-con docs Codacy Badge test dataset doi docker pypi 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, regional statistics, and metabolic connectivity. It is derived from the implementation in MRSI-Metabolic-Connectome and preserves the CHUV academic non-commercial research license.

Every report includes the acquisition's MRSinMRS minimum-reporting-standard sequence parameters (read from an optional mrsinmrs.json at the BIDS root) and a citation section, so results are easy to trace back to both the software and the acquisition protocol used. Published-study parameter sets can be reproduced directly with --config-preset <name> (see --list-presets); the report then credits the source publication.

MRSIPrep pipeline schematic

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 (derivatives/mrsi-orig/).

Published on Zenodo: 10.5281/zenodo.21477047 (CC0). See PUBLIC_DATASET.md in the repository for full download and usage instructions. This dataset is also the fixture for MRSIPrep's own automated end-to-end pipeline test.

What it uses

  • Nipype as the workflow engine: each subject/session is a cached, per-step Nipype workflow, so a rerun of an already-processed recording skips finished steps instead of recomputing them.

  • ANTs for MRSI↔T1w and T1w↔MNI registration.

  • FreeSurfer (mri_synthseg, recon-all, mri_vol2vol) for brain extraction, cortical/subcortical parcellation, and surface reconstruction.

  • FSL FAST for tissue-class probability segmentation.

  • PETPVC for partial-volume correction of MRSI maps.

  • Chimera for multi-atlas cortical/subcortical parcellation fusion.

  • TemplateFlow for the bundled MNI152 reference templates and atlases.

Pipelines

MRSIPrep runs in one of two modes, selected with --mode:

  • mni-norm (MNI normalization, default) — registers MRSI maps to a SynthSeg-extracted T1w image, generates SynthSeg+FAST tissue probability maps, applies PETPVC partial-volume correction (--no-pvc to disable), resamples to the requested output spaces, and parcellates with SynthSeg cortical/subcortical labels. No Chimera, no recon-all. This is the fast default path for anatomical coverage and CRLB reporting.

  • parc-con (parcellation and connectivity) — adds a choice of Chimera multi-atlas or bundled MNI-atlas parcellation, plus optional perturbation-based connectivity matrices.

Both modes share the same MRSI filtering, quality-masking, and T1w/MNI normalization machinery; parc-con mode is a superset of mni-norm outputs.

Design Principles

MRSIPrep was designed according to four main principles: reproducibility, modularity, transparency, and analysis agnosticism.

Reproducibility

The framework is distributed as open-source software and can be executed in containerized environments to minimize differences across computing platforms.

Modularity

Each processing stage is implemented as an independent module, allowing users to enable, disable, or replace specific steps according to their acquisition protocol and scientific question.

Transparency

MRSIPrep generates automated quality-control reports summarizing spatial registration, metabolite coverage, voxel-level quality metrics, tissue composition, and atlas projection.

Analysis Agnosticism

MRSIPrep does not impose a specific downstream analysis. Instead, it generates standardized derivatives that can be used for voxelwise analyses, regional analyses, metabolic connectomics, gradient mapping, or machine-learning workflows.

Workflow Architecture

Inputs

MRSIPrep starts from quantified metabolite maps and associated quality metrics. Typical inputs include metabolite concentration maps, Cramér-Rao lower bound maps, signal-to-noise ratio maps, linewidth maps, anatomical T1-weighted images, tissue probability maps, and optional atlas files.

Processing Steps

The core processing workflow includes:

  1. MRSI-BIDS-compatible data import.

  2. Voxelwise quality assessment.

  3. Brain masking and coverage estimation.

  4. Tissue fraction estimation.

  5. CSF and tissue correction.

  6. Spatial registration to anatomical and template spaces.

  7. Atlas projection and regional summary extraction.

  8. Generation of voxelwise, regional, and connectomics-ready derivatives.

  9. Automated quality-control reporting.

Quality-Control Framework

MRSIPrep summarizes quality at the voxel, regional, and subject levels. Voxel inclusion can be based on metabolite-specific criteria such as linewidth, signal-to-noise ratio, Cramér-Rao lower bounds, tissue composition, and spatial coverage.

License

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

Acknowledgments

Substantial implementation logic is cropped and refactored by Federico Lucchetti and Edgar Céléreau from MRSI-Metabolic-Connectome. MRSIPrep builds on the work of the ANTs, FreeSurfer, FSL, PETPVC, Chimera, and TemplateFlow projects.

Publications

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

  • Lucchetti, F., Céléreau, E., Steullet, P., Alemán-Gómez, Y., Hagmann, P., Klauser, A., & Klauser, P. (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

  • Céléreau, E., Lucchetti, F., Alemán-Gómez, Y., Dwir, D., Cleusix, M., Ledoux, J.-B., Jenni, R., Conchon, C., Bach Cuadra, M., Schilliger, Z., Solida, A., Armando, M., Plessen, K. J., Hagmann, P., Conus, P., Klauser, A., & Klauser, P. (2026). High-resolution whole-brain magnetic resonance spectroscopic imaging in youth at risk for psychosis. Imaging Neuroscience, 4. doi:10.1162/imag.a.1276