itasc 0.2.0.dev0__py3-none-any.whl

itasc/contact_analysis/pipeline.py

@@ -0,0 +1,313 @@
+"""The napari-free orchestration surface for Contact Analysis.
+
+Three composable functions thread the existing headless stages — discovery,
+per-position build, aggregate — into one pipeline the CLI, notebooks, and (during
+the napari parallel-run) the Qt studio all drive:
+
+    catalog = build_catalog(root, cell_name=..., nucleus_name=..., out_csv=...)
+    build_quantities(catalog)                 # one .build() per (quantifier, position)
+    tables = aggregate(catalog, out_dir)      # pooled, index-keyed CSVs (flat)
+
+Or, end to end from a TOML run-config: ``run("config.toml")``.
+
+Everything produced is **label-agnostic** tidy CSVs: there is no classification
+step and no plot/figure export — a subpopulation classification and any plots are a
+downstream, dataset-specific concern, computed from these tables.
+
+This module *composes* — it owns no compute. Discovery lives in :mod:`.catalog`,
+the per-position units in :mod:`.quantifier`, the record→inputs bridge in
+:mod:`.records`, and pooling in :mod:`.shape_tables`. The only orchestration that
+previously lived nowhere but the napari studio — the per-position **build loop** —
+is :func:`build_quantities`.
+
+Backend-only (no Qt / napari): the standalone wheel and headless batch runs use
+it unchanged.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from pathlib import Path
+
+from . import shape_tables
+from .catalog import discover_catalog_entries, load_catalog, save_catalog
+from .config import RunConfig, load_config, write_config
+from .quantifier import Quantifier, available_quantifiers
+from .records import (
+    available_fields,
+    output_for_record,
+    position_inputs_from_record,
+    record_build_params,
+)
+
+__all__ = [
+    "author_config",
+    "build_catalog",
+    "build_quantities",
+    "select_quantifiers",
+    "aggregate",
+    "run",
+]
+
+
+def build_catalog(
+    root: Path | str,
+    *,
+    cell_name: str | None = None,
+    nucleus_name: str | None = None,
+    out_csv: Path | str | None = None,
+) -> list[dict]:
+    """Discover the positions under *root* and return them as catalogue records.
+
+    Wraps :func:`~itasc.contact_analysis.catalog.discover_catalog_entries`:
+    a *position* is any folder holding at least one named input (cell and/or
+    nucleus labels). When *out_csv* is given, the discovered skeleton is written
+    there (:func:`~itasc.contact_analysis.catalog.save_catalog`) for an
+    analyst to fill in ``condition`` / ``date`` / ``notes`` before building.
+
+    The records carry the discovered paths but no metadata; that is fine for an
+    immediate build (which keys only on the inputs) and is the editable skeleton
+    when persisted.
+    """
+    entries = discover_catalog_entries(
+        root, cell_name=cell_name, nucleus_name=nucleus_name
+    )
+    if out_csv is not None:
+        save_catalog(out_csv, entries)
+    return entries
+
+
+def build_quantities(
+    catalog: Iterable[dict],
+    *,
+    quantifiers: Sequence[Quantifier] | None = None,
+    params: Mapping[str, object] | None = None,
+    progress_cb: Callable[[int, int, str], None] | None = None,
+) -> None:
+    """Build and persist every **producer** quantity for every position in *catalog*.
+
+    THE extracted build loop (previously trapped in the napari studio): one job
+    per ``(quantifier, position)`` where the quantifier
+    :meth:`~itasc.contact_analysis.quantifier.Quantifier.can_build` the
+    position's inputs; each job calls ``.build(inputs, output_path, params=...)``,
+    overwriting an existing artifact. Positions lacking a quantifier's inputs are
+    skipped.
+
+    Only **producers** — quantifiers whose ``produces`` another quantifier's
+    ``requires`` names (in practice just ``contacts``, writing
+    ``contact_analysis.h5``) — persist a per-position artifact here. Every other
+    (cheap) quantity is never built to disk per-position: it is instead computed
+    in memory, straight from a position's raw inputs, inside
+    :func:`~itasc.contact_analysis.shape_tables.aggregate` /
+    :func:`~itasc.contact_analysis.shape_tables.build_table` via
+    :meth:`~itasc.contact_analysis.quantifier.Quantifier.compute_object_table`.
+    A normal run therefore writes only ``contact_analysis.h5`` per position; the
+    pooled tables are the only place the cheap quantities live.
+
+    *quantifiers* defaults to one instance of every registered quantifier
+    (:func:`~itasc.contact_analysis.quantifier.available_quantifiers`); it is
+    filtered down to producers before planning, so passing non-producers here is
+    harmless (they are simply skipped).
+    *params* (the shared build knobs — z-score shuffles, density FOV, pixel size,
+    frame interval) is threaded only into quantifiers that opt in via
+    ``wants_build_params``; the rest keep their own ``params`` schema clean. A
+    quantifier whose ``required_build_params`` *params* does not satisfy is skipped
+    whole (mirrors the studio greying the metric out), so "build everything" stays
+    usable when an optional knob like the density FOV is unset.
+    *progress_cb* is called ``(done, total, position_name)`` before each build.
+    Exceptions propagate — a failed build aborts the run rather than being
+    silently swallowed.
+    """
+    quants = (
+        list(quantifiers)
+        if quantifiers is not None
+        else [cls() for cls in available_quantifiers()]
+    )
+    quants = _dependency_order(quants)
+    quants = [q for q in quants if q.produces]  # only producers persist (contacts)
+    records = list(catalog)
+    jobs: list[tuple[Quantifier, dict, dict | None]] = []
+    for quantifier in quants:
+        q_params = dict(params) if (params and quantifier.wants_build_params) else None
+        for record in records:
+            inputs = position_inputs_from_record(record)
+            if not set(quantifier.requires) <= available_fields(inputs):
+                continue
+            if quantifier.missing_build_params(record_build_params(quantifier, record, params)):
+                continue
+            jobs.append((quantifier, record, q_params))
+
+    total = len(jobs)
+    for index, (quantifier, record, q_params) in enumerate(jobs, start=1):
+        # Re-derive now: a producer built earlier this run has written its
+        # artifact, so the dependent's inputs resolve it (``position_inputs_from_record``
+        # gates a produced input on the file existing).
+        inputs = position_inputs_from_record(record)
+        if progress_cb is not None:
+            progress_cb(index, total, inputs.position_dir.name)
+        quantifier.build(inputs, output_for_record(quantifier, record), params=q_params)
+
+
+def _dependency_order(quants: Sequence[Quantifier]) -> list[Quantifier]:
+    """*quants* sorted so each producer precedes the quantifiers whose ``requires``
+    names its ``produces``. Independent quantifiers keep their given order; a
+    dependency cycle raises ``ValueError``."""
+    produced_by = {q.produces: q for q in quants if q.produces}
+    order: list[Quantifier] = []
+    state: dict[int, str] = {}  # id(q) -> "visiting" | "done"
+
+    def visit(q: Quantifier) -> None:
+        mark = state.get(id(q))
+        if mark == "done":
+            return
+        if mark == "visiting":
+            name = q.quantity_id or type(q).__name__
+            raise ValueError(f"Quantifier dependency cycle involving {name!r}")
+        state[id(q)] = "visiting"
+        for field in q.requires:
+            producer = produced_by.get(field)
+            if producer is not None and producer is not q:
+                visit(producer)
+        state[id(q)] = "done"
+        order.append(q)
+
+    for q in quants:
+        visit(q)
+    return order
+
+
+def select_quantifiers(quantities: Sequence[str]) -> list[Quantifier]:
+    """Instantiate the quantifiers a run should build for the selected *quantities*.
+
+    Empty *quantities* selects **every** registered quantifier. A non-empty list
+    selects those ``quantity_id``\\ s plus, transitively, any **producer** whose
+    ``produces`` field a selected (or pulled-in) quantifier ``requires`` — so asking
+    for a contacts-derived metric silently brings contacts along instead of leaving
+    it unbuildable. Order follows registration; the build loop re-sorts by
+    dependency.
+    """
+    classes = list(available_quantifiers())
+    if not quantities:
+        return [cls() for cls in classes]
+
+    by_id = {cls.quantity_id: cls for cls in classes}
+    unknown = [q for q in quantities if q not in by_id]
+    if unknown:
+        raise ValueError(f"unknown quantit(y/ies) {unknown}; known: {sorted(by_id)}")
+    produced_by = {cls.produces: cls for cls in classes if cls.produces}
+
+    selected: dict[str, type[Quantifier]] = {}
+
+    def add(cls: type[Quantifier]) -> None:
+        if cls.quantity_id in selected:
+            return
+        selected[cls.quantity_id] = cls
+        for field in cls.requires:
+            producer = produced_by.get(field)
+            if producer is not None and producer is not cls:
+                add(producer)
+
+    for qid in quantities:
+        add(by_id[qid])
+    # Preserve registration order for a stable, readable build sequence.
+    return [cls() for cls in classes if cls.quantity_id in selected]
+
+
+def aggregate(
+    catalog: Sequence[dict],
+    out_dir: Path | str | None = None,
+    *,
+    params: Mapping[str, object] | None = None,
+    quantities: Sequence[str] | None = None,
+) -> dict[str, Path]:
+    """Pool every built product across *catalog* into the index-keyed tables.
+
+    Thin pass-through to
+    :func:`itasc.contact_analysis.shape_tables.aggregate`: returns the
+    table name → written CSV path map. The tables are written **flat** under
+    *out_dir* (``<out_dir>/<name>.csv``); *out_dir* defaults to the catalogue root
+    (the common ancestor of the positions). *params* carries the shared build
+    knobs (pixel size, frame interval, FOV area, …) so a param-gated cheap
+    quantity (e.g. cell shape needing ``pixel_size_um``) pools with the same
+    knobs a normal build would have used. *quantities* restricts which tables are
+    written (``None`` = all); see :func:`shape_tables.aggregate`.
+    """
+    return shape_tables.aggregate(catalog, out_dir, params=params, quantities=quantities)
+
+
+def author_config(
+    out_dir: Path | str,
+    records: Sequence[dict],
+    *,
+    tables_dir: str | None = None,
+    quantities: Sequence[str] = (),
+    params: Mapping[str, object] | None = None,
+    catalog_name: str = "catalog.csv",
+    config_name: str = "config.toml",
+) -> Path:
+    """Write ``catalog.csv`` + ``config.toml`` into *out_dir*; return the config path.
+
+    The composition point behind the studio's "Save config…" / "Run": persist the
+    in-memory *records* to a catalog CSV, then author a run-config beside it that
+    points at that CSV (a relative ``catalog`` key, so the folder stays
+    relocatable). *tables_dir* is written as the config's ``out_dir`` (where the
+    flat pooled tables land); ``None`` leaves it unset (defaults to the catalogue
+    root at run time). ``run(author_config(...))`` reproduces the UI's run
+    headlessly. Creates *out_dir* if missing.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    save_catalog(out_dir / catalog_name, records)
+    return write_config(
+        out_dir / config_name,
+        catalog=catalog_name,
+        out_dir=tables_dir,
+        quantities=quantities,
+        params=params,
+    )
+
+
+def run(
+    config_path: Path | str, *, progress_cb=None, build: bool = True
+) -> dict[str, Path]:
+    """Run the whole pipeline from a TOML run-config: the "author once, then run".
+
+    Loads the :class:`~itasc.contact_analysis.config.RunConfig`, then
+    threads its choices through the stages: load the catalog CSV, build the
+    selected *quantities* — of which only producers (``contacts``) actually
+    persist a per-position artifact, see :func:`build_quantities` — and aggregate
+    into the flat measurement tables under the config's ``out_dir`` (default: the
+    catalogue root), where the cheap quantities are computed in memory. The same
+    ``quantities`` selection restricts which tables ``aggregate`` writes (empty =
+    all), so a pool-only run honors the choice too. Returns
+    the table name → written CSV path map. The optional *progress_cb* is
+    forwarded to the build stage.
+
+    Set *build* to ``False`` for **pool-only**: skip the per-position build stage
+    entirely and go straight to aggregate. The producer's ``.build`` overwrites its
+    ``.h5`` unconditionally (it is not guarded like ``ensure_contacts``), so a plain
+    ``run`` recomputes every position's contacts even when the artifact already
+    exists. ``build=False`` reads the existing ``.h5`` via each quantifier's
+    ``compute_object_table`` and computes the cheap quantities in memory — a
+    load-and-pool with no recompute. Positions missing their ``.h5`` simply
+    contribute nothing (scope them out before calling).
+    """
+    cfg: RunConfig = load_config(config_path)
+    catalog = load_catalog(cfg.catalog)
+    # The global build knobs (``pixel_size_um`` / ``time_interval_s``) are read off
+    # each record by ``position_inputs_from_record``; in the studio they are stamped
+    # per-position, here they come from the config. Stamp config params onto every
+    # record that does not already carry them, then also pass them to the build loop
+    # (the required-param gate + opt-in ``wants_build_params`` quantifiers).
+    for record in catalog:
+        for key, value in cfg.params.items():
+            record.setdefault(key, value)
+    if build:
+        build_quantities(
+            catalog,
+            quantifiers=select_quantifiers(cfg.quantities),
+            params=cfg.params or None,
+            progress_cb=progress_cb,
+        )
+    return aggregate(
+        catalog, cfg.out_dir, params=cfg.params or None, quantities=cfg.quantities or None
+    )

