MNutils 1.2.0__py3-none-any.whl

mnutils/__init__.py

@@ -0,0 +1,54 @@
+"""Utilities for working with multi-nuclear MR data from GE scanners.
+
+The public surface is re-exported here, so the common entry points are
+reachable without knowing the internal module layout::
+
+    import mnutils
+
+    exam = mnutils.DMIExam("/data/exam")
+    mnutils.plotting.images.display_images(exam.anatomical[0].data)
+
+`mnutils.matlab` is deliberately *not* imported here: it needs the optional
+`matlabengine` dependency, so import it explicitly when you need it.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import GEExam, GESeries, fitting, plotting, testing, utils
+from .GEExam import DMIExam, DMIinjExam, ExamBase, MS_DMIExam
+from .GESeries import (
+    MRISeries,
+    MRSISeries,
+    MRSSeries,
+    MRSWashinSeries,
+    NiiBase,
+    RawMRISeries,
+)
+
+try:
+    __version__ = version("mnutils")
+except PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    # subpackages / modules
+    "GEExam",
+    "GESeries",
+    "fitting",
+    "plotting",
+    "testing",
+    "utils",
+    # exam classes
+    "ExamBase",
+    "DMIExam",
+    "MS_DMIExam",
+    "DMIinjExam",
+    # series classes
+    "NiiBase",
+    "MRISeries",
+    "RawMRISeries",
+    "MRSISeries",
+    "MRSSeries",
+    "MRSWashinSeries",
+    "__version__",
+]

mnutils/_scripts.py

@@ -0,0 +1,177 @@
+"""Thin `uv run <name>` wrappers around the MyST/quartodoc docs toolchain.
+
+Simpler than the equivalent script in the sibling `xmris` package: MNUtils has
+no interactive-widget config classes to auto-document, so this is just
+`quartodoc build` (which emits Quarto Markdown, `.qmd`) followed by a
+translation pass into plain MyST Markdown (`.md`), then subprocess wrappers
+around `myst build`/`myst start`.
+"""
+
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _find_project_root() -> Path:
+    """Return the root of the MNUtils project, or exit if not found."""
+    for parent in Path(__file__).resolve().parents:
+        if (parent / "pyproject.toml").exists():
+            return parent
+    msg = "Error: could not find MNUtils project root (no pyproject.toml in any parent)"
+    raise RuntimeError(msg)
+
+
+def _get_docs_dir() -> Path:
+    docs_dir = _find_project_root() / "docs"
+
+    if not docs_dir.exists():
+        print(f"Error: 'docs' directory not found at: {docs_dir!s}")
+        sys.exit(1)
+
+    return docs_dir
+
+
+def _translate_qmd_to_myst(api_dir: Path) -> None:
+    """Convert quartodoc's `.qmd` output into plain MyST `.md`.
+
+    quartodoc targets Quarto by default; mystmd needs MyST Markdown instead.
+    This rewrites Quarto's `{.doc-method #anchor}` attribute blocks into
+    explicit `(anchor)=` MyST targets, drops leftover Quarto CSS blocks, and
+    downgrades any local link whose target didn't survive rather than
+    shipping a silently dead link. That downgrade is expected and routine
+    for plain attributes -- quartodoc's summary table links every attribute
+    by name, but (unlike methods) an attribute never gets its own anchored
+    section to link to, documented or not -- so it's counted, not printed
+    per occurrence; see the summary line `docs_api()` prints at the end.
+    """
+    downgraded = 0
+    for qmd_file in api_dir.rglob("*.qmd"):
+        content = qmd_file.read_text(encoding="utf-8")
+
+        # Fix internal file extensions to point to standard Markdown.
+        content = content.replace(".qmd", ".md")
+
+        # Converts: ### Heading {.doc-method #anchor}  ->  (anchor)= \n ### Heading
+        content = re.sub(
+            r"^(.*?)\s*\{[^\}]*?#([\w\.\-]+)[^\}]*\}\s*$",
+            r"(\2)=\n\1",
+            content,
+            flags=re.MULTILINE,
+        )
+        # Strip any leftover pure CSS blocks that didn't have an ID (e.g. {.doc-signature}).
+        content = re.sub(r"\s*\{\.[^\}]+\}", "", content)
+
+        valid_targets = set(re.findall(r"^\(([\w\.\-]+)\)=", content, flags=re.MULTILINE))
+
+        def link_replacer(match: re.Match) -> str:
+            nonlocal downgraded
+            text, anchor = match.group(1), match.group(2)
+            if anchor in valid_targets:
+                return match.group(0)
+            downgraded += 1
+            return f"`{text}`"
+
+        content = re.sub(r"\[([^\]]+)\]\(#([\w\.\-]+)\)", link_replacer, content)
+
+        md_file = qmd_file.with_suffix(".md")
+        md_file.write_text(content, encoding="utf-8")
+        qmd_file.unlink()
+
+    # Give the generated landing page a stable MyST target -- quartodoc emits
+    # a bare `# Function reference` with no anchor, so without this every
+    # link into the API chapter would resolve against a URL instead.
+    index_file = api_dir / "index.md"
+    if index_file.exists():
+        index_text = index_file.read_text(encoding="utf-8")
+        if not index_text.startswith("(api-home)="):
+            index_file.write_text(f"(api-home)=\n{index_text.lstrip()}", encoding="utf-8")
+
+    if downgraded:
+        print(
+            f"docs-api: downgraded {downgraded} dead attribute link(s) to plain text "
+            "(expected -- attributes never get their own anchor)"
+        )
+
+
+def docs_api() -> None:
+    """Regenerate the quartodoc API reference stubs under docs/api/."""
+    docs_dir = _get_docs_dir()
+    api_dir = docs_dir / "api"
+
+    if api_dir.exists():
+        shutil.rmtree(api_dir)
+    api_dir.mkdir(parents=True, exist_ok=True)
+
+    subprocess.run(["quartodoc", "build", "--config", "quartodoc.yml"], cwd=docs_dir, check=True)
+    _translate_qmd_to_myst(api_dir)
+
+
+def docs_notebooks() -> None:
+    """Serve a live preview of the docs, executing notebooks. Blocking."""
+    docs_dir = _get_docs_dir()
+    subprocess.run(["myst", "start", "--execute"], cwd=docs_dir, check=True)
+
+
+def docs_all() -> None:
+    """Regenerate API stubs, then serve a live preview. Blocking."""
+    docs_api()
+    docs_notebooks()
+
+
+# Docs chapters whose pages are executed as tests. One directory per sidebar
+# 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")
+
+
+def generate_test_notebooks() -> None:
+    """Convert every executable page under TEST_CHAPTERS into a test notebook.
+
+    Mirrors xmris's docs-are-the-tests pattern: a page only joins the suite
+    once it carries a jupytext kernelspec (frontmatter-less pages, like a bare
+    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.
+    """
+    project_root = _find_project_root()
+    docs_dir = project_root / "docs"
+    out_root = project_root / "tests" / "autogen_notebooks"
+
+    if out_root.exists():
+        shutil.rmtree(out_root)
+
+    for chapter in TEST_CHAPTERS:
+        chapter_dir = docs_dir / chapter
+        if not chapter_dir.is_dir():
+            continue
+        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,
+            )
+
+
+def _is_executable_page(md_file: Path) -> bool:
+    """A page joins the test suite only if it carries a jupytext kernelspec."""
+    head = md_file.read_text(encoding="utf-8")[:400]
+    return head.startswith("---") and "kernelspec:" in head
+
+
+def run_tests() -> None:
+    """Regenerate the notebook tests from docs, then run the full pytest suite."""
+    generate_test_notebooks()
+    subprocess.run(["pytest"], check=True)