MNutils 1.2.0__py3-none-any.whl

mnutils/utils/spectra.py

@@ -0,0 +1,149 @@
+import numpy as np
+import numpy.typing as npt
+from loguru import logger
+
+
+def calculate_hz_axis(
+    spectral_width: float | None = None,
+    npts: int | None = None,
+    header: dict | None = None,
+) -> npt.NDArray[np.float64]:
+    """Calculate the frequency (Hz) axis for a spectrum.
+
+    Parameters
+    ----------
+    spectral_width : float, optional
+        Spectral width in Hz. Read from `header` if not given.
+    npts : int, optional
+        Number of spectral points. Read from `header` if not given.
+    header : dict, optional
+        Raw header dict to fall back on for `spectral_width`/`npts`.
+
+    Returns
+    -------
+    npt.NDArray[np.float64]
+        Frequency axis in Hz, centered on zero.
+    """
+    _sw = spectral_width
+    _npts = npts
+
+    if header is not None:
+        rdb_hdr = header.get("rdb_hdr", {})
+        if isinstance(rdb_hdr, dict):
+            if _sw is None:
+                _sw = rdb_hdr.get("spectral_width", None)
+            if _npts is None:
+                _npts = rdb_hdr.get("user1", None)
+
+    if _sw is None:
+        raise ValueError(
+            "Spectral width information is required to calculate frequency axis. "
+            "Please provide spectral width or ensure it is present in the header."
+        )
+    if _npts is None:
+        raise ValueError(
+            "Number of points information is required to calculate frequency axis. "
+            "Please provide number of points or ensure it is present in the header."
+        )
+
+    return np.linspace(-_sw / 2, _sw / 2, int(_npts))
+
+
+def calculate_ppm_axis(
+    spectral_width: float | None = None,
+    frequency: float | None = None,
+    carrier_ppm: float | None = None,
+    nucleus: int | str | None = None,
+    npts: int | None = None,
+    header: dict | None = None,
+) -> npt.NDArray[np.float64]:
+    """Calculate the chemical shift (ppm) axis for a spectrum.
+
+    Parameters
+    ----------
+    spectral_width : float, optional
+        Spectral width in Hz. Read from `header` if not given.
+    frequency : float, optional
+        Spectrometer frequency in MHz. Read from `header` if not given.
+    carrier_ppm : float, optional
+        Carrier frequency offset in ppm. Derived from `nucleus` if not given.
+    nucleus : int or str, optional
+        Nucleus identifier (e.g. `"1H"` or `1`) used to derive `carrier_ppm`
+        when it is not provided directly.
+    npts : int, optional
+        Number of spectral points. Read from `header` if not given.
+    header : dict, optional
+        Raw header dict to fall back on for the other parameters.
+
+    Returns
+    -------
+    npt.NDArray[np.float64]
+        Chemical shift axis in ppm.
+    """
+    hz_axis = calculate_hz_axis(
+        spectral_width=spectral_width,
+        npts=npts,
+        header=header,
+    )
+
+    _freq = None
+    _carrier_ppm = None
+    _nuc = None
+
+    if frequency is not None:
+        _freq = frequency
+
+    if header is not None:
+        rdb_hdr = header.get("rdb_hdr", {})
+        if isinstance(rdb_hdr, dict):
+            if _freq is None:
+                _freq = rdb_hdr.get("ps_mps_freq", None)
+                if _freq is not None:
+                    _freq = np.double(_freq / 1e7)  # Convert to MHz
+        image_hdr = header.get("image", {})
+        if isinstance(image_hdr, dict):
+            _nuc = image_hdr.get("specnuc", None)
+
+    if _freq is None:
+        raise ValueError(
+            "Frequency information is required to calculate ppm axis. "
+            "Please provide frequency or ensure it is present in the header."
+        )
+
+    if nucleus is not None:
+        # Convert nucleus to integer if provided as string (e.g., '1H' -> 1) by
+        # extracting 1 to 3 digits from the string
+        if isinstance(nucleus, str):
+            import re
+
+            match = re.search(r"\d{1,3}", nucleus)
+            if match:
+                _nuc = int(match.group(0))
+            else:
+                logger.warning(
+                    f"Could not parse nucleus from string '{nucleus}'. Defaulting to 1H. "
+                    "This will offset ppm by 4.68!"
+                )
+                _nuc = 1
+        else:
+            _nuc = nucleus
+
+    if _nuc is not None and carrier_ppm is not None:
+        logger.warning(
+            "Both nucleus and carrier_ppm provided. Carrier ppm will be used for ppm "
+            "axis calculation."
+        )
+        _carrier_ppm = carrier_ppm
+    elif carrier_ppm is not None:
+        _carrier_ppm = carrier_ppm
+    elif _nuc is not None:
+        _carrier_ppm = 4.68 if _nuc in [1, 2] else 0.0
+    else:
+        logger.warning(
+            "Neither nucleus nor carrier_ppm provided. Defaulting to 1H with carrier ppm of "
+            "4.68. This will offset ppm by 4.68!"
+        )
+        _carrier_ppm = 4.68
+
+    ppm = (hz_axis / _freq) + _carrier_ppm
+    return ppm.astype(np.float64)