itasc/contact_analysis/pixel_size.py

@@ -0,0 +1,166 @@
+"""Resolve a position's physical pixel size (µm per pixel).
+
+Backend-only (no Qt / napari) so the standalone wheel and headless batch runs can
+use it. The cell-shape build needs µm/px to turn pixel-unit ``regionprops``
+measurements into physical µm / µm². Two sources are consulted, in order:
+
+1. The position's ``itasc_config.json`` — ``metadata.pixel_size_um`` — the key
+   the main pipeline widget already writes (``main_widget.py``).
+2. The segmented label TIFF's resolution tags — ImageJ ``unit`` + ``resolution``
+   or the baseline ``XResolution`` / ``ResolutionUnit`` tags.
+
+Returns ``None`` when neither yields a positive value; callers treat that as
+"pixel size unknown" (the cell-shape build is then blocked until one is set).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import tifffile
+
+from itasc.core.paths import position_config_path
+
+__all__ = ["resolve_pixel_size_um", "pixel_size_from_config", "pixel_size_from_tiff"]
+
+#: Multipliers turning a length in the tag's unit into µm.
+_UNIT_TO_UM = {
+    "micron": 1.0,
+    "microns": 1.0,
+    "um": 1.0,
+    "µm": 1.0,
+    "micrometer": 1.0,
+    "micrometre": 1.0,
+    "mm": 1_000.0,
+    "millimeter": 1_000.0,
+    "cm": 10_000.0,
+    "centimeter": 10_000.0,
+    "inch": 25_400.0,
+    "in": 25_400.0,
+}
+#: Baseline-TIFF ``ResolutionUnit`` tag values (2 = inch, 3 = centimeter).
+_RESOLUTION_UNIT_TO_UM = {2: 25_400.0, 3: 10_000.0}
+
+
+def resolve_pixel_size_um(
+    position_dir: Path | str | None,
+    cell_labels_path: Path | str | None,
+) -> float | None:
+    """µm/px for a position, from its config first, then the label TIFF tags.
+
+    Returns ``None`` when no positive pixel size can be found.
+    """
+    size = pixel_size_from_config(position_dir)
+    if size is not None:
+        return size
+    return pixel_size_from_tiff(cell_labels_path)
+
+
+def pixel_size_from_config(position_dir: Path | str | None) -> float | None:
+    """``metadata.pixel_size_um`` from ``itasc_config.json`` in *position_dir*."""
+    if position_dir is None:
+        return None
+    config_path = position_config_path(position_dir)
+    if not config_path.is_file():
+        return None
+    try:
+        with open(config_path) as f:
+            config = json.load(f)
+        metadata = config.get("metadata", {})
+        return _positive_float(metadata.get("pixel_size_um"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+
+
+def pixel_size_from_tiff(cell_labels_path: Path | str | None) -> float | None:
+    """µm/px from a TIFF's resolution tags (ImageJ unit, else ResolutionUnit)."""
+    if cell_labels_path is None:
+        return None
+    path = Path(cell_labels_path)
+    if not path.is_file():
+        return None
+    try:
+        with tifffile.TiffFile(str(path)) as tf:
+            from_ome = _pixel_size_from_ome(tf)
+            if from_ome is not None:
+                return from_ome
+            from_imagej = _pixel_size_from_imagej(tf)
+            if from_imagej is not None:
+                return from_imagej
+            return _pixel_size_from_baseline(tf)
+    except (OSError, ValueError, KeyError, tifffile.TiffFileError):
+        # An unreadable/empty/corrupt TIFF means "pixel size unknown", not a
+        # crash. tifffile raises TiffFileError (not a KeyError/OSError subclass)
+        # for a malformed file, so it must be named explicitly.
+        return None
+
+
+def _pixel_size_from_ome(tf: tifffile.TiffFile) -> float | None:
+    """OME-TIFF stores µm/px directly as ``Pixels/@PhysicalSizeX`` (+ unit)."""
+    xml = tf.ome_metadata
+    if not xml:
+        return None
+    import xml.etree.ElementTree as ET
+
+    try:
+        root = ET.fromstring(xml)
+    except ET.ParseError:
+        return None
+    for el in root.iter():
+        if el.tag.endswith("Pixels"):
+            value = _positive_float(el.get("PhysicalSizeX"))
+            if value is None:
+                return None
+            unit = str(el.get("PhysicalSizeXUnit", "µm")).strip().lower()
+            to_um = _UNIT_TO_UM.get(unit)
+            return value * to_um if to_um is not None else None
+    return None
+
+
+def _pixel_size_from_imagej(tf: tifffile.TiffFile) -> float | None:
+    """ImageJ stores spacing as ``XResolution`` (pixels/unit) plus a ``unit``."""
+    metadata = tf.imagej_metadata or {}
+    unit = str(metadata.get("unit", "")).strip().lower()
+    to_um = _UNIT_TO_UM.get(unit)
+    if to_um is None:
+        return None
+    per_unit = _tag_ratio(tf, "XResolution")
+    if per_unit is None or per_unit <= 0:
+        return None
+    return to_um / per_unit
+
+
+def _pixel_size_from_baseline(tf: tifffile.TiffFile) -> float | None:
+    """Baseline TIFF: ``XResolution`` pixels/unit with a ``ResolutionUnit``."""
+    page = tf.pages[0]
+    unit_tag = page.tags.get("ResolutionUnit")
+    to_um = _RESOLUTION_UNIT_TO_UM.get(int(unit_tag.value)) if unit_tag else None
+    if to_um is None:
+        return None
+    per_unit = _tag_ratio(tf, "XResolution")
+    if per_unit is None or per_unit <= 0:
+        return None
+    return to_um / per_unit
+
+
+def _tag_ratio(tf: tifffile.TiffFile, name: str) -> float | None:
+    """Read a rational TIFF tag (``(num, den)`` or scalar) as a float."""
+    tag = tf.pages[0].tags.get(name)
+    if tag is None:
+        return None
+    value = tag.value
+    if isinstance(value, (tuple, list)) and len(value) == 2:
+        num, den = value
+        return float(num) / float(den) if den else None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _positive_float(value: object) -> float | None:
+    try:
+        result = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+    return result if result > 0 else None

