openads 2.0.0__py3-none-any.whl

openads/__init__.py

@@ -0,0 +1,77 @@
+"""OpenADS: acute stroke DWI/PWI pipelines.
+
+``import openads`` is light: it imports no torch, ants, shap, matplotlib, surfa or
+sklearn. Public names load on first access (PEP 562).
+
+Example:
+    >>> import openads
+    >>> openads.__version__  # doctest: +SKIP
+    '2.0.0'
+    >>> res = openads.run_dwi("sub-01", all_stages=True, output_root="out")  # doctest: +SKIP
+    >>> res = openads.run_stage(  # doctest: +SKIP
+    ...     "gen_mask", subject_id="sub-01", modality="DWI", output_root="out"
+    ... )
+
+Subpackages, from the top of the layering down: ``cli`` -> ``pipelines`` ->
+``stages`` -> ``steps`` -> ``ops``/``io``/``models``/``core``; ``config``,
+``inputs``, ``registry`` and ``assets`` support them.
+"""
+
+from openads._lazy import attach as _attach
+from openads._version import __version__
+
+__getattr__, __dir__, _names = _attach(
+    __name__,
+    submodules=[
+        "assets",
+        "cli",
+        "config",
+        "core",
+        "errors",
+        "inputs",
+        "io",
+        "logging",
+        "models",
+        "ops",
+        "pipelines",
+        "registry",
+        "stages",
+        "steps",
+    ],
+    attributes={
+        # running
+        "run_dwi": "openads.pipelines",
+        "run_pwi": "openads.pipelines",
+        "run_combined": "openads.pipelines",
+        "run_stage": "openads.pipelines",
+        "get_pipeline": "openads.pipelines",
+        "Pipeline": "openads.pipelines",
+        "RunPlan": "openads.pipelines",
+        "PipelineResult": "openads.core.result",
+        "StageResult": "openads.core.result",
+        # configuration and inputs
+        "load_config": "openads.config.loader",
+        "PipelineConfig": "openads.config.schema",
+        "SubjectSpec": "openads.inputs.spec",
+        "discover_inputs": "openads.inputs.discovery",
+        "example_subjects": "openads.assets",
+        "download_assets": "openads.assets",
+        # workspace and layout
+        "SubjectWorkspace": "openads.core.workspace",
+        "OutputLayout": "openads.core.layout",
+        "ARTIFACTS": "openads.core.layout",
+        "Modality": "openads.core.types",
+        # extension
+        "register": "openads.registry",
+        "Registry": "openads.registry",
+        "register_stage": "openads.stages",
+        "get_stage": "openads.stages",
+        "list_stages": "openads.stages",
+        "Stage": "openads.stages.base",
+        "StageContext": "openads.stages.base",
+        "StageSpec": "openads.stages.base",
+        "parse_ref": "openads.stages",
+    },
+)
+
+__all__ = ["__version__", *_names]

openads/__main__.py

@@ -0,0 +1,8 @@
+"""Run the OpenADS CLI with ``python -m openads``."""
+
+import sys
+
+from openads.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

openads/_lazy.py

@@ -0,0 +1,70 @@
+"""Helpers for lazy imports.
+
+Heavy third-party libraries (torch, ants, surfa, shap, matplotlib, sklearn)
+must never be imported when ``import openads`` runs. Modules use :func:`require`
+inside functions, and packages use :func:`attach` to expose submodules and
+attributes on first access (PEP 562).
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable, Iterable, Mapping
+from types import ModuleType
+from typing import Any
+
+__all__ = ["attach", "require"]
+
+
+def require(module: str, *, purpose: str = "") -> ModuleType:
+    """Import ``module`` now and return it, with a clear error if it is missing.
+
+    Args:
+        module: Absolute module name, for example ``"torch"``.
+        purpose: Short text for the error message, for example ``"SynthStrip"``.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: If the module cannot be imported.
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        why = f" (needed for {purpose})" if purpose else ""
+        raise ImportError(f"OpenADS needs the package providing '{module}'{why}: {exc}") from exc
+
+
+def attach(
+    package: str,
+    submodules: Iterable[str] = (),
+    attributes: Mapping[str, str] | None = None,
+) -> tuple[Callable[[str], Any], Callable[[], list[str]], list[str]]:
+    """Build ``__getattr__``, ``__dir__`` and ``__all__`` for a lazy package.
+
+    Args:
+        package: The package name (``__name__`` of the caller).
+        submodules: Submodule names that load on first attribute access.
+        attributes: Map of attribute name to the module that defines it
+            (relative names start with a dot, for example ``".workspace"``).
+
+    Returns:
+        A tuple ``(__getattr__, __dir__, __all__)``.
+    """
+    subs = set(submodules)
+    attrs = dict(attributes or {})
+    names = sorted(subs | set(attrs))
+
+    def __getattr__(name: str) -> Any:  # noqa: N807
+        if name in subs:
+            return importlib.import_module(f"{package}.{name}")
+        if name in attrs:
+            mod = importlib.import_module(attrs[name], package)
+            return getattr(mod, name)
+        raise AttributeError(f"module {package!r} has no attribute {name!r}")
+
+    def __dir__() -> list[str]:  # noqa: N807
+        return list(names)
+
+    return __getattr__, __dir__, list(names)

