mspdetect 0.1.0__py3-none-any.whl

mspdetect/__init__.py

@@ -0,0 +1,51 @@
+"""mspdetect: automatic mid-sagittal plane detection in head and neck planning CTs.
+
+Typical use::
+
+    import mspdetect as msp
+
+    case = msp.load_case("data/patient01", structures={"GTVp": "GTVp", "Body": "External"})
+    result = msp.detect_msp(case)
+    metrics = msp.compute_metrics(case, result.plane, structures=["Parotid_L"])
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mspdetect")
+except PackageNotFoundError:  # not installed
+    __version__ = "unknown"
+
+from mspdetect.config import (
+    BatchConfig,
+    CropConfig,
+    DataConfig,
+    DetectionConfig,
+    MetricsConfig,
+    OptimizerConfig,
+)
+from mspdetect.detect import MSPResult, detect_msp
+from mspdetect.io import Case, load_case
+from mspdetect.metrics import compute_metrics, side_volumes, target_metrics
+from mspdetect.plane import Plane
+from mspdetect.results import load_result, save_result
+
+__all__ = [
+    "BatchConfig",
+    "Case",
+    "CropConfig",
+    "DataConfig",
+    "DetectionConfig",
+    "MSPResult",
+    "MetricsConfig",
+    "OptimizerConfig",
+    "Plane",
+    "__version__",
+    "compute_metrics",
+    "detect_msp",
+    "load_case",
+    "load_result",
+    "save_result",
+    "side_volumes",
+    "target_metrics",
+]

mspdetect/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

mspdetect/batch.py

@@ -0,0 +1,284 @@
+"""Processing many cases, as used by the command line interface.
+
+Every case is processed independently; a failing case is recorded in a failures
+table and does not stop the run. Results are written to ``<output>/<case>/``.
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+import multiprocessing
+from collections.abc import Callable, Iterable
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+from tqdm import tqdm
+from tqdm.contrib.logging import logging_redirect_tqdm
+
+from mspdetect import __version__
+from mspdetect.config import BatchConfig
+from mspdetect.detect import detect_msp
+from mspdetect.io import load_case
+from mspdetect.metrics import compute_metrics
+from mspdetect.results import (
+    MANUAL_FILE,
+    SUMMARY_FILE,
+    load_manual_plane,
+    load_result,
+    read_summary,
+    save_result,
+)
+
+logger = logging.getLogger(__name__)
+
+RESULTS_TABLE = "msp_results.csv"
+FAILURES_TABLE = "failures.csv"
+METRICS_TABLE = "metrics.csv"
+METRICS_FAILURES_TABLE = "metrics_failures.csv"
+
+# Structures used by the detection itself (besides the crop reference)
+DETECTION_STRUCTURES = ("Body", "Mandible")
+
+
+def list_cases(config: BatchConfig) -> list[str]:
+    """Case names (paths relative to ``data.root``) to process."""
+    root, patients = config.data.root, config.data.patients
+    if not root.is_dir():
+        raise FileNotFoundError(f"data.root is not a directory: {root}")
+    if patients is None:
+        return sorted(p.name for p in root.iterdir() if p.is_dir() and not p.name.startswith("."))
+    if isinstance(patients, Path):
+        lines = patients.read_text().splitlines()
+        return [line.strip() for line in lines if line.strip() and not line.startswith("#")]
+    return list(patients)
+
+
+def _structure_files(config: BatchConfig, names: Iterable[str]) -> dict:
+    return {n: config.data.structures[n] for n in names if n in config.data.structures}
+
+
+def _detection_structures(config: BatchConfig) -> dict:
+    names = [*DETECTION_STRUCTURES]
+    if config.detection.crop.reference is not None:
+        names.append(config.detection.crop.reference)
+        if config.detection.crop.reference not in config.data.structures:
+            raise ValueError(
+                f"Crop reference '{config.detection.crop.reference}' is not in data.structures",
+            )
+    return _structure_files(config, names)
+
+
+def _detect_one(case_name: str, config: BatchConfig) -> dict:
+    """Detect and save the plane of one case; returns a status row."""
+    out_dir = config.output / case_name
+    fingerprint = config.detection.fingerprint()
+    if (out_dir / SUMMARY_FILE).exists() and not config.overwrite:
+        existing = read_summary(out_dir)
+        if existing.get("config_fingerprint") != fingerprint:
+            raise RuntimeError(
+                "existing result was computed with different detection settings; "
+                "use another output directory or set overwrite: true",
+            )
+        if existing.get("version") != __version__:
+            logger.warning(
+                "%s: existing result from mspdetect %s (now %s) is kept",
+                case_name,
+                existing.get("version"),
+                __version__,
+            )
+        return {"case_id": case_name, "status": "existing"}
+
+    case = load_case(
+        config.data.root / case_name,
+        image=config.data.image,
+        structures=_detection_structures(config),
+        case_id=case_name,
+    )
+    save_result(detect_msp(case, config.detection), out_dir)
+    return {"case_id": case_name, "status": "done"}
+
+
+def _metrics_starts(result, which: str) -> list[int]:
+    """Indices of the starts whose planes are evaluated for ``metrics.plane``."""
+    if which == "first_start":
+        return [0]
+    if which == "best":
+        return [result.best_start]
+    return list(range(len(result.starts)))
+
+
+def _metrics_one(case_name: str, config: BatchConfig) -> list[dict]:
+    """Compute the metrics of one case from its saved plane(s); one row per plane.
+
+    A manual correction (``manual.json``) replaces the detected plane(s).
+    """
+    result = load_result(config.output / case_name)
+    manual = load_manual_plane(config.output / case_name)
+    names = [*config.metrics.structures]
+    if config.metrics.target is not None:
+        names.append(config.metrics.target)
+    case = load_case(
+        config.data.root / case_name,
+        image=config.data.image,
+        structures=_structure_files(config, names),
+        case_id=case_name,
+    )
+    slices = result.crop_slices if config.metrics.volume_region == "slab" else None
+    if manual is not None:
+        planes = [("manual", manual.plane)]
+    else:
+        planes = [
+            (i, result.starts[i].final) for i in _metrics_starts(result, config.metrics.plane)
+        ]
+    rows = []
+    for start, plane in planes:
+        row = compute_metrics(
+            case,
+            plane,
+            config.metrics.structures,
+            config.metrics.target,
+            slices,
+        )
+        rows.append(
+            {
+                "case_id": row.pop("case_id"),
+                "plane_source": "detected" if manual is None else "manual",
+                "plane": config.metrics.plane,
+                "start": start,
+                "is_first_start": start == 0,
+                "is_best": start == result.best_start,
+                "volume_region": config.metrics.volume_region,
+                **row,
+            },
+        )
+    return rows
+
+
+def _safe(
+    func: Callable, case_name: str, config: BatchConfig
+) -> tuple[str, dict | list[dict] | None, str | None]:
+    try:
+        return case_name, func(case_name, config), None
+    except Exception as e:  # noqa: BLE001 - record any failure and continue with other cases
+        logger.exception("%s failed", case_name)
+        return case_name, None, f"{type(e).__name__}: {e}"
+
+
+def _run_all(func: Callable, cases: list[str], config: BatchConfig, description: str):
+    """``(case, row, error)`` for every case, in the order of ``cases``.
+
+    Cases run in parallel if ``n_jobs > 1``; a progress bar counts finished cases.
+    """
+    outcomes = {}
+    with logging_redirect_tqdm(), tqdm(total=len(cases), desc=description, unit="case") as bar:
+        if config.n_jobs == 1:
+            finished = (_safe(func, c, config) for c in cases)
+            pool = None
+        else:
+            # "spawn": forking a process with running threads (e.g. tqdm's) can deadlock
+            pool = ProcessPoolExecutor(
+                max_workers=config.n_jobs, mp_context=multiprocessing.get_context("spawn")
+            )
+            futures = [pool.submit(_safe, func, c, config) for c in cases]
+            finished = (f.result() for f in as_completed(futures))
+        try:
+            for case_name, row, error in finished:
+                outcomes[case_name] = (case_name, row, error)
+                bar.update()
+        finally:
+            if pool is not None:
+                pool.shutdown(cancel_futures=True)
+    return [outcomes[c] for c in cases]
+
+
+def write_table(path: Path, rows: list[dict], columns: Iterable[str] = ()) -> None:
+    """Write rows (dicts) as CSV; columns are ``columns`` followed by any other keys."""
+    columns = list(dict.fromkeys([*columns, *(k for row in rows for k in row)]))
+    with path.open("w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=columns)
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def _summary_row(case_name: str, summary: dict, config_output: Path) -> dict:
+    plane = summary["plane"]
+    return {
+        "case_id": case_name,
+        "normal_x": plane["normal"][0],
+        "normal_y": plane["normal"][1],
+        "normal_z": plane["normal"][2],
+        "offset_mm": plane["offset_mm"],
+        "azimuth_deg": plane["azimuth_deg"],
+        "polar_deg": plane["polar_deg"],
+        "objective": summary["objective"],
+        "quadratic": summary["quadratic"],
+        "converged": summary["converged"],
+        "n_starts": len(summary["starts"]),
+        "best_start": summary["best_start"],
+        "first_start_agrees": summary["first_start_agrees"] if len(summary["starts"]) > 1 else "",
+        "first_start_angle_deg": summary["first_start_angle_deg"]
+        if len(summary["starts"]) > 1
+        else "",
+        "first_start_distance_mm": summary["first_start_distance_mm"]
+        if len(summary["starts"]) > 1
+        else "",
+        "runtime_s": summary["runtime_s"],
+        "version": summary["version"],
+        "manual_correction": (config_output / case_name / MANUAL_FILE).exists(),
+    }
+
+
+def run_detection(config: BatchConfig) -> tuple[int, int]:
+    """Detect the plane of all cases; returns ``(n_succeeded, n_failed)``.
+
+    Writes ``msp_results.csv`` (all cases with a result) and ``failures.csv``.
+    """
+    cases = list_cases(config)
+    _detection_structures(config)  # fail early on configuration errors
+    config.output.mkdir(parents=True, exist_ok=True)
+    logger.info("Detecting the MSP of %d case(s) with %d job(s)", len(cases), config.n_jobs)
+
+    rows, failures = [], []
+    for case_name, _, error in _run_all(_detect_one, cases, config, "Detecting MSP"):
+        if error:
+            failures.append({"case_id": case_name, "error": error})
+        else:
+            rows.append(
+                _summary_row(case_name, read_summary(config.output / case_name), config.output)
+            )
+
+    write_table(config.output / RESULTS_TABLE, rows)
+    write_table(config.output / FAILURES_TABLE, failures, columns=("case_id", "error"))
+    logger.info(
+        "Done: %d succeeded, %d failed (see %s)",
+        len(rows),
+        len(failures),
+        FAILURES_TABLE,
+    )
+    return len(rows), len(failures)
+
+
+def run_metrics(config: BatchConfig) -> tuple[int, int]:
+    """Compute metrics for all cases with a detected plane.
+
+    Planes are read from ``output``; ``metrics.csv`` and ``metrics_failures.csv`` are
+    written to ``metrics.output`` (default: ``output``).
+    """
+    cases = [c for c in list_cases(config) if (config.output / c / SUMMARY_FILE).exists()]
+    out_dir = config.metrics_output
+    out_dir.mkdir(parents=True, exist_ok=True)
+    logger.info("Computing metrics of %d case(s), writing to %s", len(cases), out_dir)
+
+    rows, failures = [], []
+    for case_name, case_rows, error in _run_all(_metrics_one, cases, config, "Computing metrics"):
+        if error:
+            failures.append({"case_id": case_name, "error": error})
+        else:
+            rows.extend(case_rows)
+
+    write_table(out_dir / METRICS_TABLE, rows)
+    write_table(out_dir / METRICS_FAILURES_TABLE, failures, columns=("case_id", "error"))
+    n_done = len(cases) - len(failures)
+    logger.info("Done: %d succeeded, %d failed", n_done, len(failures))
+    return n_done, len(failures)

mspdetect/cli.py

@@ -0,0 +1,58 @@
+"""Command line interface: ``mspdetect {check-config,run,metrics} config.yaml``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+import yaml
+from pydantic import ValidationError
+
+from mspdetect import __version__
+from mspdetect.batch import run_detection, run_metrics
+from mspdetect.config import BatchConfig
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mspdetect",
+        description="Mid-sagittal plane detection in head and neck CTs.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("-v", "--verbose", action="store_true", help="show debug messages")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, help_text in [
+        ("check-config", "validate a configuration file and print the full settings"),
+        ("run", "detect the plane of all cases"),
+        ("metrics", "compute metrics for all cases with a detected plane"),
+    ]:
+        command = commands.add_parser(name, help=help_text)
+        command.add_argument("config", help="YAML configuration file")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point of the ``mspdetect`` command."""
+    args = _parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    try:
+        config = BatchConfig.from_yaml(args.config)
+    except (OSError, ValidationError, yaml.YAMLError) as e:
+        print(f"Invalid configuration {args.config}:\n{e}", file=sys.stderr)  # noqa: T201
+        return 2
+
+    if args.command == "check-config":
+        print(yaml.safe_dump(config.model_dump(mode="json"), sort_keys=False))  # noqa: T201
+        return 0
+    run = run_detection if args.command == "run" else run_metrics
+    _, n_failed = run(config)
+    return 1 if n_failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mspdetect/config.py

@@ -0,0 +1,256 @@
+"""Configuration of MSP detection, metrics and batch processing.
+
+All configurations are validated with `pydantic`_: unknown keys, wrong types and
+inconsistent values raise an error instead of being silently ignored.
+
+.. _pydantic: https://docs.pydantic.dev/latest/
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    NonNegativeInt,
+    PositiveInt,
+    field_validator,
+    model_validator,
+)
+
+
+class _Config(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class CropConfig(_Config):
+    """Which part of the CT is used to fit the plane.
+
+    Slices are counted along the patient's inferior→superior axis. Structures named
+    ``Mandible`` and ``Body`` have a special meaning (see ``include_mandible`` and
+    ``lateral_extent_mm``; ``Body`` is also used to mask out the couch).
+    """
+
+    reference: str | None = Field(
+        default="GTVp",
+        description=(
+            "Structure around which the slab of slices is cropped. "
+            "None uses the whole scan (or `slice_range`)."
+        ),
+    )
+    slice_range: tuple[NonNegativeInt, NonNegativeInt] | None = Field(
+        default=None,
+        description="Explicit [start, stop) slice range; overrides `reference`.",
+    )
+    mode: Literal["margins", "fixed_size"] = Field(
+        default="margins",
+        description=(
+            "`margins`: extent of the reference plus `margins` slices. "
+            "`fixed_size`: 2*`fixed_size` + 1 slices centred on the reference "
+            "(or the reference extent if it is larger)."
+        ),
+    )
+    margins: NonNegativeInt | tuple[NonNegativeInt, NonNegativeInt] = Field(
+        default=10,
+        description="Slices added below/above the reference: one value or [inferior, superior].",
+    )
+    fixed_size: PositiveInt = Field(
+        default=20,
+        description="Half-size (slices) of the window used in `fixed_size` mode.",
+    )
+    include_mandible: bool = Field(
+        default=True,
+        description=(
+            "If the reference ends below or within 5 slices of the lower edge of the "
+            "Mandible, extend the slab to include those mandible slices."
+        ),
+    )
+    lateral_extent_mm: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "If set, keep only this width (mm, left-right) centred on the Body "
+            "(or image centre) to exclude the shoulders."
+        ),
+    )
+    pad: NonNegativeInt = Field(
+        default=10,
+        description="Extra voxels around each crop used only for interpolating mirrored points.",
+    )
+
+    @model_validator(mode="after")
+    def _check_slice_range(self):
+        if self.slice_range is not None and self.slice_range[0] >= self.slice_range[1]:
+            raise ValueError(
+                f"slice_range must be [start, stop) with start < stop, got {self.slice_range}"
+            )
+        return self
+
+
+class OptimizerConfig(_Config):
+    """Grid search initialisation and optimisation of the plane."""
+
+    azimuth_deg: tuple[float, float] = Field(
+        default=(0.0, 30.0),
+        description="Grid search over the azimuthal angle: [centre, half-width] in degrees.",
+    )
+    polar_deg: tuple[float, float] = Field(
+        default=(90.0, 40.0),
+        description="Grid search over the polar angle: [centre, half-width] in degrees.",
+    )
+    grid_steps: PositiveInt = Field(
+        default=10,
+        description="Number of angles per axis; the grid has grid_steps**2 planes.",
+    )
+    n_starts: PositiveInt = Field(
+        default=1,
+        description=(
+            "Number of optimisations, started from the best grid points. 1 uses only "
+            "the grid point with the lowest initial value; >1 returns the start with "
+            "the lowest final quadratic loss and reports whether the first start agrees with it."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _check_n_starts(self):
+        if self.n_starts > self.grid_steps**2:
+            raise ValueError(
+                f"n_starts ({self.n_starts}) cannot exceed the number of grid points "
+                f"({self.grid_steps**2})",
+            )
+        if self.azimuth_deg[1] < 0 or self.polar_deg[1] < 0:
+            raise ValueError("Half-widths of the angle ranges must be >= 0")
+        return self
+
+
+class DetectionConfig(_Config):
+    """Everything that determines the detected plane of one case."""
+
+    hu_range: tuple[float, float] = Field(
+        default=(300.0, 2800.0),
+        description="Voxels with HU in [low, high] are considered bone.",
+    )
+    crop: CropConfig = CropConfig()
+    optimizer: OptimizerConfig = OptimizerConfig()
+
+    @model_validator(mode="after")
+    def _check_hu_range(self):
+        if self.hu_range[0] >= self.hu_range[1]:
+            raise ValueError(f"hu_range must be [low, high] with low < high, got {self.hu_range}")
+        return self
+
+    def fingerprint(self) -> str:
+        """Short hash identifying these settings (used to detect stale results)."""
+        dump = json.dumps(self.model_dump(mode="json"), sort_keys=True)
+        return hashlib.sha256(dump.encode()).hexdigest()[:16]
+
+
+class DataConfig(_Config):
+    """Where the cases are and how their files are named."""
+
+    root: Path = Field(description="Directory containing one sub-directory per case.")
+    patients: list[str] | Path | None = Field(
+        default=None,
+        description=(
+            "Cases to process: a list of sub-directory names (may contain '/'), a "
+            "text file with one name per line, or None for all sub-directories."
+        ),
+    )
+    image: str | list[str] = Field(
+        default="CT",
+        description="File name(s) of the CT without extension (case-insensitive).",
+    )
+    structures: dict[str, str | list[str]] = Field(
+        default_factory=dict,
+        description="File name(s) of structures without extension (case-insensitive).",
+    )
+
+    @field_validator("patients", mode="before")
+    @classmethod
+    def _ids_as_strings(cls, value):
+        # YAML reads numeric patient IDs as integers
+        if isinstance(value, list):
+            return [str(v) for v in value]
+        return value
+
+
+class MetricsConfig(_Config):
+    """Which metrics to compute relative to the detected plane."""
+
+    output: Path | None = Field(
+        default=None,
+        description=(
+            "Directory for metrics.csv and metrics_failures.csv; None uses the "
+            "top-level `output`. The detected planes are always read from `output`."
+        ),
+    )
+    structures: list[str] = Field(
+        default_factory=list,
+        description="Structures for which left/right volumes are computed.",
+    )
+    target: str | None = Field(
+        default="GTVp",
+        description="Structure for which laterality and distances to the plane are computed.",
+    )
+    plane: Literal["first_start", "best", "all_starts"] = Field(
+        default="first_start",
+        description=(
+            "Plane(s) used for the metrics: `first_start` = result of the optimisation "
+            "started from the grid point with the lowest initial value; `best` = lowest "
+            "final quadratic loss over all starts; `all_starts` = one row per start. "
+            "Identical if n_starts is 1."
+        ),
+    )
+    volume_region: Literal["whole", "slab"] = Field(
+        default="whole",
+        description=(
+            "Region for left/right volumes: `whole` = the whole structures; `slab` = "
+            "only the slices used to detect the plane (full left-right and "
+            "anterior-posterior extent)."
+        ),
+    )
+
+
+class BatchConfig(_Config):
+    """Configuration file of the command line interface."""
+
+    data: DataConfig
+    output: Path = Field(description="Directory where results are written.")
+    detection: DetectionConfig = DetectionConfig()
+    metrics: MetricsConfig = MetricsConfig()
+    n_jobs: PositiveInt = Field(default=1, description="Number of cases processed in parallel.")
+    overwrite: bool = Field(default=False, description="Recompute cases that already have results.")
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> BatchConfig:
+        """Load a YAML file; relative paths are resolved relative to the file."""
+        path = Path(path)
+        with path.open() as f:
+            raw = yaml.safe_load(f) or {}
+        base = path.resolve().parent
+
+        def resolve(value):
+            return str(base / value) if isinstance(value, str) else value
+
+        data = raw.get("data")
+        if isinstance(data, dict):
+            data["root"] = resolve(data.get("root"))
+            if isinstance(data.get("patients"), str):
+                data["patients"] = resolve(data["patients"])
+        if "output" in raw:
+            raw["output"] = resolve(raw["output"])
+        metrics = raw.get("metrics")
+        if isinstance(metrics, dict) and metrics.get("output") is not None:
+            metrics["output"] = resolve(metrics["output"])
+        return cls.model_validate(raw)
+
+    @property
+    def metrics_output(self) -> Path:
+        """Directory for the metrics tables: ``metrics.output`` or ``output``."""
+        return self.metrics.output or self.output