itasc/contact_analysis/quantifier.py

@@ -0,0 +1,204 @@
+"""The quantifier seam: per-position compute units, discovered by subclassing.
+
+A :class:`Quantifier` turns a position's source files (:class:`PositionInputs`)
+into a persisted, plottable quantity. Contacts is the first one; new quantities
+(nucleus-track kinematics, nucleus-vs-cell offset, cell shape, …) drop in as
+modules under :mod:`itasc.contact_analysis.quantifiers` without
+touching the studio.
+
+The mechanics mirror :mod:`itasc.napari.contact_analysis.plugins`: subclassing with a
+non-empty ``quantity_id`` auto-registers the quantifier, and
+:func:`available_quantifiers` imports every module in the ``quantifiers`` package
+so its plugins self-register. This module stays backend-only (no Qt / napari) so
+the standalone wheel and headless batch runs can use it.
+"""
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+__all__ = ["OUTPUT_SUBDIR", "PositionInputs", "Quantifier", "available_quantifiers"]
+
+#: Per-position subfolder for quantifier artifacts that persist to disk. Numbered
+#: to mirror the staged layout (``0_input`` … ``3_cell``). The dynamics
+#: quantifiers land here (``cell_dynamics.h5``, ``nucleus_dynamics.h5``); the
+#: cheap quantities (shape, relational, density, neighbor count) are pooled in
+#: memory during ``run()`` rather than written to disk. Note ``contact_analysis.h5``
+#: is *not* here — :class:`~itasc.contact_analysis.quantifiers.contacts.ContactsQuantifier`
+#: overrides :meth:`Quantifier.default_output` to write it to the position root,
+#: beside the committed ``cell_labels.tif`` / ``nucleus_labels.tif``.
+OUTPUT_SUBDIR = "4_contact_analysis"
+
+
+@dataclass(frozen=True)
+class PositionInputs:
+    """Resolved source files for one position. Quantifiers read what they need.
+
+    Every field has a live consumer. A future track-based quantifier adds its own
+    field (e.g. ``tracks_db_path``) in the same commit that first reads it — no
+    speculative placeholders here.
+    """
+
+    position_dir: Path
+    cell_labels_path: Path | None = None
+    nucleus_labels_path: Path | None = None
+    #: Physical pixel size (µm/px); ``None`` when unknown. Quantifiers that emit
+    #: values in physical units (cell shape) require it.
+    pixel_size_um: float | None = None
+    #: Frame interval (seconds/frame); ``None`` when unknown. Quantifiers that
+    #: emit time-derived values (track dynamics) require it.
+    time_interval_s: float | None = None
+    #: The position's built ``contact_analysis.h5``; ``None`` when contacts is not
+    #: in the catalogue. The contacts-derived quantifiers (neighbor count /
+    #: enrichment / z-score / density / signed contact length) read it as their input instead
+    #: of re-running contact extraction.
+    contact_analysis_path: Path | None = None
+
+
+#: quantity_id -> quantifier class, populated by ``__init_subclass__``.
+_REGISTRY: dict[str, type[Quantifier]] = {}
+
+
+class Quantifier:
+    """Base class for per-position quantifiers.
+
+    Subclasses set ``quantity_id`` / ``display_name`` (and usually ``requires``)
+    and implement :meth:`build` and :meth:`read`. A quantifier **owns its own
+    persistence**: :meth:`build` writes whatever artifact format suits the
+    quantity and :meth:`read` parses it back — the framework imposes no schema.
+    """
+
+    #: Stable key; an empty value marks an intermediate (non-registered) base.
+    quantity_id: ClassVar[str] = ""
+    #: Human-readable label shown wherever a quantity is selected.
+    display_name: ClassVar[str] = ""
+    #: ``PositionInputs`` field names this quantifier needs to build.
+    requires: ClassVar[tuple[str, ...]] = ()
+    #: The ``PositionInputs`` field this quantifier's artifact *populates*, if any
+    #: (e.g. contacts populates ``contact_analysis_path``). A quantifier whose
+    #: :attr:`requires` names another's :attr:`produces` is *derived from* it — the
+    #: studio uses this to draw the build-dependency graph. Empty for a leaf
+    #: quantity that only consumes raw source inputs.
+    produces: ClassVar[str] = ""
+    #: Default artifact file name (relative to a position); empty for an
+    #: intermediate base that does not persist.
+    default_output_name: ClassVar[str] = ""
+    #: The index columns of this quantifier's ``object_table`` — its natural grain
+    #: (e.g. ``("frame", "cell_id")``). A non-empty value marks the quantity as
+    #: **aggregated**: :mod:`itasc.contact_analysis.shape_tables` pools it
+    #: across positions into a table named by :attr:`quantity_id`, keyed on these
+    #: columns. Empty ⇒ not aggregated into an index-keyed table (e.g. contacts).
+    #: Value columns are namespaced by ``quantity_id`` so a later joined view across
+    #: tables never has colliding names.
+    table_keys: ClassVar[tuple[str, ...]] = ()
+    #: Whether the studio threads the shared plot/build params (z-score shuffle
+    #: count, density field-of-view) into :meth:`build` via ``params``. Off by
+    #: default so a quantifier with its own ``params`` schema (contacts edge
+    #: extraction, shape, dynamics) is never handed the shared bar's keys.
+    wants_build_params: ClassVar[bool] = False
+    #: Shared build-param keys that must be present and positive for this
+    #: quantifier to build, mapped to the human label shown in the UI (e.g. cell
+    #: density needs ``{"fov_area_mm2": "FOV area (mm²)"}``). The studio greys the
+    #: metric out — rather than letting the build fail — until they are supplied.
+    #: Empty for a quantifier that needs no shared param.
+    required_build_params: ClassVar[dict[str, str]] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if cls.quantity_id:
+            _REGISTRY[cls.quantity_id] = cls
+
+    def can_build(self, inputs: PositionInputs) -> bool:
+        """True when *inputs* supplies every field named in :attr:`requires`."""
+        return all(getattr(inputs, name, None) is not None for name in self.requires)
+
+    def missing_build_params(self, params: Mapping[str, Any] | None) -> tuple[str, ...]:
+        """Labels of :attr:`required_build_params` that *params* doesn't satisfy.
+
+        A required key is satisfied when present and a positive number; anything
+        else (absent, blank, ``None``, non-positive) counts as missing. The studio
+        uses the returned labels to grey the metric out and explain why. Empty
+        tuple ⇒ every required shared param is supplied."""
+        params = params or {}
+        missing: list[str] = []
+        for key, label in self.required_build_params.items():
+            value = params.get(key)
+            if not (isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0):
+                missing.append(label)
+        return tuple(missing)
+
+    def default_output(self, inputs: PositionInputs) -> Path:
+        """Where this quantifier's artifact lives for *inputs*, by default.
+
+        ``position_dir / OUTPUT_SUBDIR / default_output_name`` — every quantity
+        lands in the shared :data:`OUTPUT_SUBDIR` folder, so each subclass sets
+        just a bare file name. The studio uses this to decide a build's
+        destination, so a second quantifier no longer inherits the contacts
+        artifact path. Subclasses may override for richer layouts.
+        """
+        if not self.default_output_name:
+            raise NotImplementedError(
+                f"{type(self).__name__} sets no default_output_name"
+            )
+        return inputs.position_dir / OUTPUT_SUBDIR / self.default_output_name
+
+    def is_built(self, output_path: Path) -> bool:
+        """True when the artifact at *output_path* already exists."""
+        return Path(output_path).is_file()
+
+    def object_table(self, output_path: Path) -> Mapping[str, Any] | None:
+        """A tidy, column-major per-object table for the plotting backend.
+
+        At least a ``frame`` key plus a per-object key (e.g. ``cell_id``).
+        Returns ``None`` when this quantifier produces no per-object table; the
+        plotting backend then skips it.
+        """
+        return None
+
+    def compute_object_table(
+        self, inputs: PositionInputs, *, params: dict | None = None
+    ) -> Mapping[str, Any] | None:
+        """The pooled tidy table for one position, computed directly from *inputs*.
+
+        A **pooled** quantifier (one that declares ``table_keys``) implements this:
+        it returns the same column-major table that ``object_table`` used to return
+        after a disk round-trip, but never touches disk. ``None`` when this position
+        yields no rows. Producers (``contacts``) are not pooled and do not implement
+        it. *params* carries the shared build knobs (e.g. ``fov_area_mm2``) for the
+        quantifiers that opt in; per-position values (pixel size, frame interval)
+        arrive via *inputs*.
+        """
+        raise NotImplementedError
+
+    def build(
+        self,
+        inputs: PositionInputs,
+        output_path: Path,
+        *,
+        params: dict | None = None,
+        progress_cb: Callable[[int, int, str], None] | None = None,
+    ) -> Path:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+    def read(self, output_path: Path) -> Any:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+
+def _import_quantifier_modules() -> None:
+    """Import every (non-private) ``quantifiers`` submodule so it self-registers."""
+    from . import quantifiers
+
+    for info in pkgutil.iter_modules(quantifiers.__path__):
+        if info.name.startswith("_"):
+            continue
+        importlib.import_module(f"{quantifiers.__name__}.{info.name}")
+
+
+def available_quantifiers() -> list[type[Quantifier]]:
+    """Return registered quantifier classes, sorted by display name."""
+    _import_quantifier_modules()
+    return sorted(_REGISTRY.values(), key=lambda cls: cls.display_name.lower())