MNutils 1.2.3__tar.gz → 1.3.0__tar.gz

{mnutils-1.2.3 → mnutils-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MNutils
-Version: 1.2.3
+Version: 1.3.0
 Summary: Utility functions for multinuclear MR data processing
 Keywords: mri,mrs,xarray,spectroscopy,nmr
 Author: Sebastian Bauer
@@ -14,7 +14,6 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
 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
@@ -26,7 +25,6 @@ Requires-Dist: scipy>=1.15.3
 Requires-Dist: seaborn>=0.13.2
 Requires-Dist: xarray>=2025.6.1
 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
@@ -34,7 +32,6 @@ 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
 
@@ -58,7 +55,7 @@ scanners.
 ## Features
 
 - **Data loading** — read GE raw/reconstructed data via `GEExam`/`GESeries`.
-- **NIfTI/DICOM conversion** — convert scanner output to NIfTI.
+- **NIfTI handling** — read dcm2niix-converted scanner output (NIfTI + JSON sidecar); DICOMs are not read.
 - **Plotting** — spectral and slice plotting utilities.
 - **Spectral fitting** — AMARES fitting delegated to [`xmris`](https://github.com/andrewendlinger/xmris)
   (`xmris[fitting]`, which wraps pyAMARES).
@@ -78,7 +75,6 @@ Optional extras:
 
 ```bash
 uv add "mnutils[bet]"     # brain extraction (hd-bet, torch)
-uv add "mnutils[2025a]"   # MATLAB Engine pinned to MATLAB 2025a
 ```
 
 To track the development version instead:
@@ -87,10 +83,8 @@ To track the development version instead:
 uv add git+https://github.com/bastigw/mnutils.git
 ```
 
-`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.
+The MATLAB Engine is not an extra: its version has to match your local MATLAB install, so you
+install it yourself (see [MATLAB Engine Dependency](#matlab-engine-dependency) below).
 
 ## Usage
 
@@ -123,8 +117,8 @@ already know a series's type, construct it directly (e.g. `MRSSeries(DATA_FOLDER
 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:
+— MNUtils deliberately doesn't reimplement fitting, a series hands its FIDs straight to xmris's
+AMARES implementation (itself built on pyAMARES) and returns the xmris result:
 
 ```bash
 uv add "xmris[fitting]"

{mnutils-1.2.3 → mnutils-1.3.0}/README.md

@@ -18,7 +18,7 @@ scanners.
 ## Features
 
 - **Data loading** — read GE raw/reconstructed data via `GEExam`/`GESeries`.
-- **NIfTI/DICOM conversion** — convert scanner output to NIfTI.
+- **NIfTI handling** — read dcm2niix-converted scanner output (NIfTI + JSON sidecar); DICOMs are not read.
 - **Plotting** — spectral and slice plotting utilities.
 - **Spectral fitting** — AMARES fitting delegated to [`xmris`](https://github.com/andrewendlinger/xmris)
   (`xmris[fitting]`, which wraps pyAMARES).
@@ -38,7 +38,6 @@ Optional extras:
 
 ```bash
 uv add "mnutils[bet]"     # brain extraction (hd-bet, torch)
-uv add "mnutils[2025a]"   # MATLAB Engine pinned to MATLAB 2025a
 ```
 
 To track the development version instead:
@@ -47,10 +46,8 @@ To track the development version instead:
 uv add git+https://github.com/bastigw/mnutils.git
 ```
 
-`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.
+The MATLAB Engine is not an extra: its version has to match your local MATLAB install, so you
+install it yourself (see [MATLAB Engine Dependency](#matlab-engine-dependency) below).
 
 ## Usage
 
@@ -83,8 +80,8 @@ already know a series's type, construct it directly (e.g. `MRSSeries(DATA_FOLDER
 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:
+— MNUtils deliberately doesn't reimplement fitting, a series hands its FIDs straight to xmris's
+AMARES implementation (itself built on pyAMARES) and returns the xmris result:
 
 ```bash
 uv add "xmris[fitting]"

{mnutils-1.2.3 → mnutils-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "MNutils"
-version = "1.2.3"
+version = "1.3.0"
 description = "Utility functions for multinuclear MR data processing"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -23,7 +23,6 @@ classifiers = [
 ]
 requires-python = ">=3.12"
 dependencies = [
-    "dcm2niiw>=0.1.5",
     "ipython>=8.0",
     "loguru>=0.7.3",
     "mat73",
@@ -48,7 +47,6 @@ 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",
@@ -62,7 +60,7 @@ 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"]
+requires = ["uv_build>=0.8.13,<0.14.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -78,10 +76,11 @@ dev = [
     "griffe<0.40.0",
     "jupyter-server>=2.17.0",
     "jupytext>=1.19.1",
+    "pytest-xdist>=3.8.0",
 ]
 
 [tool.pytest.ini_options]
-addopts = "--capture=no --nbmake"
+addopts = "--nbmake -n auto -v --durations=0"
 testpaths = ["tests"]
 
 [tool.uv.sources.mat73]

{mnutils-1.2.3 → mnutils-1.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "MNutils"
-version = "1.2.3"
+version = "1.3.0"
 
 authors = [
     {name = "Sebastian Bauer", email = "28663646+bastigw@users.noreply.github.com"}
@@ -25,7 +25,6 @@ classifiers = [
 requires-python = ">=3.12"
 
 dependencies = [
-    "dcm2niiw>=0.1.5",
     "ipython>=8.0",
     "loguru>=0.7.3",
     "mat73",
@@ -46,7 +45,6 @@ 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]
@@ -57,7 +55,7 @@ test-mnutils-gen = "mnutils._scripts:generate_test_notebooks"  # docs/*.md -> te
 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"]
+requires = ["uv_build>=0.8.13,<0.14.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -77,10 +75,12 @@ dev = [
     "griffe<0.40.0",            # Explicit pin to fix quartodoc parsing bug
     "jupyter-server>=2.17.0",   # Required for rendering docs
     "jupytext>=1.19.1",
+    "pytest-xdist>=3.8.0",
 ]
 
 [tool.pytest.ini_options]
-addopts = "--capture=no --nbmake"
+# See conftest.py for further details
+addopts = "--nbmake -n auto -v --durations=0"
 testpaths = ["tests"]
 
 # [tool.uv]

{mnutils-1.2.3 → mnutils-1.3.0}/src/mnutils/GEExam.py

@@ -16,6 +16,11 @@ from .utils import file_helpers
 ANATOMICAL_SERIES_TO_SKIP = ["FGRE", "localizer", "GE_HOS", "localiser"]
 
 
+def _normalise_description(description: object) -> str:
+    """Lower-case, spaces as underscores: ``MRS washin`` -> ``mrs_washin``."""
+    return description.strip().lower().replace(" ", "_") if isinstance(description, str) else ""
+
+
 class ExamBase:
     """Base class for a GE exam, loading series metadata and providing series access."""
 
@@ -24,6 +29,7 @@ class ExamBase:
         BASE_FOLDER: str | Path,
         DATA_FOLDER: str | Path | None = None,
         OUTPUT_FOLDER: str | Path | None = None,
+        show_overview: bool = False,
     ) -> None:
         self.BASE_FOLDER = Path(BASE_FOLDER)
         if DATA_FOLDER is None:
@@ -37,7 +43,9 @@ class ExamBase:
         else:
             self.OUTPUT_FOLDER = Path(OUTPUT_FOLDER)
 
-        self.exam_overview = file_helpers.get_exam_overview(self.DATA_FOLDER, print_overview=True)
+        self.exam_overview = file_helpers.get_exam_overview(
+            self.DATA_FOLDER, print_overview=show_overview
+        )
         self.series = self.exam_overview.index.tolist()
         self.series_dict = self._create_series_dict()
 
@@ -69,60 +77,45 @@ class ExamBase:
         """Iterate over loaded series as (series ID, series object) pairs."""
         yield from self.all.items()
 
+    def _ids_with_description(self, fragment: str) -> npt.NDArray[np.int_]:
+        """Series IDs whose normalised description contains `fragment` (also normalised)."""
+        normalised = self.exam_overview["Description"].map(_normalise_description)
+        mask = normalised.str.contains(_normalise_description(fragment), regex=False)
+        return self.exam_overview[mask].index.to_numpy().astype(int)
+
     def _create_series_dict(self) -> dict[int, type[GESeries.MRISeries]]:
+        """Pick a series class per series from its description, never from a folder name."""
         series_class_dict = {}
         for series_num in self.series:
-            folder_name = self.exam_overview.at[series_num, "Folder Name"]
+            raw_description = self.exam_overview.at[series_num, "Description"]
+            description = _normalise_description(raw_description)
             has_exam = self.exam_overview.at[series_num, "Has Exam"]
-            has_dicom = self.exam_overview.at[series_num, "Has DICOM"]
-
-            if has_exam and not has_dicom:
-                logger.debug(
-                    f"Series {series_num} does not have DICOM. Assuming it is an MRS series."
-                )
-                self.exam_overview.at[series_num, "Folder Name"] = "ASSUMING MRS"
-                series_class_dict[series_num] = GESeries.MRSSeries
-                continue
-
-            # Make sure folder name is a string
-            if isinstance(folder_name, str) and has_dicom:
-                folder_name = folder_name.strip().lower()
-            else:
-                logger.warning(
-                    f"Folder name for series {series_num} is not a string: {folder_name}. Skipping."
-                )
-                continue
-
-            if not has_exam and not has_dicom:
-                logger.debug(f"Series {series_num} does not have exam or DICOM data. Skipping")
-                continue
 
-            if has_dicom and not has_exam:
-                logger.trace(f"Series {series_num} does not have raw data.")
-                # Based on the folder name determine if it is anatomical data we want to load
-                if any(skip_name.lower() in folder_name for skip_name in ANATOMICAL_SERIES_TO_SKIP):
+            if not has_exam:
+                if any(skip_name.lower() in description for skip_name in ANATOMICAL_SERIES_TO_SKIP):
                     logger.debug(f"Series {series_num} is anatomical data to skip.")
                     continue
                 series_class_dict[series_num] = GESeries.MRISeries
                 continue
 
-            if has_exam and has_dicom:
-                logger.trace(
-                    f"Series {series_num} has both exam and DICOM data. Checking folder name."
+            if not description:
+                logger.debug(
+                    f"Series {series_num} has no series description. Assuming it is an MRS series."
+                )
+                series_class_dict[series_num] = GESeries.MRSSeries
+            elif "mrs_washin" in description:
+                series_class_dict[series_num] = GESeries.MRSWashinSeries
+            elif "mrsi" in description:
+                series_class_dict[series_num] = GESeries.MRSISeries
+            elif "mrs_" in description:
+                series_class_dict[series_num] = GESeries.MRSSeries
+            elif "bs_prescan" in description:
+                continue  # Skip the bs_prescan series
+            else:
+                logger.warning(
+                    f"Series {series_num} with description '{raw_description}' does not "
+                    f"match any known series types. Skipping."
                 )
-                if "mrs_washin" in folder_name:
-                    series_class_dict[series_num] = GESeries.MRSWashinSeries
-                elif "mrsi_pseudo" in folder_name:
-                    series_class_dict[series_num] = GESeries.MRSISeries
-                elif "mrs_" in folder_name:
-                    series_class_dict[series_num] = GESeries.MRSSeries
-                elif "bs_prescan" in folder_name:
-                    continue  # Skip the bs_prescan series
-                else:
-                    logger.warning(
-                        f"Series {series_num} with folder name '{folder_name}' does not "
-                        f"match any known series types. Skipping."
-                    )
 
         return series_class_dict
 
@@ -180,8 +173,9 @@ class DMIExam(ExamBase):
         DATA_FOLDER: str | Path | None = None,
         OUTPUT_FOLDER: str | Path | None = None,
         ANATOMICAL_series: str | int | None = None,
+        show_overview: bool = False,
     ) -> None:
-        super().__init__(BASE_FOLDER, DATA_FOLDER, OUTPUT_FOLDER)
+        super().__init__(BASE_FOLDER, DATA_FOLDER, OUTPUT_FOLDER, show_overview)
 
         if isinstance(ANATOMICAL_series, int):
             self.ANATOMICAL_series = ANATOMICAL_series
@@ -190,33 +184,22 @@ class DMIExam(ExamBase):
                 identifier = ANATOMICAL_series.strip().lower()
             else:
                 identifier = "t1_bravo"
-            self.ANATOMICAL_series = (
-                self.exam_overview[
-                    self.exam_overview["Folder Name"].str.contains(identifier, na=False, case=False)
-                ]
-                .index.to_numpy()
-                .astype(int)[0]
-            )
+            self.ANATOMICAL_series = self._ids_with_description(identifier)[0]
 
-        self.MRS_series = (
-            self.exam_overview[
-                self.exam_overview["Folder Name"].str.contains("MRS_unloc", na=False)
-            ]
-            .index.to_numpy()
-            .astype(int)
+        self.MRS_series = self._ids_with_description("MRS_unloc")
+        # By default append all series without a NIfTI (raw data only)
+        no_nifti_series = (
+            self.exam_overview[~self.exam_overview["Has NIfTI"]].index.to_numpy().astype(int)
         )
-        # By default append all series where Has Dicom in the exam overview table is False
-        no_DICOM_series = (
-            self.exam_overview[~self.exam_overview["Has DICOM"]].index.to_numpy().astype(int)
-        )
-        self.MRS_series = np.union1d(self.MRS_series, no_DICOM_series)
-
-        self.MRSI_series = (
-            self.exam_overview[
-                self.exam_overview["Folder Name"].str.contains("MRSI_pseudo", na=False)
-            ]
-            .index.to_numpy()
-            .astype(int)
+        self.MRS_series = np.union1d(self.MRS_series, no_nifti_series)
+
+        self.MRSI_series = np.array(
+            [
+                series_id
+                for series_id, series_class in self.series_dict.items()
+                if issubclass(series_class, GESeries.MRSISeries)
+            ],
+            dtype=int,
         )
 
         self.anatomical: GESeries.MRISeries
@@ -253,9 +236,9 @@ class DMIExam(ExamBase):
                     logger.warning(
                         f"Multiple anatomical datasets detected. "
                         f"Previous: Series ID {self.anatomical.SERIES_ID}, "
-                        f"Name '{self.exam_overview.at[self.anatomical.SERIES_ID, 'Folder Name']}'."
+                        f"Name '{self.exam_overview.at[self.anatomical.SERIES_ID, 'Description']}'."
                         f" New: Series ID {series_obj.SERIES_ID}, "
-                        f"Name '{self.exam_overview.at[series_obj.SERIES_ID, 'Folder Name']}'."
+                        f"Name '{self.exam_overview.at[series_obj.SERIES_ID, 'Description']}'."
                     )
                 self.anatomical = series_obj
 
@@ -269,9 +252,10 @@ class MS_DMIExam(DMIExam):
         DATA_FOLDER: str | Path | None = None,
         OUTPUT_FOLDER: str | Path | None = None,
         ANATOMICAL_series: str | int | None = None,
+        show_overview: bool = False,
     ) -> None:
-        super().__init__(BASE_FOLDER, DATA_FOLDER, OUTPUT_FOLDER, ANATOMICAL_series)
-        logger.info("MS DMI Exam initialized.")
+        super().__init__(BASE_FOLDER, DATA_FOLDER, OUTPUT_FOLDER, ANATOMICAL_series, show_overview)
+        logger.debug("MS DMI Exam initialized.")
 
         self.MRSI: GESeries.MRSISeries
         self.pre_MRS: GESeries.MRSSeries
@@ -330,16 +314,11 @@ class DMIinjExam(DMIExam):
         DATA_FOLDER: str | Path | None = None,
         OUTPUT_FOLDER: str | Path | None = None,
         ANATOMICAL_series: str | int | None = None,
+        show_overview: bool = False,
     ) -> None:
-        super().__init__(BASE_FOLDER, DATA_FOLDER, OUTPUT_FOLDER, ANATOMICAL_series)
-
-        self.WASHIN_series = (
-            self.exam_overview[
-                self.exam_overview["Folder Name"].str.contains("MRS_washin", na=False)
-            ]
-            .index.to_numpy()
-            .astype(int)[0]
-        )
+        super().__init__(BASE_FOLDER, DATA_FOLDER, OUTPUT_FOLDER, ANATOMICAL_series, show_overview)
+
+        self.WASHIN_series = self._ids_with_description("MRS_washin")[0]
 
         # Define pre and post series based on wash-in series
         self.pre_MRS_series, self.post_MRS_series = self._split_series(
@@ -349,7 +328,7 @@ class DMIinjExam(DMIExam):
             self.MRSI_series, self.WASHIN_series, "MRSI"
         )
 
-        logger.info("DMI Intravenous Injection Exam initialized.")
+        logger.debug("DMI Intravenous Injection Exam initialized.")
 
         self.washin: GESeries.MRSWashinSeries
         self.pre_MRS: GESeries.MRSSeries