mrsiprep 0.1.0__tar.gz

mrsiprep-0.1.0/LICENSE

@@ -0,0 +1,57 @@
+SOFTWARE LICENSE AGREEMENT FOR ACADEMIC NON-COMMERCIAL RESEARCH PURPOSES ONLY
+
+Between CHUV (hereby described as “LICENSOR”) and LICENSEE
+
+Effective at the date the downloading is completed (“EFFECTIVE DATE”).
+
+1. LICENSE
+
+1.1 Grant
+
+Subject to the terms of this Agreement, LICENSOR hereby grants to LICENSEE, solely for academic non-commercial research purposes, a non-exclusive, non-transferable license to: (a) download, compile, execute, display and utilize the PROGRAM and (b) create bug fixes and modify the PROGRAM.
+
+LICENSEE hereby automatically grants to LICENSOR a non-exclusive, royalty-free, irrevocable license to any LICENSEE bug fixes or modifications to the PROGRAM with rights to sublicense and/or distribute. LICENSEE agrees to provide any such modifications and bug fixes to LICENSOR promptly upon their creation.
+
+1.2 No Sublicensing or Additional Rights
+
+LICENSEE shall not sublicense or distribute the PROGRAM, in whole or in part, without prior written permission from LICENSOR.
+
+LICENSEE shall ensure that all of its users agree to the terms of this Agreement.
+
+LICENSEE further agrees that it shall not put the PROGRAM on a network, server, or other similar technology that may be accessed by anyone other than the LICENSEE and its employees and users who have agreed to the terms of this Agreement.
+
+1.3 License Limitations
+
+Nothing in this Agreement shall be construed to confer any rights upon LICENSEE by implication, estoppel, or otherwise to any computer software, trademark, intellectual property, or patent rights of LICENSOR, or of any other entity, except as expressly granted herein.
+
+LICENSEE agrees that the PROGRAM, in whole or part, shall be used only for academic purposes excluding any use for any commercial purposes, including without limitation, as the basis of a commercial software or hardware product or to provide services.
+
+LICENSEE further agrees that the PROGRAM shall not be copied or otherwise adapted in order to circumvent the need for obtaining a license for use of the PROGRAM.
+
+2. OWNERSHIP OF INTELLECTUAL PROPERTY
+
+LICENSEE acknowledges that title to the PROGRAM shall remain with LICENSOR. The PROGRAM shall be marked with the notice of attribution to contributors. LICENSEE shall retain such notice on all copies. LICENSEE agrees to include appropriate acknowledgements if any results obtained from use of the PROGRAM are included in any publication.
+
+LICENSEE shall not use any trademark or trade name of LICENSOR, or any variation, adaptation, or abbreviation, of such marks or trade names, or any names of officers, faculty, students, employees, or agents of LICENSOR except as states above for acknowledgements purposes.
+
+3. INDEMNIFICATION
+
+LICENSEE shall indemnify, defend, and hold harmless LICENSOR, and their respective officers, faculty, students, employees, associated investigators and agents, and their respective successors, heirs and assigns, (Indemnitees), against any liability, damage, loss, or expense (including reasonable attorney fees and expenses) incurred by or imposed upon any of the Indemnitees in connection with any claims, suits, actions, demands or judgments arising out of any theory of liability (including, without limitation, actions in the form of tort, warranty, or strict liability and regardless of whether such action has any factual basis) pursuant to any right or license granted under this Agreement.
+
+4. NO REPRESENTATIONS OR WARRANTIES
+
+The program is delivered “AS IS”. Licensor makes no representations or warranties of any kind concerning the program, express or implied, including, without limitation, warranties of merchantability, fitness for a particular purpose, non-infringement, or the absence of latent or other defects, whether or not discoverable. Licensor extends no warranties of any kind as to program conformity with whatever user manuals or other literature may be issued from time to time.
+
+In no event shall licensor or its respective directors, officers, employees, affiliated investigators and affiliates be liable for incidental or consequential damages of any kind, including, without limitation, economic damages or injury to property and lost profits, regardless of whether licensor shall be advised, shall have other reason to know, or in fact shall know of the possibility of the foregoing.
+
+5. ASSIGNMENT
+
+This License is personal to LICENSEE and any rights or obligations assigned by LICENSEE without the prior written consent of LICENSOR shall be null and void.
+
+6. TERMINATION
+
+LICENSEE shall have the right to terminate this license for any reason. If LICENSEE breaches any provision hereunder, and fails to cure such breach within thirty (30) days, LICENSOR may terminate this license immediately. Upon termination, LICENSEE shall delete the PROGRAM the original and all copies, except that, upon prior written authorization from LICENSOR, LICENSEE may retain a copy for archive purposes.
+
+7. GOVERNING LAW
+
+This license is governed by the laws of Switzerland and the jurisdiction of the Canton of Vaud. 

