pymiox 0.1.0__tar.gz

pymiox-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Julian P. Merkofer
+
+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.

pymiox-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# Source-distribution contents: the package, licence and README only.
+# Test data under tests/data is fetched by scripts/fetch_test_data.py and never shipped.
+include LICENSE
+include README.md

pymiox-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: pymiox
+Version: 0.1.0
+Summary: Open any MR file from any vendor into one object: data, geometry, all metadata.
+Author-email: "J. P. Merkofer" <j.p.merkofer@tue.nl>
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/julianmer/MIOX
+Keywords: MRS,MRI,spectroscopy,NIfTI-MRS,DICOM
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: f90nml>=1.5
+Requires-Dist: h5py>=3.10
+Requires-Dist: mat-io>=1.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: nibabel>=5.2
+Requires-Dist: nifti-mrs>=1.4
+Requires-Dist: nifti-mrs-plus>=0.2.1
+Requires-Dist: nmrglue>=0.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydicom>=3.0
+Requires-Dist: python-gdcm>=3.2.6
+Requires-Dist: spec2nii>=0.8.15
+Requires-Dist: zarr>=2.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: scipy>=1.15; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <img src="assets/logo.png" alt="MIOX Logo" width="100"/>
+  <h1 style="margin-top: 5px; margin-bottom: 5px;">MIOX</h1>
+  <p style="margin-top: 0px;"><em>Open any MR file from any vendor into one object: data, geometry, all metadata</em></p>
+
+  [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+  [![License](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](LICENSE)
+</div>
+
+---
+
+MIOX reads MR spectroscopy, images, raw k-space, sequences, protocols, physiological recordings
+and NMR data into one well-defined object each. It keeps the complete vendor header and records
+where every standard key came from.
+
+```python
+import miox
+[d] = miox.load("meas.dat")      # one object per dataset in the file
+d.data, d.dims, d.dwelltime      # complex FIDs in NIfTI-MRS order
+d.meta["EchoTime"], d.meta.source["EchoTime"], d.meta.vendor
+miox.view(d)                     # quick look in a window
+```
+
+## Installation
+
+```
+pip install pymiox
+```
+
+or, for development,
+
+```
+git clone https://github.com/julianmer/MIOX.git
+cd MIOX
+uv sync --extra dev
+```
+
+## What it loads
+
+| | Formats |
+|---|---|
+| **Spectroscopy** | Siemens twix, RDA and DICOM; Philips SPAR/SDAT, data/list and DICOM; UIH DICOM; GE P-file; Bruker; Varian; NIfTI-MRS; dcm2niix NIfTI with an MRS sidecar; LCModel .RAW; jMRUI text and binary; TARQUIN .dpt; VASF; Vespa VIFF; SIVIC DDF; FID-A .mat; text FIDs |
+| **Images** | DICOM (classic, mosaic, enhanced, study folders); NIfTI with BIDS sidecar; NIfTI-Zarr; JNIfTI; Analyze; MGH; MINC 1 and 2; PAR/REC; AFNI; NRRD; MetaImage; GIPL; Vista; Stimulate; VTK; MRtrix; SIVIC IDF; DSI Studio src and fib; BrainVoyager VMR, V16, VTC, FMR, VMP, GLM and VOI; Bruker 2dseq; Varian fdf; GE Signa |
+| **Raw k-space** | ISMRMRD; MRD v2; Siemens twix; GE P-file and ScanArchive; Philips raw/lab/sin; Bruker fid and rawdata; Varian fid; fastMRI; BART .cfl; Gadgetron array dumps |
+| **Basis sets and priors** | LCModel .BASIS; FSL-MRS; SpinWizard; Osprey/MRSCloud; INSPECTOR; MARSS; ProFit; MRS-Sim; spant; metabolite folders; Vespa, GAVA, MIDAS and PyAMARES priors |
+| **Fit results** | LCModel COORD, TABLE, CSV and PostScript tables; TARQUIN results and fit; PyAMARES; Osprey MRSCont; FSL-MRS dynamic; spant; DMIWizard maps |
+| **Sequences and protocols** | Pulseq .seq; TOPPE; FSL-MRS simulator sequences; Siemens .pta and Bruker RF pulse shapes; Siemens .pro, .exar and printed protocols; Philips ExamCards; LCModel control files; Yarra modes and modules; SPM.mat, FSL and BrainVoyager designs and stimulation protocols |
+| **Physio** | Siemens PMU; CMRR; Philips SCANPHYSLOG; GE; BIDS; HCP; BIOPAC AcqKnowledge |
+| **Simulation** | KomaMRI, JEMRIS and MRiLab phantoms; JEMRIS signals and motion; SIMPSON |
+| **NMR** | Bruker TopSpin; Varian/Agilent; JCAMP-DX; nmrML; JEOL Delta; Tecmag TNMR; NMRPipe; Sparky; CSDM; Magritek Spinsolve; RS2D; RNMRTK |
+| **Tractograms** | TrackVis .trk; MRtrix .tck and .tsf; TRX; VTK polydata; DSI Studio .tt |
+| **Surfaces** | FreeSurfer surfaces, per-vertex values, annotations and labels; GIFTI; BrainVoyager SRF, SMP, MTC, SSM and POI; MZ3 |
+| **Transforms** | FreeSurfer LTA; ITK; AFNI; FSL FLIRT; BrainVoyager TRF |

pymiox-0.1.0/README.md

@@ -0,0 +1,53 @@
+<div align="center">
+  <img src="assets/logo.png" alt="MIOX Logo" width="100"/>
+  <h1 style="margin-top: 5px; margin-bottom: 5px;">MIOX</h1>
+  <p style="margin-top: 0px;"><em>Open any MR file from any vendor into one object: data, geometry, all metadata</em></p>
+
+  [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+  [![License](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](LICENSE)
+</div>
+
+---
+
+MIOX reads MR spectroscopy, images, raw k-space, sequences, protocols, physiological recordings
+and NMR data into one well-defined object each. It keeps the complete vendor header and records
+where every standard key came from.
+
+```python
+import miox
+[d] = miox.load("meas.dat")      # one object per dataset in the file
+d.data, d.dims, d.dwelltime      # complex FIDs in NIfTI-MRS order
+d.meta["EchoTime"], d.meta.source["EchoTime"], d.meta.vendor
+miox.view(d)                     # quick look in a window
+```
+
+## Installation
+
+```
+pip install pymiox
+```
+
+or, for development,
+
+```
+git clone https://github.com/julianmer/MIOX.git
+cd MIOX
+uv sync --extra dev
+```
+
+## What it loads
+
+| | Formats |
+|---|---|
+| **Spectroscopy** | Siemens twix, RDA and DICOM; Philips SPAR/SDAT, data/list and DICOM; UIH DICOM; GE P-file; Bruker; Varian; NIfTI-MRS; dcm2niix NIfTI with an MRS sidecar; LCModel .RAW; jMRUI text and binary; TARQUIN .dpt; VASF; Vespa VIFF; SIVIC DDF; FID-A .mat; text FIDs |
+| **Images** | DICOM (classic, mosaic, enhanced, study folders); NIfTI with BIDS sidecar; NIfTI-Zarr; JNIfTI; Analyze; MGH; MINC 1 and 2; PAR/REC; AFNI; NRRD; MetaImage; GIPL; Vista; Stimulate; VTK; MRtrix; SIVIC IDF; DSI Studio src and fib; BrainVoyager VMR, V16, VTC, FMR, VMP, GLM and VOI; Bruker 2dseq; Varian fdf; GE Signa |
+| **Raw k-space** | ISMRMRD; MRD v2; Siemens twix; GE P-file and ScanArchive; Philips raw/lab/sin; Bruker fid and rawdata; Varian fid; fastMRI; BART .cfl; Gadgetron array dumps |
+| **Basis sets and priors** | LCModel .BASIS; FSL-MRS; SpinWizard; Osprey/MRSCloud; INSPECTOR; MARSS; ProFit; MRS-Sim; spant; metabolite folders; Vespa, GAVA, MIDAS and PyAMARES priors |
+| **Fit results** | LCModel COORD, TABLE, CSV and PostScript tables; TARQUIN results and fit; PyAMARES; Osprey MRSCont; FSL-MRS dynamic; spant; DMIWizard maps |
+| **Sequences and protocols** | Pulseq .seq; TOPPE; FSL-MRS simulator sequences; Siemens .pta and Bruker RF pulse shapes; Siemens .pro, .exar and printed protocols; Philips ExamCards; LCModel control files; Yarra modes and modules; SPM.mat, FSL and BrainVoyager designs and stimulation protocols |
+| **Physio** | Siemens PMU; CMRR; Philips SCANPHYSLOG; GE; BIDS; HCP; BIOPAC AcqKnowledge |
+| **Simulation** | KomaMRI, JEMRIS and MRiLab phantoms; JEMRIS signals and motion; SIMPSON |
+| **NMR** | Bruker TopSpin; Varian/Agilent; JCAMP-DX; nmrML; JEOL Delta; Tecmag TNMR; NMRPipe; Sparky; CSDM; Magritek Spinsolve; RS2D; RNMRTK |
+| **Tractograms** | TrackVis .trk; MRtrix .tck and .tsf; TRX; VTK polydata; DSI Studio .tt |
+| **Surfaces** | FreeSurfer surfaces, per-vertex values, annotations and labels; GIFTI; BrainVoyager SRF, SMP, MTC, SSM and POI; MZ3 |
+| **Transforms** | FreeSurfer LTA; ITK; AFNI; FSL FLIRT; BrainVoyager TRF |

pymiox-0.1.0/miox/__init__.py

@@ -0,0 +1,79 @@
+####################################################################################################
+#                                           __init__.py                                            #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 01/10/26                                                                                #
+#                                                                                                  #
+# Purpose: Package entry: the version and the top-level API.                                       #
+#                                                                                                  #
+####################################################################################################
+
+
+#*************#
+#   imports   #
+#*************#
+
+# own
+from miox.data import (
+    BasisSet,
+    FitResult,
+    MRImage,
+    MRSData,
+    NoiseCovariance,
+    Phantom,
+    PhysioData,
+    PriorSet,
+    Protocol,
+    Provenance,
+    PulseSequence,
+    RawData,
+    RelaxationData,
+    RFPulse,
+    Surface,
+    Tractogram,
+    Transform,
+)
+from miox.readers import IncompleteError, Loader, ReaderError, load
+from miox.sniff import Format, Kind, Sniff, Sniffer, sniff
+
+__version__ = "0.1.0"
+__all__ = [
+    "BasisSet",
+    "FitResult",
+    "Format",
+    "IncompleteError",
+    "Kind",
+    "Loader",
+    "MRImage",
+    "MRSData",
+    "NoiseCovariance",
+    "Phantom",
+    "PhysioData",
+    "PriorSet",
+    "Protocol",
+    "Provenance",
+    "PulseSequence",
+    "RawData",
+    "ReaderError",
+    "RelaxationData",
+    "RFPulse",
+    "Sniff",
+    "Sniffer",
+    "Surface",
+    "Tractogram",
+    "Transform",
+    "__version__",
+    "load",
+    "sniff",
+    "view",
+]
+
+
+def __getattr__(name: str):
+    if name == "view":  # on first use: matplotlib adds about 0.3 s to every import
+        from miox.viewer import view
+
+        return view
+    raise AttributeError(f"module 'miox' has no attribute {name!r}")

pymiox-0.1.0/miox/__main__.py

@@ -0,0 +1,22 @@
+####################################################################################################
+#                                           __main__.py                                            #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 12/10/26                                                                                #
+#                                                                                                  #
+# Purpose: ``python -m miox``: the command line, as the ``miox`` console script.                   #
+#                                                                                                  #
+####################################################################################################
+
+
+#*************#
+#   imports   #
+#*************#
+import sys
+
+# own
+from miox.cli import main
+
+sys.exit(main())

pymiox-0.1.0/miox/audit.py

@@ -0,0 +1,143 @@
+####################################################################################################
+#                                             audit.py                                             #
+####################################################################################################
+#                                                                                                  #
+# Authors: J. P. Merkofer (j.p.merkofer@tue.nl)                                                    #
+#                                                                                                  #
+# Created: 01/10/26                                                                                #
+#                                                                                                  #
+# Purpose: Coverage audit: every field of a file's vendor header, and whether a standard key, some #
+#          other key, or nothing is read from it.                                                  #
+#                                                                                                  #
+####################################################################################################
+
+
+#*************#
+#   imports   #
+#*************#
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+# own
+from miox.meta.keys import KeyTable
+from miox.readers import Loader
+from miox.sniff import Format
+
+
+#**************************************************************************************************#
+#                                              Status                                              #
+#**************************************************************************************************#
+#                                                                                                  #
+# What is read from a header field.                                                                #
+#                                                                                                  #
+#**************************************************************************************************#
+class Status(StrEnum):
+    STANDARD = "standard"  # a key of the key table
+    OTHER = "other"  # a key outside the key table, e.g. a user-defined NIfTI-MRS key
+    UNUSED = "unused"  # nothing
+
+
+#**************************************************************************************************#
+#                                              Field                                               #
+#**************************************************************************************************#
+#                                                                                                  #
+# One field of an audited vendor header.                                                           #
+#                                                                                                  #
+#**************************************************************************************************#
+@dataclass(frozen=True)
+class Field:
+    path: str
+    status: Status
+    key: str
+    """The key read from this field, empty if none."""
+    value: str
+    """Short preview of the value."""
+
+
+#**************************************************************************************************#
+#                                             Coverage                                             #
+#**************************************************************************************************#
+#                                                                                                  #
+# The audit of one file: all fields of its vendor header, with counts and a Markdown table.        #
+#                                                                                                  #
+#**************************************************************************************************#
+@dataclass(frozen=True)
+class Coverage:
+    path: Path
+    format: Format
+    fields: tuple[Field, ...]
+
+    def summary(self) -> dict[Status, int]:
+        counts = dict.fromkeys(Status, 0)
+        for f in self.fields:
+            counts[f.status] += 1
+        return counts
+
+    def to_markdown(self) -> str:
+        s = self.summary()
+        lines = [
+            f"# Coverage: `{self.path.name}` ({self.format})",
+            "",
+            f"{len(self.fields)} header fields: {s[Status.STANDARD]} read into standard keys, "
+            f"{s[Status.OTHER]} into other keys, {s[Status.UNUSED]} unused.",
+            "",
+            "| field | status | key | value |",
+            "|---|---|---|---|",
+        ]
+        for f in self.fields:
+            lines.append(f"| `{f.path}` | {f.status} | {f.key} | {f.value} |")
+        return "\n".join(lines) + "\n"
+
+
+#**************************************************************************************************#
+#                                             Auditor                                              #
+#**************************************************************************************************#
+#                                                                                                  #
+# Loads a file and matches its vendor header against the fields its keys were read from. A key     #
+# read from a nested block covers every field inside it.                                           #
+#                                                                                                  #
+#**************************************************************************************************#
+class Auditor:
+    PREVIEW_LIMIT = 60  # characters of a value shown in the table
+
+    def __init__(self):
+        self.loader = Loader()
+        self.keys = KeyTable()
+
+    def audit(self, path: str | Path) -> Coverage:
+        """Audit the metadata coverage of one file (all datasets in it)."""
+        path = Path(path)
+        datasets = self.loader.load(path)
+        read_from = {}  # vendor field -> key
+        for d in datasets:
+            read_from.update({field: key for key, field in d.meta.fields.items()})
+        fields = []
+        for field, value in datasets[0].meta.vendor_fields().items():
+            key = self._key(field, read_from)
+            if not key:
+                status = Status.UNUSED
+            elif key in self.keys:
+                status = Status.STANDARD
+            else:
+                status = Status.OTHER
+            fields.append(Field(field, status, key, self._preview(value)))
+        return Coverage(path, datasets[0].provenance.format, tuple(fields))
+
+    @staticmethod
+    def _key(field: str, read_from: dict[str, str]) -> str:
+        parts = field.split("/")
+        for n in range(len(parts), 0, -1):
+            key = read_from.get("/".join(parts[:n]))
+            if key:
+                return key
+        return ""
+
+    def _preview(self, value) -> str:
+        text = json.dumps(value, default=str)
+        if len(text) > self.PREVIEW_LIMIT:
+            text = text[: self.PREVIEW_LIMIT - 1] + "…"
+        return text.replace("|", "\\|")