mnutils-1.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,41 @@
+mnutils/GEExam.py,sha256=-76gvH23SiS_Tlbf8GBqtRCeaYXyvq1MFdUKNim8I8Y,20077
+mnutils/GESeries.py,sha256=EXtTdSQAfK8lvRyLHwH0yFSOmtpAMMLNbAKiwV_6ato,61404
+mnutils/__init__.py,sha256=zw-6KymGUR7pvGeLaFR5idgaGuPgM6B444HvitP1tnw,1302
+mnutils/_scripts.py,sha256=1K1iCkVjuIoEDihLbG3O9NJ9CeYM2Tu_pI2bfvfHcMo,6716
+mnutils/fitting/AMARES.py,sha256=qAPV_hadASrlBVr6Ss9wOfZJGUP0MahrC3WhqZkaPTM,30042
+mnutils/fitting/__init__.py,sha256=o10Q9_phhEpwEtLNv56Muv7YjO2sZSl8vTjiIi2wdY0,114
+mnutils/matlab/__init__.py,sha256=YA4s6D3pdfjgi89qLtB3uQiOCb46iob3hGCRF39K08c,273
+mnutils/matlab/setup_matlab.py,sha256=Pk9UvPfY-QjCPAicKK1glH5qA4oor4QlYOavY_AiWgY,4411
+mnutils/plotting/__init__.py,sha256=SZyoLuhCIWfRotzrNSWdbE5lK6qQ4CnTbZgOWOTJTXU,926
+mnutils/plotting/_widgets/__init__.py,sha256=Dl4holZEoUKVK-8kK2IXZNny_QHCyqD2OzF7Dd0KC5E,217
+mnutils/plotting/_widgets/_html.py,sha256=_xWvz137-Ty4_uhZUJz4H_HlgoU3zOss9NbsIQdHCC8,1522
+mnutils/plotting/_widgets/_shared/__init__.py,sha256=O-_I4G_rJ8B4fF9LPMkheoWmbjiwzWs58iAuptZgf40,1673
+mnutils/plotting/_widgets/_shared/dom.js,sha256=tnjXuLTqj2Susq91XhntWo1SGKQFs2XdS8cw8QCj95k,4259
+mnutils/plotting/_widgets/_shared/theme.css,sha256=e6m2dmMUmvbJ9VQ9K2ZnwJk9Th6daL38O0kuLO4uvYs,3286
+mnutils/plotting/_widgets/image_grid.css,sha256=Qwwrwwjf6k6y97GtEPlUWHEirigtXRBdJZXDo5Pc8Jo,7404
+mnutils/plotting/_widgets/image_grid.js,sha256=aTIwG6isaMO4dGmcWj_mCTK5huDtxVmppgvA3V--yLc,7643
+mnutils/plotting/_widgets/image_grid.py,sha256=3PNy00lreYe4p8iO-yyVBRSNarwKwA2SD77imDDzRqQ,3365
+mnutils/plotting/_widgets/mrsi_inspector.css,sha256=pCxVPeXTRUB-qRLWsrzNLczsuOhWfYw9Fgv5XaB4pU0,12325
+mnutils/plotting/_widgets/mrsi_inspector.js,sha256=phwBT6PtuEXY3qpfQOOrZNRnfwc1CCyzvodMHrs06fA,26595
+mnutils/plotting/_widgets/mrsi_inspector.py,sha256=R0y6ENnicAEXoTwQqIBZwoW6b5aFl4dr9Ck0NvhMU0g,2579
+mnutils/plotting/_widgets/slice_viewer.css,sha256=HwQSjbxVPCfMOtHMdcRRCNIrBJVAG0tUjyfWFPmCbq4,686
+mnutils/plotting/_widgets/slice_viewer.js,sha256=9JAo0NHYFdn8PMIQIshRbbBdHtP_SpkAIsrpIAdMi4I,1072
+mnutils/plotting/_widgets/slice_viewer.py,sha256=L8LB91Fwqlh2zgVJnD2GQCXY2lVFENl2YgarRMjd2ic,1039
+mnutils/plotting/images.py,sha256=6Sxe-Dshk3bBpsgyCDU7UCYlS8YHtriuUPqj7r2wtwY,55585
+mnutils/plotting/saving.py,sha256=wk7yrlCcWcGW4bxwUNyCn7-vEUqlxluHeS6L0yhsUfg,3936
+mnutils/plotting/spectra.py,sha256=WsaQ5zsc5zgBsNucp2dAAT7VVyWTSZZeX3xA4BylAGs,11564
+mnutils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mnutils/testing/__init__.py,sha256=riccXHSgG6yMJV3hIM0QZHCtwXrRilz_b9WHyW_xAyk,70
+mnutils/testing/_spectra.py,sha256=tWn5ixg0y3iq7J8v1pOBAgHNrzC0xpF6mICz9nu_YQs,15460
+mnutils/testing/synthetic.py,sha256=wktyXHzThPfdxdgcer8R7Dk2oROiojElJumTzExNeMQ,12729
+mnutils/utils/__init__.py,sha256=GZMY9BwBLFdGPQyNdY7XViGP3Kr9ioZGoQCt0nEsrWw,589
+mnutils/utils/data_loaders.py,sha256=F4feHhCgthhmvIJ2TQgaYF9MkY6OhBiTb57t7F-3wQY,7785
+mnutils/utils/file_helpers.py,sha256=tBQRoObr2Yfn7BK96Mcp9Z_rE8dTC-NBZJmUPD_BBQY,23649
+mnutils/utils/images.py,sha256=Kq2Y-_oCIGMNh5ev5msR2kGJTxiYN7HndtuL3J4Yaj4,7278
+mnutils/utils/nifti.py,sha256=G3y_PospnZmfqxLjwtH4lWcBIS2Ikhyc4_9rdxwjNx4,14805
+mnutils/utils/spectra.py,sha256=P7fiBwacifh_6xxYa4FTq22z4VeLQoKnGxKJ-c0qGW0,4990
+mnutils-1.2.0.dist-info/licenses/LICENSE,sha256=74rhSzSkSwSeBsl16Rv-JlTy-XQvWxj5K-v80ouR_Fs,1507
+mnutils-1.2.0.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
+mnutils-1.2.0.dist-info/entry_points.txt,sha256=Mqz92Hi3-LREpPdJVQqyb_YKlt_Zcu-8N8yTIjMtxtc,264
+mnutils-1.2.0.dist-info/METADATA,sha256=X-9Jue90WLtsrs5Tzft_ihz74SN2pj_ty18vW-fo444,6169
+mnutils-1.2.0.dist-info/RECORD,,

mnutils-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.5
+Root-Is-Purelib: true
+Tag: py3-none-any

mnutils-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,7 @@
+[console_scripts]
+docs-mnutils = mnutils._scripts:docs_all
+docs-mnutils-api = mnutils._scripts:docs_api
+docs-mnutils-notebooks = mnutils._scripts:docs_notebooks
+test-mnutils = mnutils._scripts:run_tests
+test-mnutils-gen = mnutils._scripts:generate_test_notebooks
+

mnutils-1.2.0.dist-info/licenses/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.