mrsiprep-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: mrsiprep
+Version: 0.1.0
+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
+Provides-Extra: ants
+Requires-Dist: antspyx; extra == "ants"
+Provides-Extra: gui
+Requires-Dist: PyQt6; extra == "gui"
+Provides-Extra: all
+Requires-Dist: antspyx; extra == "all"
+Requires-Dist: PyQt6; 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-v0.1.0-blue)
+[![e2e](https://img.shields.io/github/actions/workflow/status/MRSI-Psychosis-UP/MRSIPrep/e2e-synthmrsi-project.yml?label=tested%20on%20SynthMRSI-Project&color=success)](https://github.com/MRSI-Psychosis-UP/MRSIPrep/actions/workflows/e2e-synthmrsi-project.yml)
+[![docs](https://app.readthedocs.org/projects/mrsiprep/badge/?version=stable)](https://mrsiprep.readthedocs.io/en/stable/)
+[![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-docker?logo=pypi&logoColor=white)](https://pypi.org/project/mrsiprep-docker/)
+[![license](https://img.shields.io/badge/license-academic--non--commercial-lightgrey)](LICENSE)
+
+## About
+
+*MRSIPrep* is a preprocessing and derivative-generation pipeline for already
+quantified whole-brain MRSI maps, run as a BIDS App via Docker. Its default
+`mni-norm` mode normalizes MRSI maps to a specified template for
+[voxel-based analysis](https://github.com/MRSI-Psychosis-UP/VLAD).
+`parc-con` mode adds SynthSeg+FAST tissue maps, PETPVC, and Chimera/MNI-atlas
+regional profile extraction for metabolic connectivity computation. MRSIPrep
+creates a quality-control report for each run.
+
+**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.
+- **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.
+
+## 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 "tested on SynthMRSI-Project" badge above)
+
+## Use Cases
+
+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](https://doi.org/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](https://doi.org/10.1162/imag.a.1276)
+- Céléreau, E., Lucchetti, F., Steullet, P., Schilliger, Z., Alemán-Gómez,
+  Y., Jenni, R., Petrova, T., Forrer, S., Delavari, F., Ledoux, J.-B., 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)
+
+## 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.

mrsiprep-0.1.0/README.md

@@ -0,0 +1,99 @@
+# *MRSIPrep*: A Robust Preprocessing Pipeline for Whole-Brain MRSI Data
+
+
+
+![version](https://img.shields.io/badge/version-v0.1.0-blue)
+[![e2e](https://img.shields.io/github/actions/workflow/status/MRSI-Psychosis-UP/MRSIPrep/e2e-synthmrsi-project.yml?label=tested%20on%20SynthMRSI-Project&color=success)](https://github.com/MRSI-Psychosis-UP/MRSIPrep/actions/workflows/e2e-synthmrsi-project.yml)
+[![docs](https://app.readthedocs.org/projects/mrsiprep/badge/?version=stable)](https://mrsiprep.readthedocs.io/en/stable/)
+[![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-docker?logo=pypi&logoColor=white)](https://pypi.org/project/mrsiprep-docker/)
+[![license](https://img.shields.io/badge/license-academic--non--commercial-lightgrey)](LICENSE)
+
+## About
+
+*MRSIPrep* is a preprocessing and derivative-generation pipeline for already
+quantified whole-brain MRSI maps, run as a BIDS App via Docker. Its default
+`mni-norm` mode normalizes MRSI maps to a specified template for
+[voxel-based analysis](https://github.com/MRSI-Psychosis-UP/VLAD).
+`parc-con` mode adds SynthSeg+FAST tissue maps, PETPVC, and Chimera/MNI-atlas
+regional profile extraction for metabolic connectivity computation. MRSIPrep
+creates a quality-control report for each run.
+
+**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.
+- **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.
+
+## 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 "tested on SynthMRSI-Project" badge above)
+
+## Use Cases
+
+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](https://doi.org/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](https://doi.org/10.1162/imag.a.1276)
+- Céléreau, E., Lucchetti, F., Steullet, P., Schilliger, Z., Alemán-Gómez,
+  Y., Jenni, R., Petrova, T., Forrer, S., Delavari, F., Ledoux, J.-B., 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)
+
+## 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.

mrsiprep-0.1.0/mrsiprep/cli/parser.py

@@ -0,0 +1,294 @@
+"""CLI parser for MRSIPrep."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from mrsiprep.config.defaults import QUALITY_DEFAULTS
+from mrsiprep.config.settings import MRSIPrepConfig
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mrsiprep", description="Preprocess quantified whole-brain MRSI derivatives.")
+    parser.add_argument("bids_dir", type=Path, help="The root folder of a BIDS valid dataset (sub-XXXXX folders at the top level).")
+    parser.add_argument("output_dir", type=Path, help="The output path for MRSIPrep derivatives and reports.")
+    parser.add_argument(
+        "analysis_level",
+        choices=["participant"],
+        help="Processing stage to be run, only 'participant' in the case of MRSIPrep (see BIDS-Apps specification).",
+    )
+
+    selection = parser.add_argument_group("Options for filtering BIDS queries")
+    selection.add_argument("--participant-label", nargs="+", default=[])
+    selection.add_argument("--session-label", nargs="+", default=[])
+    selection.add_argument("--participants", type=Path, default=None, help="TSV/CSV subject-session list.")
+    selection.add_argument(
+        "--bids-filter-file",
+        type=Path,
+        default=None,
+        help="Path to a JSON file of PyBIDS-style entity filters used to select among ambiguous input candidates, "
+        "e.g. {\"t1w\": {\"acquisition\": \"memprage\", \"run\": \"01\"}} to force a specific T1w acquisition/run "
+        "when a session has more than one. Only the \"t1w\" key is currently supported.",
+    )
+
+    quality = parser.add_argument_group("quality thresholds")
+    quality.add_argument(
+        "--metabolites",
+        type=_parse_comma_list,
+        required=True,
+        help="Comma-separated metabolite names to process, e.g. 'CrPCr,GluGln,GPCPCh,NAANAAG,Ins'.",
+    )
+    quality.add_argument("--quality-metrics", nargs="+", default=["snr", "linewidth", "crlb"])
+    quality.add_argument("--snr-min", type=float, default=QUALITY_DEFAULTS["snr_min"])
+    quality.add_argument("--linewidth-max", type=float, default=QUALITY_DEFAULTS["linewidth_max"])
+    quality.add_argument("--crlb-max", type=float, default=QUALITY_DEFAULTS["crlb_max"])
+
+    processing = parser.add_argument_group("Options for performing only a subset of the workflow")
+    processing.add_argument(
+        "--mode",
+        "--processing-mode",
+        dest="processing_mode",
+        choices=["mni-norm", "parc-con", "midas"],
+        default="mni-norm",
+        help="Processing mode. 'midas' runs a MIDAS-faithful pipeline (Maudsley et al. 2006): fuzzy c-means "
+        "tissue segmentation, PSF-convolved tissue fractions, rigid MRSI->T1 registration, and per-parcel "
+        "Eq. 4 pure-GM/pure-WM regression instead of PETPVC.",
+    )
+    processing.add_argument(
+        "--tissue-backend",
+        choices=["synthseg-fast", "existing", "none"],
+        default="synthseg-fast",
+        help="Tissue segmentation backend for PVC. 'none' disables tissue segmentation and PVC entirely. "
+        "Ignored in --mode midas, which always uses its own fuzzy c-means segmentation.",
+    )
+
+    registration = parser.add_argument_group("Specific options for registrations")
+    registration.add_argument(
+        "--registration-backend",
+        choices=["ants", "fsl", "flirt-fnirt", "flirt_fnirt", "flirt/fnirt"],
+        default="ants",
+        help="Registration toolchain. 'ants' is the default; 'fsl'/'flirt-fnirt' uses FLIRT affine registration "
+        "(no deformable stage -- FNIRT is not implemented).",
+    )
+    registration.add_argument(
+        "--ants-mrsi-to-t1-transform",
+        default="sr",
+        help="ANTs transform preset/code for MRSI-to-T1w registration. Default matches the previous implementation: 'sr'.",
+    )
+    registration.add_argument(
+        "--ants-t1-to-mni-transform",
+        default="s",
+        help="ANTs transform preset/code for T1w-to-MNI registration. Default matches the previous implementation: 's'.",
+    )
+    registration.add_argument("--fsl-mrsi-to-t1-dof", type=int, choices=[6, 7, 9, 12], default=6)
+    registration.add_argument(
+        "--fsl-mrsi-to-t1-init",
+        choices=["flirt", "usesqform"],
+        default="flirt",
+        help="FSL MRSI-to-T1w initialization. 'usesqform' applies the NIfTI qform/sform geometry with FLIRT.",
+    )
+    registration.add_argument("--fsl-t1-to-mni-dof", type=int, choices=[6, 7, 9, 12], default=12)
+    registration.add_argument("--fsl-cost", default="mutualinfo", help="FLIRT cost function for FSL registrations.")
+    registration.add_argument("--normalization", choices=["simple", "ants-syn", "existing"], default="simple")
+    registration.add_argument("--output-spaces", nargs="+", default=["MNI152NLin2009cAsym"])
+    registration.add_argument(
+        "--output-mrsi-t1w",
+        action="store_true",
+        help="Also resample all metabolite (and CRLB/SNR/FWHM/spikemask) maps into T1w space as permanent "
+        "derivatives (mrsi-t1w/). Off by default; the registration-overview report generates its own single "
+        "reference-metabolite T1w map in the work directory regardless of this flag.",
+    )
+    registration.add_argument(
+        "--mni-resolution",
+        default="t1wres",
+        help="MNI template resolution: 'origres' (MRSI native), 't1wres' (T1w native), or '<N>mm' (e.g. '2mm').",
+    )
+    registration.add_argument("--registration-t1-target", choices=["brain-csf", "brain", "raw"], default=None)
+    registration.add_argument("--csf-pv-threshold", type=float, default=0.95)
+    registration.add_argument(
+        "--ref-met",
+        required=True,
+        help="Reference metabolite map used to build the MRSI registration target, e.g. 'CrPCr'.",
+    )
+    registration.add_argument("--t1", dest="t1_pattern", default="desc-brain_T1w")
+
+    parcellation = parser.add_argument_group("parcellation")
+    parcellation.add_argument("--parcellation-mode", choices=["synthseg", "chimera", "mni"], default=None)
+    parcellation.add_argument("--synthseg-mode", choices=["fast", "standard", "robust"], default="robust")
+    parcellation.add_argument("--chimera-scheme", default="LFMIHIFIFF")
+    parcellation.add_argument("--chimera-scale", type=_parse_scale, default=3)
+    parcellation.add_argument("--chimera-grow", type=int, default=2)
+    parcellation.add_argument("--atlas", default="chimera-LFMIHIFIS-3")
+    parcellation.add_argument("--custom-atlas", type=Path, default=None)
+    parcellation.add_argument("--custom-atlas-lut", type=Path, default=None)
+    parcellation.add_argument("--fs-subjects-dir", type=Path, default=None)
+
+    connectivity = parser.add_argument_group("connectivity")
+    connectivity.add_argument("--write-connectivity", action="store_true")
+    connectivity.add_argument("--connectivity-method", choices=["pearson", "spearman", "cosine", "euclidean_distance"], default="spearman")
+    connectivity.add_argument("--connectivity-space", choices=["MRSI", "T1w", "MNI"], default="MRSI")
+    connectivity.add_argument("--connectivity-n-perturbations", type=int, default=50, help="Number of CRLB-scaled noise perturbations per metabolite used to build the connectivity similarity matrix.")
+    connectivity.add_argument("--connectivity-sigma-scale", type=float, default=2.0, help="Scale factor applied to the CRLB-derived noise sigma when perturbing metabolite maps for connectivity.")
+    connectivity.add_argument(
+        "--connectivity-exclude-parcels",
+        default=None,
+        help="Comma-separated substrings; parcels whose name contains any of them are excluded from the connectivity matrix (e.g. 'wm-lh,cer-').",
+    )
+    connectivity.add_argument(
+        "--connectivity-max-parcel-id",
+        type=int,
+        default=None,
+        help="Exclude parcels whose label/ID is greater than or equal to this value from the connectivity matrix.",
+    )
+    connectivity.add_argument("--regional-summary", choices=["mean", "median", "weighted_mean"], default="mean")
+
+    processing_control = parser.add_argument_group("Workflow configuration")
+    processing_control.add_argument("--transform", default="", help="Legacy output transform override; prefer --output-spaces.")
+    processing_control.add_argument("--no-filter", action="store_true", help="Disable biharmonic spike filtering (enabled by default in every processing mode).")
+    processing_control.add_argument(
+        "--filter-fwhm-mm",
+        type=float,
+        default=None,
+        help="Smoothing FWHM (mm) used when splicing repaired biharmonic-filter voxels back in. "
+        "Default: derived from the native MRSI voxel size (mean voxel dimension x sqrt(2)).",
+    )
+    processing_control.add_argument("--spikepc", type=float, default=99.0)
+    processing_control.add_argument("--no-pvc", action="store_true")
+    processing_control.add_argument(
+        "--longitudinal",
+        action="store_true",
+        help="Build one unbiased ANTs template across a subject's sessions and register it to MNI once, "
+        "composing (session-to-template)+(template-to-MNI) instead of registering each session directly to MNI. "
+        "No-op for subjects with a single session. Requires --registration-backend ants.",
+    )
+    processing_control.add_argument("--transform-spikemask", action="store_true", help="Also transform per-metabolite spike masks into T1w/MNI space.")
+    processing_control.add_argument("--nthreads", type=int, default=16, help="ANTs/ITK thread count per subject/session process.")
+    processing_control.add_argument(
+        "--nproc",
+        type=int,
+        default=1,
+        help="Number of subject/session recordings to process in parallel. Each parallel process gets --nthreads threads; "
+        "if nproc*nthreads exceeds the available CPU count, --nthreads is coerced down and a warning is shown at startup.",
+    )
+    processing_control.add_argument("--work-dir", "-w", type=Path, default=None)
+
+    overwrite = parser.add_argument_group("overwrite/recompute")
+    overwrite.add_argument("--overwrite", action="store_true")
+    overwrite.add_argument("--overwrite-filt", action="store_true")
+    overwrite.add_argument("--overwrite-seg", action="store_true", help="Force recompute of tissue segmentation (SynthSeg brain extraction + dseg/probseg), even if cached outputs exist.")
+    overwrite.add_argument("--overwrite-pve", action="store_true")
+    overwrite.add_argument("--overwrite-t1-reg", action="store_true")
+    overwrite.add_argument("--overwrite-mni-reg", action="store_true")
+    overwrite.add_argument("--overwrite-transform", action="store_true")
+    overwrite.add_argument("--overwrite-chimera", action="store_true", help="Force re-run Chimera parcellation even if the output dseg file already exists.")
+
+    runtime = parser.add_argument_group("Other options")
+    runtime.add_argument("--validate-only", action="store_true", help="Check selected subject/session inputs and exit without running preprocessing.")
+    runtime.add_argument(
+        "--skip-file-integrity-check",
+        action="store_true",
+        help="Skip forcing a full read of T1w/MRSI input files during preflight validation (existence-only checks instead). "
+        "By default every run force-reads these files first and skips any recording with a missing or corrupt/truncated input.",
+    )
+    runtime.add_argument("--check-external-libs", action="store_true", help="Verify required external binaries are available and exit.")
+    runtime.add_argument(
+        "--stop-on-first-crash",
+        action="store_true",
+        help="Abort the whole run immediately on the first recording failure, instead of logging it and continuing with the rest of the batch.",
+    )
+    runtime.add_argument(
+        "--verbose",
+        "-v",
+        type=int,
+        choices=[0, 1, 2, 3],
+        default=1,
+        help="0=subject start/finish only, 1=+processing steps, 2=+step details, 3=+raw ANTs/recon-all/mri_synthseg output.",
+    )
+    return parser
+
+
+def parse_args(argv: list[str] | None = None) -> MRSIPrepConfig:
+    args = build_parser().parse_args(argv)
+    return MRSIPrepConfig(
+        bids_dir=args.bids_dir,
+        output_dir=args.output_dir,
+        analysis_level=args.analysis_level,
+        participant_label=args.participant_label,
+        session_label=args.session_label,
+        participants_file=args.participants,
+        bids_filter_file=args.bids_filter_file,
+        metabolites=args.metabolites,
+        quality_metrics=args.quality_metrics,
+        snr_min=args.snr_min,
+        linewidth_max=args.linewidth_max,
+        crlb_max=args.crlb_max,
+        processing_mode=args.processing_mode,
+        tissue_backend=args.tissue_backend,
+        registration_backend=args.registration_backend,
+        ants_mrsi_to_t1_transform=args.ants_mrsi_to_t1_transform,
+        ants_t1_to_mni_transform=args.ants_t1_to_mni_transform,
+        fsl_mrsi_to_t1_dof=args.fsl_mrsi_to_t1_dof,
+        fsl_mrsi_to_t1_init=args.fsl_mrsi_to_t1_init,
+        fsl_t1_to_mni_dof=args.fsl_t1_to_mni_dof,
+        fsl_cost=args.fsl_cost,
+        normalization=args.normalization,
+        output_spaces=args.output_spaces,
+        output_mrsi_t1w=args.output_mrsi_t1w,
+        mni_resolution=args.mni_resolution,
+        registration_t1_target=args.registration_t1_target,
+        csf_pv_threshold=args.csf_pv_threshold,
+        ref_met=args.ref_met,
+        t1_pattern=args.t1_pattern,
+        parcellation_mode=args.parcellation_mode,
+        synthseg_mode=args.synthseg_mode,
+        chimera_scheme=args.chimera_scheme,
+        chimera_scale=args.chimera_scale,
+        chimera_grow=args.chimera_grow,
+        atlas=args.atlas,
+        custom_atlas=args.custom_atlas,
+        custom_atlas_lut=args.custom_atlas_lut,
+        fs_subjects_dir=args.fs_subjects_dir,
+        write_connectivity=args.write_connectivity,
+        connectivity_method=args.connectivity_method,
+        connectivity_space=args.connectivity_space,
+        connectivity_n_perturbations=args.connectivity_n_perturbations,
+        connectivity_sigma_scale=args.connectivity_sigma_scale,
+        connectivity_exclude_parcels=args.connectivity_exclude_parcels,
+        connectivity_max_parcel_id=args.connectivity_max_parcel_id,
+        regional_summary=args.regional_summary,
+        transform=args.transform,
+        filter_biharmonic=not args.no_filter,
+        filter_fwhm_mm=args.filter_fwhm_mm,
+        spike_percentile=args.spikepc,
+        no_pvc=args.no_pvc,
+        longitudinal=args.longitudinal,
+        transform_spikemask=args.transform_spikemask,
+        nthreads=args.nthreads,
+        nproc=args.nproc,
+        work_dir=args.work_dir,
+        overwrite=args.overwrite,
+        overwrite_filt=args.overwrite_filt,
+        overwrite_seg=args.overwrite_seg,
+        overwrite_pve=args.overwrite_pve,
+        overwrite_t1_reg=args.overwrite_t1_reg,
+        overwrite_mni_reg=args.overwrite_mni_reg,
+        overwrite_transform=args.overwrite_transform,
+        overwrite_chimera=args.overwrite_chimera,
+        validate_only=args.validate_only,
+        skip_file_integrity_check=args.skip_file_integrity_check,
+        check_external_libs=args.check_external_libs,
+        stop_on_first_crash=args.stop_on_first_crash,
+        verbose=args.verbose,
+    )
+
+
+def _parse_comma_list(value: str) -> list[str]:
+    return [item.strip() for item in str(value).split(",") if item.strip()]
+
+
+def _parse_scale(value) -> int:
+    text = str(value)
+    if text.startswith("scale"):
+        text = text[len("scale") :]
+    return int(text)

mrsiprep-0.1.0/mrsiprep/cli/run.py

@@ -0,0 +1,48 @@
+"""MRSIPrep command entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from mrsiprep.cli.parser import parse_args
+from mrsiprep.utils.banner import print_banner
+from mrsiprep.utils.debug import Debug
+from mrsiprep.utils.logging import setup_logging
+from mrsiprep.utils.provenance import check_external_software
+from mrsiprep.workflows.participant import run_participant_workflow, validate_participant_inputs
+
+
+def main(argv: list[str] | None = None) -> int:
+    print_banner()
+    config = parse_args(argv)
+    logger = setup_logging(config.verbose, log_dir=config.logs_dir)
+    nproc, nthreads, cpu_warning = config.resolve_cpu_budget()
+    if cpu_warning:
+        logger.warning(cpu_warning)
+    config.nproc, config.nthreads = nproc, nthreads
+    if config.analysis_level != "participant":
+        logger.error("Only participant analysis level is currently supported.")
+        return 2
+    if config.check_external_libs:
+        debug = Debug(verbose=config.verbose)
+        ok = check_external_software(debug, config)
+        return 0 if ok else 1
+    if config.validate_only:
+        statuses = validate_participant_inputs(config)
+        failed = [status for status in statuses if status.status != "success"]
+        succeeded = [status for status in statuses if status.status == "success"]
+        logger.info("MRSIPrep input validation finished: %d valid, %d invalid", len(succeeded), len(failed))
+        for status in failed:
+            logger.error("INVALID sub-%s%s: %s", status.subject, f" ses-{status.session}" if status.session else "", status.error)
+        return 1 if failed else 0
+    statuses = run_participant_workflow(config)
+    failed = [status for status in statuses if status.status != "success"]
+    succeeded = [status for status in statuses if status.status == "success"]
+    logger.info("MRSIPrep finished: %d succeeded, %d failed", len(succeeded), len(failed))
+    for status in failed:
+        logger.error("FAILED sub-%s%s: %s", status.subject, f" ses-{status.session}" if status.session else "", status.error)
+    return 1 if failed and not succeeded else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

mrsiprep-0.1.0/mrsiprep/config/defaults.py

@@ -0,0 +1,22 @@
+"""Default values for MRSIPrep."""
+
+METABOLITE_ALIASES = {
+    "Glx": ["GluGln", "Glx"],
+    "GluGln": ["GluGln", "Glx"],
+    "NAA": ["NAA", "NAANAAG"],
+    "tNAA": ["NAANAAG", "tNAA", "NAA"],
+    "NAANAAG": ["NAANAAG", "tNAA", "NAA"],
+    "Cho": ["GPCPCh", "Cho"],
+    "GPCPCh": ["GPCPCh", "Cho"],
+    "tCr": ["CrPCr", "tCr"],
+    "CrPCr": ["CrPCr", "tCr"],
+    "Ins": ["Ins"],
+}
+
+QUALITY_DEFAULTS = {
+    "snr_min": 4.0,
+    "linewidth_max": 0.1,
+    "crlb_max": 20.0,
+}
+
+CHIMERA_SCALES = {"scale1": 1, "scale2": 2, "scale3": 3, "scale4": 4, "scale5": 5}