mrsuite 0.0.1__tar.gz

mrsuite-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Julian P. Merkofer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mrsuite-0.0.1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: mrsuite
+Version: 0.0.1
+Summary: MRS Processing, Analysis, AI Model Integration, and Benchmarking
+Author-email: "Julian P. Merkofer" <j.p.merkofer@tue.nl>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/julianmer/MRSuite
+Keywords: MRS,magnetic resonance spectroscopy,NIfTI-MRS,fitting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Requires-Dist: nifti-mrs
+Requires-Dist: nifti-mrs-plus>=0.2.0
+Requires-Dist: spec2nii
+Requires-Dist: oct2py
+Requires-Dist: lcmodel-wrapper>=0.3
+Requires-Dist: tarquin-wrapper>=0.1
+Requires-Dist: h5py
+Requires-Dist: torch
+Requires-Dist: huggingface_hub
+Requires-Dist: safetensors
+Requires-Dist: ssqueezepy>=0.6.6
+Requires-Dist: keras>=3.0
+Requires-Dist: nicegui[native,plotly]<4,>=3.17
+Requires-Dist: suspect
+Requires-Dist: pyAMARES
+Requires-Dist: pypulseq
+Requires-Dist: mrsandbox>=0.1.0
+Requires-Dist: augmentrum>=0.0.3
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/logo/logo.png" alt="MRSuite Logo" width="130" style="margin-bottom: -5px;"/>
+  <h1 style="margin-top: 5px; margin-bottom: 5px;">MRSuite</h1>
+  <p style="margin-top: 0px;"><em>MRS Processing, Analysis, AI Model Integration, and Benchmarking</em></p>
+
+  [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+</div>
+
+---
+
+The MRSuite project is an open-source, modular framework for magnetic resonance spectroscopy (MRS) that brings together tools for data handling, signal processing, machine learning, and reproducible reporting in a modular and extensible ecosystem.
+
+---
+
+## Overview
+
+MRSuite is designed to support the full MRS workflow, from raw data processing to advanced analysis. It is built around the following core principles:
+- **Modularity**: Each processing and analysis step is encapsulated in reusable, interchangeable modules.
+- **Flexibility**: Custom algorithms, models, and external-language tools can be easily integrated.
+- **Scalability**: Capable of handling large datasets and computationally intensive workflows.
+- **Extensibility**: New modules and features can be added by following a consistent interface.
+- **Reproducibility**: Standardized interfaces and reporting tools ensure transparent, consistent documentation.
+- **Benchmarking**: Built-in tools allow for systematic evaluation across datasets and methods.
+- **Community-Driven**: Open-source development encourages contributions and collaboration.
+
+
+## Installation
+
+MRSuite needs Python 3.11 or newer:
+
+```bash
+pip install mrsuite
+```
+
+The toolboxes MRSuite drives come in as you use them: what pip cannot install (Octave or
+MATLAB, R, FSL-MRS) is named when a step first needs it, and everything else is fetched on
+first use, each under its own licence (FSL-MRS, for one, is for non-commercial use only).
+
+
+## Python
+
+```python
+from mrsuite import fsl_mrs, io, lcmodel
+from mrsuite.benchmark import scoring
+from mrsuite.core.pipeline import Pipeline
+from mrsuite.datasets import challenge2016
+
+spectra, water, truth = challenge2016.load()            # fetched on first use
+basis = io.basis(challenge2016.BASIS)
+fits = {"LCModel": Pipeline([lcmodel.step.fit(basis=basis)]).run(spectra),
+        "FSL-MRS": Pipeline([fsl_mrs.step.fit(basis=basis)]).run(spectra)}
+scores = scoring.score(fits, truth, references=["optimal"], metrics={"mosae": scoring.mae})
+```
+
+A step is any toolbox's function: `fid_a.step.op_alignAverages(0.2, 'n')`,
+`spant.step.hsvd_filt()`, `osprey.step.op_eccKlose(water)`. Swap one for another and the
+rest of the chain stands. Scoring runs on
+[MRSValidate](https://github.com/JohnLaMaster/MRSValidate), which is not on PyPI yet:
+`pip install git+https://github.com/JohnLaMaster/MRSValidate.git`.
+
+
+## Key Components
+
+### Processing Pipeline
+A modular pipeline for preprocessing MRS data, including:
+- **Data Import**: Load data from various formats.
+- **Processing**: Choose from a collection of processing steps or add your own.
+- **Provenance**: Every step is recorded in the data's own processing history (NIfTI-MRS): the
+  toolbox, its exact version and every argument.
+
+### AI Model Zoo
+A collection of (pre-trained) AI models for MRS analysis, including:
+- **Interface**: A standardized interface for integrating AI models into the processing pipeline.
+- **Training**: Train or retrain a model in MRSuite (`model.learn`, one Keras 3 loop, on the CPU,
+  CUDA or Apple's MPS), its recipe recorded with it.
+- **Sharing**: Push a model to the Hugging Face Hub and load anyone's by its name.
+
+### Benchmarking Suite
+A suite of tools for benchmarking MRS processing and analysis methods, including:
+- **Accuracy and agreement**: MRSuite's own errors (MAE, MOSAE) and every analysis of
+  [MRSValidate](https://github.com/JohnLaMaster/MRSValidate) that compares fits with the truth:
+  errors, Lin's CCC, regression, Bland-Altman, normality; per metabolite and pooled.
+- **Comparative Analysis**: Compare different methods and configurations on the same data.
+- **Score tables**: One table per measure, by method, reference and metabolite.
+- **Visualization**: A radar of the methods, a corner per aspect, and MRSValidate's plots.
+
+### Graphical Interface
+
+```bash
+mrsuite-gui
+```
+
+Wire blocks on a canvas. One block per step, each offering every toolbox that does it, and
+every function of every toolbox besides. Each block shows what it made, exports it, and
+reads out its NIfTI-MRS header and history. The graph is written out as the Python that
+makes it again.
+
+![In vivo processing: an OpenNeuro dataset through FSL-MRS, FID-A, spant and Osprey into LCModel](https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/gui/processing.png)
+
+*In vivo processing: coils, alignment, outliers, averaging, eddy currents, water, referencing
+and phasing by four toolboxes, then LCModel with the water reference.*
+
+![A benchmark: the 2016 fitting challenge into LCModel, FSL-MRS, spant and WAND, scored on five aspects](https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/gui/benchmark.png)
+
+*A benchmark: the 2016 fitting challenge into four fitters, scored on five aspects against
+the truth and drawn on a radar.*
+
+![The same processing as the Python it writes](https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/gui/script.png)
+
+*The same processing as the Python it writes.*
+
+### Reporting Standards
+A set of standards for generating reproducible reports, including:
+- **Documentation**: Each step of the processing pipeline is documented automatically, in the
+  data's history.
+- **Training recipes**: A trained model carries how its training spectra were made, reported as
+  the MRSsynMRS minimum standard for synthetic data.
+- **Contribution Guidelines**:
+  [CONTRIBUTING.md](https://github.com/julianmer/MRSuite/blob/main/CONTRIBUTING.md) says how to
+  add a method, check it, and share a trained model.
+

mrsuite-0.0.1/README.md

@@ -0,0 +1,121 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/logo/logo.png" alt="MRSuite Logo" width="130" style="margin-bottom: -5px;"/>
+  <h1 style="margin-top: 5px; margin-bottom: 5px;">MRSuite</h1>
+  <p style="margin-top: 0px;"><em>MRS Processing, Analysis, AI Model Integration, and Benchmarking</em></p>
+
+  [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+</div>
+
+---
+
+The MRSuite project is an open-source, modular framework for magnetic resonance spectroscopy (MRS) that brings together tools for data handling, signal processing, machine learning, and reproducible reporting in a modular and extensible ecosystem.
+
+---
+
+## Overview
+
+MRSuite is designed to support the full MRS workflow, from raw data processing to advanced analysis. It is built around the following core principles:
+- **Modularity**: Each processing and analysis step is encapsulated in reusable, interchangeable modules.
+- **Flexibility**: Custom algorithms, models, and external-language tools can be easily integrated.
+- **Scalability**: Capable of handling large datasets and computationally intensive workflows.
+- **Extensibility**: New modules and features can be added by following a consistent interface.
+- **Reproducibility**: Standardized interfaces and reporting tools ensure transparent, consistent documentation.
+- **Benchmarking**: Built-in tools allow for systematic evaluation across datasets and methods.
+- **Community-Driven**: Open-source development encourages contributions and collaboration.
+
+
+## Installation
+
+MRSuite needs Python 3.11 or newer:
+
+```bash
+pip install mrsuite
+```
+
+The toolboxes MRSuite drives come in as you use them: what pip cannot install (Octave or
+MATLAB, R, FSL-MRS) is named when a step first needs it, and everything else is fetched on
+first use, each under its own licence (FSL-MRS, for one, is for non-commercial use only).
+
+
+## Python
+
+```python
+from mrsuite import fsl_mrs, io, lcmodel
+from mrsuite.benchmark import scoring
+from mrsuite.core.pipeline import Pipeline
+from mrsuite.datasets import challenge2016
+
+spectra, water, truth = challenge2016.load()            # fetched on first use
+basis = io.basis(challenge2016.BASIS)
+fits = {"LCModel": Pipeline([lcmodel.step.fit(basis=basis)]).run(spectra),
+        "FSL-MRS": Pipeline([fsl_mrs.step.fit(basis=basis)]).run(spectra)}
+scores = scoring.score(fits, truth, references=["optimal"], metrics={"mosae": scoring.mae})
+```
+
+A step is any toolbox's function: `fid_a.step.op_alignAverages(0.2, 'n')`,
+`spant.step.hsvd_filt()`, `osprey.step.op_eccKlose(water)`. Swap one for another and the
+rest of the chain stands. Scoring runs on
+[MRSValidate](https://github.com/JohnLaMaster/MRSValidate), which is not on PyPI yet:
+`pip install git+https://github.com/JohnLaMaster/MRSValidate.git`.
+
+
+## Key Components
+
+### Processing Pipeline
+A modular pipeline for preprocessing MRS data, including:
+- **Data Import**: Load data from various formats.
+- **Processing**: Choose from a collection of processing steps or add your own.
+- **Provenance**: Every step is recorded in the data's own processing history (NIfTI-MRS): the
+  toolbox, its exact version and every argument.
+
+### AI Model Zoo
+A collection of (pre-trained) AI models for MRS analysis, including:
+- **Interface**: A standardized interface for integrating AI models into the processing pipeline.
+- **Training**: Train or retrain a model in MRSuite (`model.learn`, one Keras 3 loop, on the CPU,
+  CUDA or Apple's MPS), its recipe recorded with it.
+- **Sharing**: Push a model to the Hugging Face Hub and load anyone's by its name.
+
+### Benchmarking Suite
+A suite of tools for benchmarking MRS processing and analysis methods, including:
+- **Accuracy and agreement**: MRSuite's own errors (MAE, MOSAE) and every analysis of
+  [MRSValidate](https://github.com/JohnLaMaster/MRSValidate) that compares fits with the truth:
+  errors, Lin's CCC, regression, Bland-Altman, normality; per metabolite and pooled.
+- **Comparative Analysis**: Compare different methods and configurations on the same data.
+- **Score tables**: One table per measure, by method, reference and metabolite.
+- **Visualization**: A radar of the methods, a corner per aspect, and MRSValidate's plots.
+
+### Graphical Interface
+
+```bash
+mrsuite-gui
+```
+
+Wire blocks on a canvas. One block per step, each offering every toolbox that does it, and
+every function of every toolbox besides. Each block shows what it made, exports it, and
+reads out its NIfTI-MRS header and history. The graph is written out as the Python that
+makes it again.
+
+![In vivo processing: an OpenNeuro dataset through FSL-MRS, FID-A, spant and Osprey into LCModel](https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/gui/processing.png)
+
+*In vivo processing: coils, alignment, outliers, averaging, eddy currents, water, referencing
+and phasing by four toolboxes, then LCModel with the water reference.*
+
+![A benchmark: the 2016 fitting challenge into LCModel, FSL-MRS, spant and WAND, scored on five aspects](https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/gui/benchmark.png)
+
+*A benchmark: the 2016 fitting challenge into four fitters, scored on five aspects against
+the truth and drawn on a radar.*
+
+![The same processing as the Python it writes](https://raw.githubusercontent.com/julianmer/MRSuite/main/assets/gui/script.png)
+
+*The same processing as the Python it writes.*
+
+### Reporting Standards
+A set of standards for generating reproducible reports, including:
+- **Documentation**: Each step of the processing pipeline is documented automatically, in the
+  data's history.
+- **Training recipes**: A trained model carries how its training spectra were made, reported as
+  the MRSsynMRS minimum standard for synthetic data.
+- **Contribution Guidelines**:
+  [CONTRIBUTING.md](https://github.com/julianmer/MRSuite/blob/main/CONTRIBUTING.md) says how to
+  add a method, check it, and share a trained model.
+

mrsuite-0.0.1/mrsuite/__init__.py

@@ -0,0 +1,54 @@
+####################################################################################################
+#                                           __init__.py                                            #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 2026-08-08                                                                              #
+#                                                                                                  #
+# Purpose: Package entry point. Exposes the toolbox bridges directly (mrsuite.fid_a,               #
+#          mrsuite.fsl_mrs, mrsuite.osprey, mrsuite.lcmodel) and mrsuite.method, which makes       #
+#          a function of your own a method, and stamps the shared NIfTI-MRS+ provenance.           #
+#          Bridges are imported lazily: resolving an Octave-backed one would start a               #
+#          session, and the FSL-MRS one pulls in the whole FSL-MRS stack, neither of which         #
+#          a caller who only wants the pipeline should pay for.                                    #
+#                                                                                                  #
+####################################################################################################
+
+
+#*************#
+#   imports   #
+#*************#
+import importlib
+from typing import Any
+
+import nifti_mrs_plus
+
+from mrsuite.core.method import Method, method
+
+__version__ = "0.0.1"
+
+# Same pattern as Augmentrum: stamp the shared wrapper's provenance metadata so
+# processed data records which toolbox touched it.
+nifti_mrs_plus.set_provenance("MRSuite", __version__)
+
+_BRIDGES = {"augmentrum", "fid_a", "fsl_mrs", "lcmodel", "mrspeclab", "nifti_mrs", "osprey",
+            "pyamares", "spant", "suspect", "tarquin", "vespa"}
+
+__all__ = ["__version__", "Method", "method", *sorted(_BRIDGES)]
+
+
+#*************#
+#   getattr   #
+#*************#
+def __getattr__(name: str) -> Any:
+    if name in _BRIDGES:
+        return importlib.import_module(f"mrsuite.bridges.{name}")
+    raise AttributeError(f"module 'mrsuite' has no attribute '{name}'")
+
+
+#*********#
+#   dir   #
+#*********#
+def __dir__():
+    return sorted(set(globals()) | _BRIDGES)

mrsuite-0.0.1/mrsuite/basic_driver.py

@@ -0,0 +1,112 @@
+####################################################################################################
+#                                         basic_driver.py                                          #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 2026-10-09                                                                              #
+#                                                                                                  #
+# Purpose: Reads and writes basis sets with BasiC, for mrsuite.io. Not imported by MRSuite: BasiC  #
+#          is a folder of scripts importing each other as top-level modules (core, readers,        #
+#          writers), so it runs in a process of its own. FIDs come and go as .npz; what BasiC      #
+#          prints goes to stderr; the job's answer goes to stdout, as JSON; a failure ends it      #
+#          with one line saying why.                                                               #
+#                                                                                                  #
+#          Usage: python basic_driver.py '<job as JSON>'                                           #
+#                                                                                                  #
+####################################################################################################
+
+
+#*************#
+#   imports   #
+#*************#
+import contextlib
+import json
+import sys
+
+import numpy as np
+
+
+#**********#
+#   fail   #
+#**********#
+def fail(message):
+    sys.exit(" ".join(str(message).split()))
+
+
+#**********#
+#   read   #
+#**********#
+def read(job):
+    """The files in the format given or detected, with the parameters given where they state
+    none, as one array of FIDs (to ``result``) and what is said of them; the echo time and
+    sequence as the basis functions hold them (a reader gives 0 for an echo time not
+    stated), else as given."""
+    from core.detect import detect_format
+    from core.load import fill_missing, load_basis
+
+    found = detect_format(job["files"])
+    fmt = job["format"]
+    if fmt == "auto":
+        if found["status"] == "ambiguous":
+            fail(f"{found['message']} Choose one as format: "
+                 + ", ".join(map(repr, found["ambiguous_options"])))
+        if found["status"] == "failed":
+            fail(found["message"])
+        fmt = found["format"]
+    stated = found["data"]
+    given = {k: job[k] for k in ("sw", "sf", "te")}
+    basis = load_basis(job["files"], fmt, sw=stated.get("sw") or given["sw"],
+                       sf=stated.get("sf") or given["sf"])
+    if not basis:
+        fail("it found no basis functions in the files")
+    fill_missing(basis, given)
+    lacking = [k for k in ("sw", "sf") if not all(b.get(k) for b in basis)]
+    if lacking:
+        fail(f"the files do not state {' or '.join(lacking)}: give "
+             + ", ".join(f"{k}=" for k in lacking))
+    if len({len(np.ravel(b["fid"])) for b in basis}) > 1:
+        fail("its basis functions differ in length")
+    np.savez(job["result"], fids=np.array([np.ravel(b["fid"]) for b in basis]))
+    first = basis[0]
+    return {"names": [b["name"] for b in basis], "bandwidth": float(first["sw"]),
+            "frequency": float(first["sf"]), "centre": first.get("centerFreq"),
+            "te": first.get("te") or given["te"], "seq": first.get("seq"), "format": fmt}
+
+
+#***********#
+#   write   #
+#***********#
+def write(job):
+    """The job's basis set (FIDs from ``fids``) written for a tool BasiC writes for; the
+    files written."""
+    from core.formats import ALL_TOOLS
+    from core.write import write_basis
+
+    tools = {t["id"]: [f["id"] for f in t["formats"]] for t in ALL_TOOLS if not t["dimmed"]}
+    if job["tool"] not in tools:
+        fail(f"no tool {job['tool']!r}; one of: {', '.join(tools)}")
+    outputs = tools[job["tool"]]
+    if job["output"] != "default" and job["output"] not in outputs:
+        fail(f"{job['tool']} writes output 'default'"
+             + "".join(f", {o!r}" for o in outputs) + f", not {job['output']!r}")
+    fids = np.load(job["fids"])["fids"]
+    basis = [{"fid": fid, "name": name, "n": len(fid), "sw": job["bandwidth"],
+              "sf": job["frequency"], "centerFreq": job["centre"], "te": job["te"],
+              "seq": job["seq"]} for name, fid in zip(job["names"], fids)]
+    written = write_basis(basis, job["tool"], job["output"], job["folder"], te=job["te"],
+                          seq=job["seq"])
+    if not written:                        # its writers go on without what they fail
+        fail("it wrote nothing")
+    return written
+
+
+if __name__ == "__main__":
+    try:
+        with contextlib.redirect_stdout(sys.stderr):
+            job = json.loads(sys.argv[1])
+            sys.path.insert(0, job["root"])
+            answer = {"read": read, "write": write}[job["task"]](job)
+    except Exception as err:               # noqa: BLE001 - said, in one line
+        fail(f"{type(err).__name__}: {err}")
+    print(json.dumps(answer))

mrsuite-0.0.1/mrsuite/benchmark/__init__.py

@@ -0,0 +1,24 @@
+####################################################################################################
+#                                           __init__.py                                            #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 2026-10-01                                                                              #
+#                                                                                                  #
+# Purpose: Benchmarking on MRSValidate. Fits and ground truth become its ObservationSets on a      #
+#          reference the caller names (water, tCr, the optimal scale or none), every metric runs   #
+#          as a step of its analysis plan, and radar draws the resulting scores.                   #
+#                                                                                                  #
+####################################################################################################
+
+
+#*************#
+#   imports   #
+#*************#
+from mrsuite.benchmark.radar import plot_scores, radar
+from mrsuite.benchmark.scoring import (REFERENCES, analyses, bias, coverage, figure, mae,
+                                       observations, optimal_scale, score)
+
+__all__ = ["REFERENCES", "observations", "optimal_scale", "score", "analyses", "figure",
+           "coverage", "mae", "bias", "radar", "plot_scores"]