MNutils 1.2.0__tar.gz

mnutils-1.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025-2026, Sebastian Bauer
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mnutils-1.2.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: MNutils
+Version: 1.2.0
+Summary: Utility functions for multinuclear MR data processing
+Keywords: mri,mrs,xarray,spectroscopy,nmr
+Author: Sebastian Bauer
+Author-email: Sebastian Bauer <28663646+bastigw@users.noreply.github.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Jupyter
+Requires-Dist: dcm2niiw>=0.1.5
+Requires-Dist: ipython>=8.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mat73
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: nibabel>=5.3.2
+Requires-Dist: nmrglue>=0.11
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: xmris[fitting]
+Requires-Dist: matlabengine==25.1.* ; extra == '2025a'
+Requires-Dist: hd-bet>=2.0.1 ; extra == 'bet'
+Requires-Dist: torch>=2.10.0 ; extra == 'bet'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/bastigw/mnutils
+Project-URL: Documentation, https://bastigw.github.io/mnutils/
+Project-URL: Repository, https://github.com/bastigw/mnutils
+Project-URL: Issues, https://github.com/bastigw/mnutils/issues
+Provides-Extra: 2025a
+Provides-Extra: bet
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"
+            srcset="docs/assets/logo/mnutils-banner-dark.svg">
+    <img src="docs/assets/logo/mnutils-banner-light.svg" alt="MNUtils" width="420">
+  </picture>
+</p>
+
+[![Tests](https://github.com/bastigw/mnutils/actions/workflows/ci-fast.yml/badge.svg)](https://github.com/bastigw/mnutils/actions/workflows/ci-fast.yml)
+[![Docs](https://github.com/bastigw/mnutils/actions/workflows/deploy.yml/badge.svg)](https://bastigw.github.io/mnutils/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+MNUtils is a collection of utility functions for working with multi-nuclear MR data from our GE
+scanners.
+
+## Features
+
+- **Data loading** — read GE raw/reconstructed data via `GEExam`/`GESeries`.
+- **NIfTI/DICOM conversion** — convert scanner output to NIfTI.
+- **Plotting** — spectral and slice plotting utilities.
+- **Spectral fitting** — AMARES fitting delegated to [`xmris`](https://github.com/andrewendlinger/xmris)
+  (`xmris[fitting]`, which wraps pyAMARES).
+
+See the [documentation](https://bastigw.github.io/mnutils/) for the full basics, data model,
+plotting, fitting, NIfTI, and MATLAB-bridge guides.
+
+## Installation
+
+```bash
+uv add git+https://github.com/bastigw/mnutils.git
+```
+
+Optional extras:
+
+```bash
+uv add "mnutils[bet] @ git+https://github.com/bastigw/mnutils.git"     # brain extraction (hd-bet, torch)
+uv add "mnutils[2025a] @ git+https://github.com/bastigw/mnutils.git"   # MATLAB Engine pinned to MATLAB 2025a
+```
+
+`2025a` pins `matlabengine==25.1.*`. If your local MATLAB install is a different version, install
+the matching `matlabengine` release yourself instead (see [MATLAB Engine
+Dependency](#matlab-engine-dependency) below) — there's no way to pin one version project-wide
+across contributors' machines.
+
+## Usage
+
+The main entry point is `ExamBase`: point it at a GE exam's data folder and it classifies every
+series for you — no need to know in advance which folder is an anatomical scan and which is a
+spectrum.
+
+```python
+from mnutils.GEExam import ExamBase
+
+exam = ExamBase("data/HeVo-11")  # prints an overview of every series it found
+
+exam.exam_overview.head()  # same overview as a DataFrame
+exam.series_dict[6]  # the GESeries subclass ExamBase picked for series 6 — nothing loaded yet
+```
+
+Load the series you actually need and analyse it — everything about it (spectrum, header fields,
+scan time) lives on the returned object:
+
+```python
+exam.load_series(6)
+mrs = exam[6]
+
+print(mrs.protocol_name, mrs.spec.dims, mrs.spec.shape)
+avg = mrs.avg_spec  # average over repetitions
+```
+
+`load_series` also takes a list, and `load_all` loads everything `ExamBase` classified. If you
+already know a series's type, construct it directly (e.g. `MRSSeries(DATA_FOLDER, 6)`) and skip
+the exam-level overview entirely.
+
+From there, spectral fitting is handled by [**xmris**](https://github.com/andrewendlinger/xmris)
+— MNUtils deliberately doesn't reimplement fitting, it wraps xmris's AMARES implementation
+(itself built on pyAMARES) so a series's spectrum can go straight into a fit:
+
+```bash
+uv add "xmris[fitting]"
+```
+
+See the [fitting docs](https://bastigw.github.io/mnutils/fitting/) for the full workflow, and the
+[loading data](https://bastigw.github.io/mnutils/basics/loading_data/) and
+[GEExam](https://bastigw.github.io/mnutils/data-model/geexam/) tutorials for more on exams and
+series. Need a raw `.mat` file's path directly instead of a loaded object?
+`mnutils.utils.file_helpers.get_mat_data_from_series(base_folder, series_id)` returns it.
+
+## Requirements
+
+- Python 3.12+
+
+## MATLAB Engine Dependency
+
+To use MNUtils, you need to install the MATLAB Engine for Python. The version of the MATLAB Engine
+you require depends on your local MATLAB version. Ensure you install the correct version that
+matches your MATLAB installation.
+
+You can find the appropriate MATLAB Engine version for your setup here: [MATLAB Engine for
+Python](https://pypi.org/project/matlabengine/#history).
+
+To install the MATLAB Engine in your project, use the following command, replacing `<version>`
+with the correct version for your MATLAB:
+
+```bash
+uv add "matlabengine==<version>"
+```
+
+## Development
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [contributor docs](docs/contribute/) for setup,
+tests, docs, and lint workflow.
+
+## Contributions and Suggestions
+
+I'm very open to suggestions and improvements! If you have ideas or want to share your own
+utilities, feel free to reach out or submit a pull request.
+
+## License
+
+BSD-3-Clause — see [`LICENSE`](LICENSE).

mnutils-1.2.0/README.md

@@ -0,0 +1,121 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"
+            srcset="docs/assets/logo/mnutils-banner-dark.svg">
+    <img src="docs/assets/logo/mnutils-banner-light.svg" alt="MNUtils" width="420">
+  </picture>
+</p>
+
+[![Tests](https://github.com/bastigw/mnutils/actions/workflows/ci-fast.yml/badge.svg)](https://github.com/bastigw/mnutils/actions/workflows/ci-fast.yml)
+[![Docs](https://github.com/bastigw/mnutils/actions/workflows/deploy.yml/badge.svg)](https://bastigw.github.io/mnutils/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
+
+MNUtils is a collection of utility functions for working with multi-nuclear MR data from our GE
+scanners.
+
+## Features
+
+- **Data loading** — read GE raw/reconstructed data via `GEExam`/`GESeries`.
+- **NIfTI/DICOM conversion** — convert scanner output to NIfTI.
+- **Plotting** — spectral and slice plotting utilities.
+- **Spectral fitting** — AMARES fitting delegated to [`xmris`](https://github.com/andrewendlinger/xmris)
+  (`xmris[fitting]`, which wraps pyAMARES).
+
+See the [documentation](https://bastigw.github.io/mnutils/) for the full basics, data model,
+plotting, fitting, NIfTI, and MATLAB-bridge guides.
+
+## Installation
+
+```bash
+uv add git+https://github.com/bastigw/mnutils.git
+```
+
+Optional extras:
+
+```bash
+uv add "mnutils[bet] @ git+https://github.com/bastigw/mnutils.git"     # brain extraction (hd-bet, torch)
+uv add "mnutils[2025a] @ git+https://github.com/bastigw/mnutils.git"   # MATLAB Engine pinned to MATLAB 2025a
+```
+
+`2025a` pins `matlabengine==25.1.*`. If your local MATLAB install is a different version, install
+the matching `matlabengine` release yourself instead (see [MATLAB Engine
+Dependency](#matlab-engine-dependency) below) — there's no way to pin one version project-wide
+across contributors' machines.
+
+## Usage
+
+The main entry point is `ExamBase`: point it at a GE exam's data folder and it classifies every
+series for you — no need to know in advance which folder is an anatomical scan and which is a
+spectrum.
+
+```python
+from mnutils.GEExam import ExamBase
+
+exam = ExamBase("data/HeVo-11")  # prints an overview of every series it found
+
+exam.exam_overview.head()  # same overview as a DataFrame
+exam.series_dict[6]  # the GESeries subclass ExamBase picked for series 6 — nothing loaded yet
+```
+
+Load the series you actually need and analyse it — everything about it (spectrum, header fields,
+scan time) lives on the returned object:
+
+```python
+exam.load_series(6)
+mrs = exam[6]
+
+print(mrs.protocol_name, mrs.spec.dims, mrs.spec.shape)
+avg = mrs.avg_spec  # average over repetitions
+```
+
+`load_series` also takes a list, and `load_all` loads everything `ExamBase` classified. If you
+already know a series's type, construct it directly (e.g. `MRSSeries(DATA_FOLDER, 6)`) and skip
+the exam-level overview entirely.
+
+From there, spectral fitting is handled by [**xmris**](https://github.com/andrewendlinger/xmris)
+— MNUtils deliberately doesn't reimplement fitting, it wraps xmris's AMARES implementation
+(itself built on pyAMARES) so a series's spectrum can go straight into a fit:
+
+```bash
+uv add "xmris[fitting]"
+```
+
+See the [fitting docs](https://bastigw.github.io/mnutils/fitting/) for the full workflow, and the
+[loading data](https://bastigw.github.io/mnutils/basics/loading_data/) and
+[GEExam](https://bastigw.github.io/mnutils/data-model/geexam/) tutorials for more on exams and
+series. Need a raw `.mat` file's path directly instead of a loaded object?
+`mnutils.utils.file_helpers.get_mat_data_from_series(base_folder, series_id)` returns it.
+
+## Requirements
+
+- Python 3.12+
+
+## MATLAB Engine Dependency
+
+To use MNUtils, you need to install the MATLAB Engine for Python. The version of the MATLAB Engine
+you require depends on your local MATLAB version. Ensure you install the correct version that
+matches your MATLAB installation.
+
+You can find the appropriate MATLAB Engine version for your setup here: [MATLAB Engine for
+Python](https://pypi.org/project/matlabengine/#history).
+
+To install the MATLAB Engine in your project, use the following command, replacing `<version>`
+with the correct version for your MATLAB:
+
+```bash
+uv add "matlabengine==<version>"
+```
+
+## Development
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [contributor docs](docs/contribute/) for setup,
+tests, docs, and lint workflow.
+
+## Contributions and Suggestions
+
+I'm very open to suggestions and improvements! If you have ideas or want to share your own
+utilities, feel free to reach out or submit a pull request.
+
+## License
+
+BSD-3-Clause — see [`LICENSE`](LICENSE).

mnutils-1.2.0/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "MNutils"
+version = "1.2.0"
+description = "Utility functions for multinuclear MR data processing"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+keywords = [
+    "mri",
+    "mrs",
+    "xarray",
+    "spectroscopy",
+    "nmr",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Framework :: Jupyter",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "dcm2niiw>=0.1.5",
+    "ipython>=8.0",
+    "loguru>=0.7.3",
+    "mat73",
+    "matplotlib>=3.10.7",
+    "nibabel>=5.3.2",
+    "nmrglue>=0.11",
+    "pillow>=12.3.0",
+    "scipy>=1.15.3",
+    "seaborn>=0.13.2",
+    "xmris[fitting]",
+]
+
+[[project.authors]]
+name = "Sebastian Bauer"
+email = "28663646+bastigw@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/bastigw/mnutils"
+Documentation = "https://bastigw.github.io/mnutils/"
+Repository = "https://github.com/bastigw/mnutils"
+Issues = "https://github.com/bastigw/mnutils/issues"
+
+[project.optional-dependencies]
+2025a = ["matlabengine==25.1.*"]
+bet = [
+    "hd-bet>=2.0.1",
+    "torch>=2.10.0",
+]
+
+[project.scripts]
+docs-mnutils-api = "mnutils._scripts:docs_api"
+docs-mnutils-notebooks = "mnutils._scripts:docs_notebooks"
+docs-mnutils = "mnutils._scripts:docs_all"
+test-mnutils-gen = "mnutils._scripts:generate_test_notebooks"
+test-mnutils = "mnutils._scripts:run_tests"
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.1.0",
+    "ipywidgets>=8.1.7",
+    "nbmake>=1.5.5",
+    "pytest>=8.4.1",
+    "ruff>=0.9.0",
+    "mystmd>=1.3.0",
+    "quartodoc>=0.11.1",
+    "griffe<0.40.0",
+    "jupyter-server>=2.17.0",
+    "jupytext>=1.19.1",
+]
+
+[tool.pytest.ini_options]
+addopts = "--capture=no --nbmake"
+testpaths = ["tests"]
+
+[tool.uv.sources.mat73]
+git = "https://github.com/skjerns/mat7.3"
+
+[tool.uv.sources.xmris]
+git = "https://github.com/andrewendlinger/xmris.git"
+
+[tool.uv.build-backend]
+source-exclude = [".ruff_cache/**"]
+wheel-exclude = [".ruff_cache/**"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "NPY",
+    "D",
+    "UP",
+]
+ignore = [
+    "D100",
+    "D104",
+    "D401",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"docs/**/*.py" = [
+    "E501",
+    "F401",
+    "E402",
+]
+"docs/**/*.ipynb" = [
+    "E501",
+    "F401",
+    "E402",
+]
+
+[tool.jupytext]
+formats = "ipynb,md:myst"
+notebook_metadata_filter = "-all, kernelspec.name, kernelspec.language, kernelspec.display_name, jupytext.text_representation.extension, jupytext.text_representation.format_name"
+cell_metadata_filter = "-all, tags, name"

mnutils-1.2.0/pyproject.toml.orig

@@ -0,0 +1,124 @@
+[project]
+name = "MNutils"
+version = "1.2.0"
+
+authors = [
+    {name = "Sebastian Bauer", email = "28663646+bastigw@users.noreply.github.com"}
+]
+
+description = "Utility functions for multinuclear MR data processing"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+
+keywords = ["mri", "mrs", "xarray", "spectroscopy", "nmr"]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Framework :: Jupyter",
+]
+
+requires-python = ">=3.12"
+
+dependencies = [
+    "dcm2niiw>=0.1.5",
+    "ipython>=8.0",
+    "loguru>=0.7.3",
+    "mat73",
+    "matplotlib>=3.10.7",
+    "nibabel>=5.3.2",
+    "nmrglue>=0.11",
+    "pillow>=12.3.0",
+    "scipy>=1.15.3",
+    "seaborn>=0.13.2",
+    "xmris[fitting]",
+]
+
+[project.urls]
+Homepage = "https://github.com/bastigw/mnutils"
+Documentation = "https://bastigw.github.io/mnutils/"
+Repository = "https://github.com/bastigw/mnutils"
+Issues = "https://github.com/bastigw/mnutils/issues"
+
+[project.optional-dependencies]
+2025a = ["matlabengine==25.1.*"]
+bet = ["hd-bet>=2.0.1", "torch>=2.10.0"]
+
+[project.scripts]
+docs-mnutils-api = "mnutils._scripts:docs_api"        # Regenerate quartodoc API stubs
+docs-mnutils-notebooks = "mnutils._scripts:docs_notebooks"  # Serve tutorials — blocking
+docs-mnutils = "mnutils._scripts:docs_all"            # API refs, then serve site — blocking
+test-mnutils-gen = "mnutils._scripts:generate_test_notebooks"  # docs/*.md -> tests/autogen_notebooks/*.ipynb
+test-mnutils = "mnutils._scripts:run_tests"           # test-gen, then run the full pytest suite
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    # --- Notebooks ---
+    "ipykernel>=7.1.0",
+    "ipywidgets>=8.1.7",
+    # --- Testing ---
+    "nbmake>=1.5.5",
+    "pytest>=8.4.1",
+    # --- Code Quality ---
+    "ruff>=0.9.0",
+    # --- Documentation (MyST) ---
+    "mystmd>=1.3.0",            # Python MyST CLI for docs building
+    "quartodoc>=0.11.1",        # Converts code docstrings to markdown
+    "griffe<0.40.0",            # Explicit pin to fix quartodoc parsing bug
+    "jupyter-server>=2.17.0",   # Required for rendering docs
+    "jupytext>=1.19.1",
+]
+
+[tool.pytest.ini_options]
+addopts = "--capture=no --nbmake"
+testpaths = ["tests"]
+
+# [tool.uv]
+# config-settings = { editable_mode = "compat" }
+
+[tool.uv.sources]
+mat73 = { git = "https://github.com/skjerns/mat7.3" }
+xmris = { git = "https://github.com/andrewendlinger/xmris.git" }
+# xmris = { path = "../xmris", editable = true }
+
+[tool.uv.build-backend]
+source-exclude = [".ruff_cache/**"]
+wheel-exclude = [".ruff_cache/**"]
+
+# --- Ruff (Linter) ---
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "NPY", "D", "UP"] # Errors, Failures, Isort, NumPy, Docstrings, Upgrade
+ignore = ["D100", "D104", "D401"]                  # Ignore missing docstring in public module/package
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore line length, unused imports, and import positions in notebooks/scripts
+"docs/**/*.py" = ["E501", "F401", "E402"]
+"docs/**/*.ipynb" = ["E501", "F401", "E402"]
+
+# --- Jupytext ---
+# Two-way syncing between Jupyter Notebooks (.ipynb) and Markdown (.md) for docs pages.
+# Edit in .md (git-friendly) or .ipynb (interactive), but only ever commit .md files.
+[tool.jupytext]
+formats = "ipynb,md:myst"
+
+# Include display_name to prevent notebook validation errors
+notebook_metadata_filter = "-all, kernelspec.name, kernelspec.language, kernelspec.display_name, jupytext.text_representation.extension, jupytext.text_representation.format_name"
+
+# Cell Metadata: strip execution counts/IDs, keep 'tags' (MyST directives) and 'name'.
+cell_metadata_filter = "-all, tags, name"