MNutils 1.2.3__tar.gz → 1.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MNutils
-Version: 1.2.3
+Version: 1.2.4
 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
 

{mnutils-1.2.3 → mnutils-1.2.4}/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
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "MNutils"
-version = "1.2.3"
+version = "1.2.4"
 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.2.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "MNutils"
-version = "1.2.3"
+version = "1.2.4"
 
 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.2.4}/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."""
 
@@ -69,60 +74,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
 
@@ -190,33 +180,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)
-        )
-        # 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 = 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)
         )
-        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 +232,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
 
@@ -333,13 +312,7 @@ class DMIinjExam(DMIExam):
     ) -> 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]
-        )
+        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(

{mnutils-1.2.3 → mnutils-1.2.4}/src/mnutils/GESeries.py

@@ -8,7 +8,6 @@ import h5py
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
-import pyAMARES
 import xarray as xr
 import xmris  # noqa: F401, necessary for xarray accessor to work
 from loguru import logger
@@ -283,7 +282,7 @@ class NiiBase:
 
 
 class MRISeries(NiiBase):
-    """A reconstructed MRI series, loaded as a NIfTI from a scan's DATA_FOLDER."""
+    """A reconstructed MRI series, loaded as a NIfTI (found by its sidecar's SeriesNumber)."""
 
     def __init__(
         self,
@@ -295,9 +294,7 @@ class MRISeries(NiiBase):
         self.OUTPUT_FOLDER = (DATA_FOLDER / ".." / "output").resolve()
         self.SERIES_ID = SERIES_ID
         try:
-            nii_path: Path = file_helpers.get_niftis_from_series(
-                self.DATA_FOLDER, self.SERIES_ID, convert_dicoms=True
-            )
+            nii_path: Path = file_helpers.get_niftis_from_series(self.DATA_FOLDER, self.SERIES_ID)
             super().__init__(nii_path, orientation)
         except (ValueError, FileNotFoundError) as e:
             logger.warning(
@@ -307,17 +304,71 @@ class MRISeries(NiiBase):
 
 
 class RawMRISeries(MRISeries):
-    """An MRI series with the associated raw reconstructed .mat data loaded."""
+    """An MRI series with the associated raw reconstructed .mat data loaded.
 
-    def __init__(self, DATA_FOLDER: Path, SERIES_ID: int) -> None:
+    The ``.mat`` is optional at construction: if none is found, a warning is logged and
+    `mat_path` is ``None``. Using the data (`recon`, `bb`, header properties) then raises.
+    Check `has_mat` first when a series may lack one.
+    """
+
+    def __init__(
+        self, DATA_FOLDER: Path, SERIES_ID: int, mat_path: str | Path | None = None
+    ) -> None:
         super().__init__(DATA_FOLDER, SERIES_ID)
-        self.mat_path: Path = file_helpers.get_mat_data_from_series(
-            self.DATA_FOLDER, self.SERIES_ID
+        self.mat_path: Path | None
+        self.header: dict
+        if mat_path is not None:
+            self.mat_path = Path(mat_path)
+        else:
+            try:
+                self.mat_path = file_helpers.get_mat_data_from_series(
+                    self.DATA_FOLDER, self.SERIES_ID
+                )
+            except FileNotFoundError as e:
+                logger.warning(
+                    f"Could not find a .mat file for series {self.SERIES_ID}. "
+                    f"Proceeding without raw data.\nError: {e}"
+                )
+                self.mat_path = None
+        # Only the header fields MNUtils reads: a v7.3 header is ~1600 HDF5 datasets (~0.45 s).
+        self.header = (
+            data_loaders.read_mat_header(self.mat_path) if self.mat_path is not None else {}
         )
-        self.recon: dict = data_loaders.load_mat_file(self.mat_path)
-        self.header: dict = self.recon.get("h", {})
-        self.bb = self.recon.get("bb", np.array([]))
-        self.bbabs = self.recon.get("bbabs", np.abs(self.bb))
+
+    @property
+    def has_mat(self) -> bool:
+        """Whether this series has a ``.mat`` file to read raw data and header from."""
+        return self.mat_path is not None
+
+    def _require_mat(self) -> Path:
+        if self.mat_path is None:
+            raise FileNotFoundError(
+                f"Series {self.SERIES_ID} has no .mat file (looked in {self.DATA_FOLDER})."
+            )
+        return self.mat_path
+
+    @cached_property
+    def recon(self) -> dict:
+        """Every top-level variable of the ``.mat`` file, with ``h`` pruned to `self.header`.
+
+        Loaded on first access, not at construction, so reading only the header stays cheap.
+        The full ``h`` (~1600 datasets on v7.3) is skipped; use ``load_mat_file`` for it.
+        """
+        mat_path = self._require_mat()
+        names = [n for n in data_loaders.list_mat_variables(mat_path) if n != "h"]
+        recon = data_loaders.load_mat_file(mat_path, variable_names=names)
+        recon["h"] = self.header
+        return recon
+
+    @cached_property
+    def bb(self) -> np.ndarray:
+        """The reconstructed image, or an empty array if the file has none."""
+        return self.recon.get("bb", np.array([]))
+
+    @cached_property
+    def bbabs(self) -> np.ndarray:
+        """The magnitude image: ``bbabs`` from the file, else ``abs(bb)``."""
+        return self.recon.get("bbabs", np.abs(self.bb))
 
     @cached_property
     def fids(self) -> xr.DataArray:
@@ -597,8 +648,10 @@ class RawMRISeries(MRISeries):
     def _get_header_value(self, key_path: list[str]) -> None | str | np.double | npt.NDArray:
         """Traverse the header dictionary using a key path.
 
-        Raises AttributeError if the path is invalid.
+        Raises AttributeError if the path is invalid, FileNotFoundError if the series has no
+        ``.mat`` (and so no header).
         """
+        self._require_mat()
         value = self.header
         try:
             for key in key_path:
@@ -632,11 +685,13 @@ class MRSISeries(RawMRISeries):
     ) -> None:
         super().__init__(DATA_FOLDER, SERIES_ID)
         # Expect spec and header to be present
-        spec_data = self.recon.get("spec", np.ndarray([]))
+        spec_data = self.recon.get("spec", np.ndarray([])) if self.has_mat else np.empty(0)
         if not isinstance(spec_data, np.ndarray) or spec_data.size == 0:
-            logger.error(
-                "Expected 'spec' to be a non-empty numpy array. Not initializing object properly"
-            )
+            if self.has_mat:  # without a .mat the missing data was already warned about
+                logger.error(
+                    "Expected 'spec' to be a non-empty numpy array. "
+                    "Not initializing object properly"
+                )
         else:
             self.spec: xr.DataArray = xr.DataArray(
                 spec_data,
@@ -701,6 +756,8 @@ class MRSISeries(RawMRISeries):
     @cached_property
     def SNR_map(self) -> xr.DataArray:
         """The per-voxel SNR, computed from the FIDs via pyAMARES.fidSNR."""
+        import pyAMARES
+
         return xr.apply_ufunc(
             pyAMARES.fidSNR, self.fids, input_core_dims=[["time"]], vectorize=True
         )
@@ -1264,11 +1321,13 @@ class MRSSeries(RawMRISeries):
 
     def __init__(self, DATA_FOLDER: Path, SERIES_ID: int) -> None:
         super().__init__(DATA_FOLDER, SERIES_ID)
-        spec_data = self.recon.get("spec", np.ndarray([]))
+        spec_data = self.recon.get("spec", np.ndarray([])) if self.has_mat else np.empty(0)
         if not isinstance(spec_data, np.ndarray) or spec_data.size == 0:
-            logger.error(
-                "Expected 'spec' to be a non-empty numpy array. Not initializing object properly"
-            )
+            if self.has_mat:  # without a .mat the missing data was already warned about
+                logger.error(
+                    "Expected 'spec' to be a non-empty numpy array. "
+                    "Not initializing object properly"
+                )
         else:
             # This assumes no zero filling was applied yet
             self.npts: int = spec_data.shape[1]

{mnutils-1.2.3 → mnutils-1.2.4}/src/mnutils/__init__.py

@@ -8,6 +8,11 @@ reachable without knowing the internal module layout::
     exam = mnutils.DMIExam("/data/exam")
     mnutils.plotting.images.display_images(exam.anatomical[0].data)
 
+Package-wide defaults live in `mnutils.rcParams`, which works like
+matplotlib's::
+
+    mnutils.rcParams["image.cmap"] = "viridis"
+
 `mnutils.matlab` is deliberately *not* imported here: it needs the optional
 `matlabengine` dependency, so import it explicitly when you need it.
 """
@@ -24,6 +29,7 @@ from .GESeries import (
     NiiBase,
     RawMRISeries,
 )
+from .rcparams import RcParams, rc_context, rc_presets, rcdefaults, rcParams, rcParamsDefault
 
 try:
     __version__ = version("mnutils")
@@ -50,5 +56,12 @@ __all__ = [
     "MRSISeries",
     "MRSSeries",
     "MRSWashinSeries",
+    # configuration
+    "RcParams",
+    "rcParams",
+    "rcParamsDefault",
+    "rc_context",
+    "rc_presets",
+    "rcdefaults",
     "__version__",
 ]

{mnutils-1.2.3 → mnutils-1.2.4}/src/mnutils/_scripts.py

@@ -11,6 +11,7 @@ import re
 import shutil
 import subprocess
 import sys
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 
@@ -124,7 +125,24 @@ def docs_all() -> None:
 # chapter, mirrored into tests/autogen_notebooks/<chapter>/. Keep in sync with
 # GENRES in .claude/skills/docs-page/check_docs.py -- that file decides which
 # house rules a chapter's pages are held to, this one decides which get run.
-TEST_CHAPTERS = ("basics", "data-model", "plotting", "fitting", "nifti", "matlab")
+# `matlab` is deliberately excluded: its pages need a live MATLAB install and
+# a matching `matlabengine` version (see CLAUDE.md's Gotchas), which no CI or
+# contributor machine can be assumed to have -- it isn't run by default.
+TEST_CHAPTERS = ("basics", "data-model", "plotting", "fitting", "nifti")
+
+
+def _convert_to_notebook(md_file: Path, out_dir: Path) -> None:
+    subprocess.run(
+        [
+            "jupytext",
+            "--to",
+            "notebook",
+            "--output",
+            str(out_dir / f"{md_file.stem}.ipynb"),
+            str(md_file),
+        ],
+        check=True,
+    )
 
 
 def generate_test_notebooks() -> None:
@@ -135,6 +153,11 @@ def generate_test_notebooks() -> None:
     chapter `index.md`, are skipped rather than failing with no kernel to
     start). Output goes under tests/autogen_notebooks/, which is gitignored --
     regenerate it before running pytest, never commit it.
+
+    Each page is its own `jupytext` subprocess (~0.3-0.5s of interpreter
+    startup apiece) with nothing shared between them, so they run in a thread
+    pool -- the GIL doesn't matter here since every thread spends its time
+    blocked in `subprocess.run`, not executing Python.
     """
     project_root = _find_project_root()
     docs_dir = project_root / "docs"
@@ -143,26 +166,21 @@ def generate_test_notebooks() -> None:
     if out_root.exists():
         shutil.rmtree(out_root)
 
+    jobs: list[tuple[Path, Path]] = []
     for chapter in TEST_CHAPTERS:
         chapter_dir = docs_dir / chapter
         if not chapter_dir.is_dir():
             continue
+        out_dir = out_root / chapter
         for md_file in sorted(chapter_dir.glob("*.md")):
-            if not _is_executable_page(md_file):
-                continue
-            out_dir = out_root / chapter
-            out_dir.mkdir(parents=True, exist_ok=True)
-            subprocess.run(
-                [
-                    "jupytext",
-                    "--to",
-                    "notebook",
-                    "--output",
-                    str(out_dir / f"{md_file.stem}.ipynb"),
-                    str(md_file),
-                ],
-                check=True,
-            )
+            if _is_executable_page(md_file):
+                jobs.append((md_file, out_dir))
+
+    for out_dir in {out_dir for _, out_dir in jobs}:
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+    with ThreadPoolExecutor() as pool:
+        list(pool.map(lambda job: _convert_to_notebook(*job), jobs))
 
 
 def _is_executable_page(md_file: Path) -> bool:

mnutils-1.2.4/src/mnutils/fitting/__init__.py

@@ -0,0 +1,16 @@
+"""Spectral fitting, delegated to pyAMARES through a thin wrapper."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from . import AMARES
+
+__all__ = ["AMARES"]
+
+
+def __getattr__(name: str):
+    if name == "AMARES":
+        from . import AMARES
+
+        return AMARES
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")