openads/_version.py

@@ -0,0 +1,5 @@
+"""Single source of the package version."""
+
+__all__ = ["__version__"]
+
+__version__ = "2.0.0"

openads/assets/__init__.py

@@ -0,0 +1,162 @@
+"""Asset resolution (model weights, atlases, templates, example data).
+
+Assets are not part of the wheel (about 320 MB). The assets root is found in
+this order (AMENDMENTS A5); the first candidate that exists wins, and there is
+no per-file fall-through to later candidates:
+
+1. the explicit ``assets_dir`` argument (``paths.assets_dir`` in the config),
+2. the ``ADS_ASSETS_DIR`` environment variable,
+3. ``<repo>/assets`` when the package runs from a source checkout,
+4. the user cache ``$XDG_CACHE_HOME/openads/assets`` (default
+   ``~/.cache/openads/assets``).
+
+Nothing is downloaded implicitly. ``openads assets download`` (:func:`download`)
+fetches the manifest's files from a public mirror into the user cache (or
+``ADS_ASSETS_DIR``), verifying each SHA-256; running it accepts the licence it
+prints. Lookups only check that a file exists. SHA-256 verification of a
+folder runs on request (``openads assets verify``).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from openads.assets.manifest import AssetEntry, AssetStatus, load_manifest, verify
+from openads.errors import AssetNotFoundError
+
+__all__ = [
+    "ENV_VAR",
+    "AssetEntry",
+    "AssetStatus",
+    "DownloadReport",
+    "assets_root",
+    "candidate_roots",
+    "download",
+    "download_assets",
+    "example_subjects",
+    "load_manifest",
+    "resolve",
+    "verify",
+]
+
+#: Environment variable that points to the assets root.
+ENV_VAR = "ADS_ASSETS_DIR"
+
+
+def _repo_assets() -> Path | None:
+    """``<repo>/assets`` if this package runs from a source checkout."""
+    pkg = Path(__file__).resolve().parents[1]  # .../src/ads
+    repo = pkg.parents[1]  # .../<repo>
+    if (pkg.parent.name == "src") and (repo / "pyproject.toml").is_file():
+        return repo / "assets"
+    return None
+
+
+def _cache_assets() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "openads" / "assets"
+
+
+def candidate_roots(assets_dir: Path | str | None = None) -> list[tuple[str, Path]]:
+    """Candidate assets roots in resolution order, labelled by their source.
+
+    Args:
+        assets_dir: Explicit assets folder.
+
+    Returns:
+        ``[(source, path), ...]``; sources are ``argument``, ``ADS_ASSETS_DIR``,
+        ``repository`` and ``user-cache``.
+    """
+    out: list[tuple[str, Path]] = []
+    if assets_dir is not None:
+        out.append(("argument", Path(assets_dir).expanduser()))
+    env = os.environ.get(ENV_VAR)
+    if env:
+        out.append((ENV_VAR, Path(env).expanduser()))
+    repo = _repo_assets()
+    if repo is not None:
+        out.append(("repository", repo))
+    out.append(("user-cache", _cache_assets()))
+    return out
+
+
+def assets_root(assets_dir: Path | str | None = None) -> Path:
+    """Return the first existing assets root.
+
+    An explicit ``assets_dir`` or ``ADS_ASSETS_DIR`` that does not exist is an
+    error (it is never skipped silently).
+
+    Raises:
+        AssetNotFoundError: If no candidate exists.
+    """
+    tried = []
+    for source, path in candidate_roots(assets_dir):
+        if path.is_dir():
+            return path
+        if source in ("argument", ENV_VAR):
+            raise AssetNotFoundError(f"assets folder from {source} does not exist: {path}")
+        tried.append(f"{source}: {path}")
+    raise AssetNotFoundError(
+        "no assets folder found; run `openads assets download` (or set ADS_ASSETS_DIR or "
+        "paths.assets_dir). Tried: " + "; ".join(tried)
+    )
+
+
+def resolve(rel: Path | str, *, assets_dir: Path | str | None = None) -> Path:
+    """Resolve an asset path.
+
+    Args:
+        rel: Path relative to the assets root (``"models/synthstrip.1.pt"``),
+            or an absolute path (returned unchanged if it exists).
+        assets_dir: Explicit assets folder (highest priority).
+
+    Returns:
+        The existing path.
+
+    Raises:
+        AssetNotFoundError: If the file or folder does not exist.
+    """
+    p = Path(rel).expanduser()
+    if p.is_absolute():
+        if not p.exists():
+            raise AssetNotFoundError(f"asset not found: {p}")
+        return p
+    root = assets_root(assets_dir)
+    full = root / p
+    if not full.exists():
+        raise AssetNotFoundError(
+            f"asset {p.as_posix()!r} not found under {root}; run `openads assets download`"
+        )
+    return full
+
+
+def example_subjects(
+    modality: str | None = None, *, assets_dir: Path | str | None = None
+) -> list[Path]:
+    """List the bundled example subject folders (``examples/<mod>/sub-*``).
+
+    Args:
+        modality: ``"dwi"`` or ``"pwi"`` (case-insensitive); ``None`` lists both.
+        assets_dir: Explicit assets folder (highest priority).
+
+    Returns:
+        Sorted subject folders; empty if the assets have no examples.
+
+    Raises:
+        ValueError: On an unknown modality.
+        AssetNotFoundError: If no assets folder exists.
+    """
+    mods = ["dwi", "pwi"] if modality is None else [modality.lower()]
+    if any(m not in ("dwi", "pwi") for m in mods):
+        raise ValueError(f"modality must be 'dwi' or 'pwi', got {modality!r}")
+    root = assets_root(assets_dir) / "examples"
+    return sorted(
+        d for m in mods if (root / m).is_dir() for d in (root / m).iterdir() if d.is_dir()
+    )
+
+
+from openads.assets.fetch import DownloadReport, download  # noqa: E402  (needs the names above)
+
+#: Same as :func:`download`, under the name exported at the package top level.
+download_assets = download

openads/assets/fetch.py

@@ -0,0 +1,157 @@
+"""Download the assets (model weights, atlases, example subjects) of the packaged manifest.
+
+The wheel ships code only. ``openads assets download`` (or :func:`download`) fetches the files
+from a public mirror, by default the ``assets/`` folder of the official farialab/OpenADS GitHub
+repository at a fixed commit (:data:`DEFAULT_URL`), verifies each one
+against the manifest's SHA-256 and writes it under the assets root. Nothing is downloaded
+implicitly: running the command is the user's acceptance of the licence in :data:`NOTICE`.
+Files already present with the right digest are skipped, so the command is safe to re-run.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from openads.assets.manifest import AssetEntry, load_manifest, sha256
+
+__all__ = [
+    "DEFAULT_COMMIT",
+    "DEFAULT_URL",
+    "NOTICE",
+    "URL_ENV_VAR",
+    "DownloadReport",
+    "default_target",
+    "download",
+]
+
+#: Mirror holding the assets at the same relative paths as the manifest: ``assets/`` of
+#: farialab/OpenADS, pinned to the commit the manifest was made from (6c378d1, OpenADS 1.0), so a
+#: later change on ``main`` cannot make a download fail verification.
+DEFAULT_COMMIT = "6c378d1ae36278c9351c247e00286f19e0a893ac"
+DEFAULT_URL = f"https://raw.githubusercontent.com/farialab/OpenADS/{DEFAULT_COMMIT}/assets"
+#: Environment variable that replaces :data:`DEFAULT_URL` (another mirror, a local copy via ``file://``).
+URL_ENV_VAR = "ADS_ASSETS_URL"
+
+NOTICE = """\
+OpenADS model weights, atlases and example data are distributed under the JHU Non-Profit Research
+Software License Agreement (see the LICENSE file of the openads package): non-commercial, non-profit
+research and education only; commercial use, including research by for-profit entities, needs a
+separate written licence from Johns Hopkins University; cite OpenADS in publications.
+By downloading these files you accept this licence."""
+
+
+@dataclass
+class DownloadReport:
+    """What :func:`download` did.
+
+    Attributes:
+        root: Assets root written to.
+        downloaded: Paths fetched and verified.
+        present: Paths already there with the right digest.
+        missing: Paths the mirror does not have (HTTP 404).
+        failed: ``(path, reason)`` for other errors, including a digest mismatch.
+    """
+
+    root: Path
+    downloaded: list[str] = field(default_factory=list)
+    present: list[str] = field(default_factory=list)
+    missing: list[str] = field(default_factory=list)
+    failed: list[tuple[str, str]] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """Every requested file is present and verified."""
+        return not self.missing and not self.failed
+
+
+def default_target() -> Path:
+    """Target folder when none is given.
+
+    ``ADS_ASSETS_DIR`` if set, else the user cache that :func:`openads.assets.assets_root`
+    searches last.
+    """
+    from openads.assets import ENV_VAR, _cache_assets
+
+    env = os.environ.get(ENV_VAR)
+    return Path(env).expanduser() if env else _cache_assets()
+
+
+def _fetch(url: str, dest: Path, entry: AssetEntry) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=dest.parent, prefix=".part-")
+    try:
+        with os.fdopen(fd, "wb") as out, urllib.request.urlopen(url, timeout=60) as r:
+            while block := r.read(1 << 20):
+                out.write(block)
+        got = sha256(Path(tmp))
+        if got != entry.sha256:
+            raise ValueError(f"SHA-256 mismatch (expected {entry.sha256[:12]}…, got {got[:12]}…)")
+        os.replace(tmp, dest)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def download(
+    kinds: Iterable[str] | None = None,
+    *,
+    assets_dir: Path | str | None = None,
+    base_url: str | None = None,
+    quiet: bool = False,
+) -> DownloadReport:
+    """Download and verify assets.
+
+    Args:
+        kinds: ``"model"``, ``"atlas"``, ``"example"``; ``None`` downloads all.
+        assets_dir: Target assets root (default :func:`default_target`).
+        base_url: Mirror URL (default ``$ADS_ASSETS_URL`` or :data:`DEFAULT_URL`).
+        quiet: Do not print the licence notice and progress.
+
+    Returns:
+        A :class:`DownloadReport`; check ``report.ok``.
+    """
+    root = Path(assets_dir).expanduser() if assets_dir is not None else default_target()
+    base = (base_url or os.environ.get(URL_ENV_VAR) or DEFAULT_URL).rstrip("/")
+    wanted = set(kinds) if kinds else None
+    entries = [e for e in load_manifest() if wanted is None or e.kind in wanted]
+    report = DownloadReport(root)
+    say = (lambda *a: None) if quiet else (lambda *a: print(*a, file=sys.stderr, flush=True))
+    say(NOTICE)
+    say(
+        f"\nDownloading {len(entries)} files ({sum(e.size for e in entries) / 1e6:.0f} MB)"
+        f" from {base}\ninto {root}"
+    )
+    for k, e in enumerate(entries, 1):
+        dest = root / e.path
+        if dest.is_file() and dest.stat().st_size == e.size and sha256(dest) == e.sha256:
+            report.present.append(e.path)
+            continue
+        url = f"{base}/{urllib.parse.quote(e.path)}"
+        say(f"[{k}/{len(entries)}] {e.path} ({e.size / 1e6:.1f} MB)")
+        try:
+            _fetch(url, dest, e)
+            report.downloaded.append(e.path)
+        except urllib.error.HTTPError as err:
+            if err.code == 404:
+                report.missing.append(e.path)
+            else:
+                report.failed.append((e.path, f"HTTP {err.code}"))
+        except (OSError, ValueError) as err:
+            report.failed.append((e.path, str(err)))
+    say(
+        f"\n{len(report.downloaded)} downloaded, {len(report.present)} already present, "
+        f"{len(report.missing)} not on the mirror, {len(report.failed)} failed"
+    )
+    for p in report.missing:
+        say(f"  not on the mirror: {p}")
+    for p, why in report.failed:
+        say(f"  failed: {p}: {why}")
+    return report