itasc 0.2.0.dev0__py3-none-any.whl

itasc/contact_analysis/quantifiers/__init__.py

@@ -0,0 +1,7 @@
+"""Quantifier plugins.
+
+Dropping a ``*.py`` module here whose class subclasses
+:class:`itasc.contact_analysis.quantifier.Quantifier` (with a non-empty
+``quantity_id``) registers a new per-position quantity. ``available_quantifiers``
+imports every module here so they self-register.
+"""

itasc/contact_analysis/quantifiers/_contacts_derived.py

@@ -0,0 +1,42 @@
+"""Shared plumbing for the contacts-*derived* quantifiers.
+
+The neighbor count / density / signed-contact-length quantities are all computed
+from a position's already-built ``contact_analysis.h5``. They are **pooled**
+quantities: each runs its compute function over the contacts artifact at aggregate
+time (in :meth:`Quantifier.compute_object_table`) and the tidy table goes straight
+into the pooled output — no per-position artifact is persisted.
+
+This module factors out the one thing those quantifiers share: loading the
+contacts artifact for a position. All of it is **label-agnostic**.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from itasc.contact_analysis.contacts.reader import (
+    PositionContactAnalysis,
+    read_position_contacts,
+)
+from itasc.contact_analysis.quantifier import PositionInputs
+
+__all__ = [
+    "PositionContactAnalysis",
+    "load_analysis",
+]
+
+
+def load_analysis(inputs: PositionInputs) -> PositionContactAnalysis:
+    """Read the position's contacts artifact, or raise a clear error.
+
+    The derived quantifiers ``require`` ``contact_analysis_path``, so a missing /
+    not-yet-built file is a real precondition failure (a position lacking its
+    ``contact_analysis.h5`` is scoped out before pooling) rather than a silent
+    skip.
+    """
+    path = inputs.contact_analysis_path
+    if path is None or not Path(path).is_file():
+        raise FileNotFoundError(
+            "contact_analysis.h5 not found — build 'Cell–cell contacts' for this "
+            f"position first (looked for {path!r})."
+        )
+    return read_position_contacts(path)

itasc/contact_analysis/quantifiers/cell_density.py

@@ -0,0 +1,65 @@
+"""Cell-density quantifier — per-frame cell counts per field-of-view area.
+
+Counts cells straight off the tracked **cell labels** (unique non-zero labels per
+frame), so it is a cell-labels quantity, not a contacts-derived one. The
+field-of-view area is **required** — it comes from the shared params bar and there
+is no silent image-area fallback; ``density = n_cells / fov_area_mm2`` in
+cells/mm². One ``all`` total row per frame (label-agnostic). A **pooled** quantity:
+:meth:`compute_object_table` builds the tidy table in memory (no per-position
+artifact).
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+import numpy as np
+
+from itasc.contact_analysis.contacts.neighborhood import cell_density
+from itasc.contact_analysis.quantifier import PositionInputs, Quantifier
+from itasc.contact_analysis.shape.core import read_label_stack
+
+
+class CellDensityQuantifier(Quantifier):
+    """Per ``(frame, label)`` cell count and density (cells/mm²)."""
+
+    quantity_id = "cell_density"
+    display_name = "Cell density"
+    # Cell labels are the only hard input — counts come straight off them. The
+    # field-of-view area is a required build *param* (validated in
+    # ``compute_object_table``), not a PositionInputs field.
+    requires = ("cell_labels_path",)
+    # Density is keyed per (frame, label); ``label`` is always ``"all"``.
+    table_keys = ("frame", "label")
+    wants_build_params = True
+    # The field-of-view area has no image-area fallback, so it is a hard build
+    # requirement: the pooling loop skips Cell density (and the UI greys it out)
+    # until it is set, instead of letting the compute raise.
+    required_build_params = {"fov_area_mm2": "FOV area (mm²)"}
+
+    def compute_object_table(
+        self, inputs: PositionInputs, *, params: dict | None = None
+    ) -> Mapping[str, np.ndarray]:
+        fov = (params or {}).get("fov_area_mm2")
+        if not (isinstance(fov, (int, float)) and fov > 0):
+            raise ValueError(
+                "Cell density requires a field-of-view area — set 'FOV area (mm²)' "
+                "in Parameters before building."
+            )
+        frame_cells = _frame_cells_from_labels(inputs.cell_labels_path)
+        return cell_density(frame_cells, fov_area_mm2=float(fov))
+
+
+def _frame_cells_from_labels(labels_path: Path | None) -> dict[int, list[int]]:
+    """``frame -> [cell_id, …]`` from a tracked cell-label TIFF.
+
+    The unique non-zero labels of frame *i* are the cells present in it — the same
+    set the contacts ``cells`` table holds (it is one ``regionprops`` row per
+    label), so this reproduces the old per-frame counts without the artifact.
+    """
+    stack = read_label_stack(Path(labels_path))
+    out: dict[int, list[int]] = {}
+    for frame_idx, frame in enumerate(stack):
+        ids = np.unique(frame)
+        out[frame_idx] = [int(i) for i in ids if i != 0]
+    return out

itasc/contact_analysis/quantifiers/cell_dynamics.py

@@ -0,0 +1,81 @@
+"""Cell-dynamics quantifier — the registry adapter over the dynamics core.
+
+Wraps :mod:`itasc.contact_analysis.dynamics` so the studio can build
+and read per-cell motion through the generic :class:`Quantifier` interface. Its
+persistence is a multi-table ``4_contact_analysis/cell_dynamics.h5``;
+:meth:`object_table` exposes the per-frame instantaneous table (the only
+``(frame, cell_id)`` table) to the plotting backend. The cell twin of
+:mod:`.nucleus_dynamics` — they share the label-agnostic core and differ only by
+which label field they read and their output filename.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+import numpy as np
+
+from itasc.contact_analysis.dynamics import (
+    TrackDynamics,
+    build_track_dynamics,
+    read_instantaneous_table,
+    read_track_dynamics,
+)
+from itasc.contact_analysis.dynamics.kinematics import instantaneous_table
+from itasc.contact_analysis.dynamics.trajectories import extract_trajectories
+from itasc.contact_analysis.quantifier import PositionInputs, Quantifier
+
+
+class CellDynamicsQuantifier(Quantifier):
+    """Quantifies per-cell motion (speed, persistence, MSD, collective) from cell labels."""
+
+    quantity_id = "cell_dynamics"
+    display_name = "Cell dynamics"
+    requires = ("cell_labels_path",)
+    # Pixel size (µm/px) + frame interval (s/frame) are global build params, set
+    # once in the Parameters panel and applied to every position, so each output
+    # lands in physical units. They gate the build (unset ⇒ not buildable) and
+    # reach :meth:`build` via the stamped ``PositionInputs``, not the params dict.
+    required_build_params = {
+        "pixel_size_um": "pixel size (µm/px)",
+        "time_interval_s": "frame interval (s)",
+    }
+
+    default_output_name = "cell_dynamics.h5"
+    # The object_table is the per-(frame, cell_id) instantaneous motion table. The
+    # per-track / per-tissue / curve sub-tables are separate views (tracks / frames
+    # / dac_curves) and are not this quantifier's object_table.
+    table_keys = ("frame", "cell_id")
+
+    def build(
+        self,
+        inputs: PositionInputs,
+        output_path: Path,
+        *,
+        params: dict | None = None,
+        progress_cb: Callable[[int, int, str], None] | None = None,
+    ) -> Path:
+        return build_track_dynamics(
+            inputs.cell_labels_path,
+            output_path,
+            pixel_size_um=inputs.pixel_size_um,
+            time_interval_s=inputs.time_interval_s,
+            source_path=inputs.position_dir,
+            params=params,
+            quantity_id=self.quantity_id,
+            progress_cb=progress_cb,
+        )
+
+    def read(self, output_path: Path) -> TrackDynamics:
+        return read_track_dynamics(output_path)
+
+    def object_table(self, output_path: Path) -> Mapping[str, np.ndarray]:
+        return read_instantaneous_table(output_path)
+
+    def compute_object_table(
+        self, inputs: PositionInputs, *, params: dict | None = None
+    ) -> Mapping[str, np.ndarray]:
+        trajectories = extract_trajectories(
+            inputs.cell_labels_path, pixel_size_um=inputs.pixel_size_um
+        )
+        return instantaneous_table(trajectories, time_interval_s=inputs.time_interval_s)

itasc/contact_analysis/quantifiers/cell_shape.py

@@ -0,0 +1,32 @@
+"""Cell-shape quantifier — the registry adapter over the shape core.
+
+Exposes per-cell morphology through the generic :class:`Quantifier` interface as
+a **pooled** quantity: :meth:`compute_object_table` runs the shape core over the
+cell label stack in memory and hands the tidy table straight to the pooling layer
+(no per-position artifact is persisted). The object-key column is ``cell_id`` (the
+shared track id).
+"""
+from __future__ import annotations
+
+from itasc.contact_analysis.quantifier import Quantifier
+from itasc.contact_analysis.shape import compute_object_shape
+
+
+class CellShapeQuantifier(Quantifier):
+    """Quantifies per-cell, per-frame shape descriptors from cell labels."""
+
+    quantity_id = "cell_shape"
+    display_name = "Cell shape"
+    # Cell labels only; no nucleus / contacts dependency. Pixel size (to emit
+    # physical µm / µm²) is a global build param set in the Parameters panel.
+    requires = ("cell_labels_path",)
+    required_build_params = {"pixel_size_um": "pixel size (µm/px)"}
+    #: Per-cell, per-frame shape descriptors, keyed (frame, cell_id).
+    table_keys = ("frame", "cell_id")
+
+    def compute_object_table(self, inputs, *, params=None):
+        return compute_object_shape(
+            inputs.cell_labels_path,
+            pixel_size_um=inputs.pixel_size_um,
+            object_key="cell_id",
+        )

itasc/contact_analysis/quantifiers/contacts.py

@@ -0,0 +1,72 @@
+"""Cell-cell contacts quantifier — the registry adapter over the contacts code.
+
+Wraps :mod:`itasc.contact_analysis.contacts` so the studio can build
+and read contacts through the generic :class:`Quantifier` interface. Its chosen
+persistence is the ``contact_analysis.h5`` schema, unchanged from before the
+rename.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from itasc.contact_analysis.contacts.build import build_contacts
+from itasc.contact_analysis.contacts.reader import (
+    read_position_contacts,
+)
+from itasc.contact_analysis.quantifier import PositionInputs, Quantifier
+
+
+class ContactsQuantifier(Quantifier):
+    """Quantifies cell-cell contacts: edges, T1 events, NLS classes."""
+
+    quantity_id = "contacts"
+    display_name = "Cell–cell contacts"
+    # Cell labels are mandatory; nucleus labels are optional (when present they
+    # enable the cell_id == nucleus_id invariant check and NLS classification).
+    requires = ("cell_labels_path",)
+    #: The contacts artifact is the input the contacts-derived quantifiers
+    #: (neighbor count / enrichment / z-score / density / signed contact length) consume.
+    produces = "contact_analysis_path"
+
+    #: Default artifact name when a position does not dictate one.
+    default_output_name = "contact_analysis.h5"
+
+    def build(
+        self,
+        inputs: PositionInputs,
+        output_path: Path,
+        *,
+        params: dict | None = None,
+        progress_cb: Callable[[int, int, str], None] | None = None,
+    ) -> Path:
+        return build_contacts(
+            cell_labels_path=inputs.cell_labels_path,
+            nucleus_labels_path=inputs.nucleus_labels_path,
+            output_path=output_path,
+            source_path=inputs.position_dir,
+            edge_extraction_params=params,
+            progress_cb=progress_cb,
+        )
+
+    def default_output(self, inputs: PositionInputs) -> Path:
+        """The contacts ``.h5`` lives in the position base folder, beside the
+        committed ``cell_labels.tif`` / ``nucleus_labels.tif`` — not under the
+        shared :data:`~itasc.contact_analysis.quantifier.OUTPUT_SUBDIR` that the
+        other (dynamics) quantifiers persist into. One homogeneous per-position
+        layout for the downstream-stable inputs and this derived-from-them graph.
+        """
+        return inputs.position_dir / self.default_output_name
+
+    def read(self, output_path: Path) -> Any:
+        return read_position_contacts(output_path)
+
+    def object_table(self, output_path: Path) -> Mapping[str, np.ndarray]:
+        """The per-cell ``cells`` table (``frame`` · ``cell_id`` · morphometry).
+
+        The subpopulation label is no longer carried here — it lives in the NLS
+        sidecar CSV and is joined by ``cell_id`` at pool time."""
+        return read_position_contacts(output_path).cells

itasc/contact_analysis/quantifiers/neighbor_count.py

@@ -0,0 +1,26 @@
+"""Neighbor-count quantifier — per-cell adjacency degree from the contact graph.
+
+A contacts-derived **pooled** quantity: :meth:`compute_object_table` reads the
+position's ``contact_analysis.h5`` and returns the per ``(frame, cell_id)``
+neighbor count in memory (no per-position artifact). The NLS subpopulation label
+is *not* stored here — it is left-joined by ``cell_id`` at pool time, exactly as
+the shape family does.
+"""
+from __future__ import annotations
+
+from itasc.contact_analysis.contacts.neighborhood import cell_neighbor_counts
+from itasc.contact_analysis.quantifier import Quantifier
+from itasc.contact_analysis.quantifiers import _contacts_derived as derived
+
+
+class NeighborCountQuantifier(Quantifier):
+    """Per ``(frame, cell_id)`` number of distinct cell-cell neighbors."""
+
+    quantity_id = "neighbor_count"
+    display_name = "Neighbor count"
+    requires = ("contact_analysis_path",)
+    # Per-cell adjacency degree, keyed (frame, cell_id).
+    table_keys = ("frame", "cell_id")
+
+    def compute_object_table(self, inputs, *, params=None):
+        return dict(cell_neighbor_counts(derived.load_analysis(inputs)))

itasc/contact_analysis/quantifiers/nucleus_dynamics.py

@@ -0,0 +1,77 @@
+"""Nucleus-dynamics quantifier — the registry adapter over the dynamics core.
+
+The nucleus twin of :mod:`.cell_dynamics`: it runs the same label-agnostic
+:func:`build_track_dynamics` over the **nucleus** label stack instead of the cell
+one, persisting ``4_contact_analysis/nucleus_dynamics.h5``. Nuclei are
+compact, point-like centroids — the robust default for motility / MSD. The
+object-key column stays ``cell_id`` (a nucleus is nucleus-seeded so it carries
+its cell's shared track id), so the pooling / plotting layer treats it no
+differently.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+import numpy as np
+
+from itasc.contact_analysis.dynamics import (
+    TrackDynamics,
+    build_track_dynamics,
+    read_instantaneous_table,
+    read_track_dynamics,
+)
+from itasc.contact_analysis.dynamics.kinematics import instantaneous_table
+from itasc.contact_analysis.dynamics.trajectories import extract_trajectories
+from itasc.contact_analysis.quantifier import PositionInputs, Quantifier
+
+
+class NucleusDynamicsQuantifier(Quantifier):
+    """Quantifies per-nucleus motion (speed, persistence, MSD, collective) from nucleus labels."""
+
+    quantity_id = "nucleus_dynamics"
+    display_name = "Nucleus dynamics"
+    requires = ("nucleus_labels_path",)
+    # Pixel size + frame interval are global build params (see CellDynamics).
+    required_build_params = {
+        "pixel_size_um": "pixel size (µm/px)",
+        "time_interval_s": "frame interval (s)",
+    }
+
+    default_output_name = "nucleus_dynamics.h5"
+    # Instantaneous nucleus motion is keyed on the shared cell track id
+    # (frame, cell_id).
+    table_keys = ("frame", "cell_id")
+
+    def build(
+        self,
+        inputs: PositionInputs,
+        output_path: Path,
+        *,
+        params: dict | None = None,
+        progress_cb: Callable[[int, int, str], None] | None = None,
+    ) -> Path:
+        return build_track_dynamics(
+            inputs.nucleus_labels_path,
+            output_path,
+            pixel_size_um=inputs.pixel_size_um,
+            time_interval_s=inputs.time_interval_s,
+            source_path=inputs.position_dir,
+            params=params,
+            quantity_id=self.quantity_id,
+            progress_cb=progress_cb,
+        )
+
+    def read(self, output_path: Path) -> TrackDynamics:
+        return read_track_dynamics(output_path)
+
+    def object_table(self, output_path: Path) -> Mapping[str, np.ndarray]:
+        return read_instantaneous_table(output_path)
+
+    def compute_object_table(
+        self, inputs: PositionInputs, *, params: dict | None = None
+    ) -> Mapping[str, np.ndarray]:
+        trajectories = extract_trajectories(
+            inputs.nucleus_labels_path, pixel_size_um=inputs.pixel_size_um
+        )
+        return instantaneous_table(trajectories, time_interval_s=inputs.time_interval_s)

itasc/contact_analysis/quantifiers/nucleus_shape.py

@@ -0,0 +1,35 @@
+"""Nucleus-shape quantifier — the registry adapter over the shape core.
+
+The nucleus twin of :mod:`.cell_shape`: :meth:`compute_object_table` runs the same
+label-agnostic :func:`compute_object_shape` over the **nucleus** label stack
+instead of the cell one and pools the tidy table in memory (no per-position
+artifact). The object-key column stays ``cell_id`` — a nucleus is nucleus-seeded
+so it carries its cell's shared track id — so nothing in the pooling layer treats
+it differently.
+"""
+from __future__ import annotations
+
+from itasc.contact_analysis.quantifier import Quantifier
+from itasc.contact_analysis.shape import compute_object_shape
+
+
+class NucleusShapeQuantifier(Quantifier):
+    """Quantifies per-nucleus, per-frame shape descriptors from nucleus labels."""
+
+    quantity_id = "nucleus_shape"
+    display_name = "Nucleus shape"
+    # Nucleus labels only; pixel size (to emit physical µm / µm²) is a global
+    # build param set in the Parameters panel.
+    requires = ("nucleus_labels_path",)
+    required_build_params = {"pixel_size_um": "pixel size (µm/px)"}
+    # Nucleus shape is keyed on its cell's shared track id (frame, cell_id); its
+    # descriptors are namespaced by quantity_id (so the nucleus ``area`` never
+    # collides with the cell ``area`` in a joined view).
+    table_keys = ("frame", "cell_id")
+
+    def compute_object_table(self, inputs, *, params=None):
+        return compute_object_shape(
+            inputs.nucleus_labels_path,
+            pixel_size_um=inputs.pixel_size_um,
+            object_key="cell_id",
+        )

itasc/contact_analysis/quantifiers/shape_relational.py

@@ -0,0 +1,34 @@
+"""Relational shape quantifier — nucleus-vs-cell paired morphology.
+
+Wraps :func:`itasc.contact_analysis.shape.compute_relational_table`, which
+pairs each nucleus with its cell on the shared ``(frame, id)`` key and emits
+relational quantities (nuclear:cell area ratio, centroid offset, orientation
+delta, …). Needs **both** label stacks plus a pixel size. A **pooled** quantity:
+:meth:`compute_object_table` builds the tidy table in memory (no per-position
+artifact). The object-key column is ``cell_id``, so the relational table pools
+through the same path as the per-source shape tables.
+"""
+from __future__ import annotations
+
+from itasc.contact_analysis.quantifier import Quantifier
+from itasc.contact_analysis.shape import compute_relational_table
+
+
+class ShapeRelationalQuantifier(Quantifier):
+    """Quantifies per-(frame, cell) relational nucleus-vs-cell shape."""
+
+    quantity_id = "shape_relational"
+    display_name = "Nucleus–cell shape"
+    # Both label stacks (to pair); pixel size (to emit physical units) is a
+    # global build param set in the Parameters panel.
+    requires = ("cell_labels_path", "nucleus_labels_path")
+    required_build_params = {"pixel_size_um": "pixel size (µm/px)"}
+    # Per-cell nucleus↔cell relational descriptors, keyed (frame, cell_id).
+    table_keys = ("frame", "cell_id")
+
+    def compute_object_table(self, inputs, *, params=None):
+        return compute_relational_table(
+            inputs.cell_labels_path,
+            inputs.nucleus_labels_path,
+            pixel_size_um=inputs.pixel_size_um,
+        )

itasc/contact_analysis/quantifiers/signed_contact_length.py

@@ -0,0 +1,44 @@
+"""Signed-contact-length quantifier — signed T1 junction lengths for the potential.
+
+A contacts-derived **pooled** quantity: :meth:`compute_object_table` returns the
+signed central-junction length of each T1 event (negative on the losing side,
+positive on the gaining side) in memory (no per-position artifact). Pooled and
+Boltzmann-inverted downstream these reproduce the double-well potential. Lengths
+are in µm when the position's pixel size resolves, else pixels. The
+``contact_type`` transition label is normalized here (blank → ``"unlabelled"``) so
+a group axis never sees an empty string.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from itasc.contact_analysis.contacts.signed_contact_length import (
+    signed_central_junction_lengths,
+)
+from itasc.contact_analysis.quantifier import Quantifier
+from itasc.contact_analysis.quantifiers import _contacts_derived as derived
+
+
+class SignedContactLengthQuantifier(Quantifier):
+    """Per-T1-event signed central junction length (the potential's samples)."""
+
+    quantity_id = "signed_contact_length"
+    display_name = "Signed contact length"
+    requires = ("contact_analysis_path",)
+    # One row per T1 event; ``contact_type`` / ``role`` are categorical axes that
+    # key the table alongside the event id (only ``signed_length`` is a value
+    # column).
+    table_keys = ("frame", "t1_event_id", "role", "contact_type")
+
+    def compute_object_table(self, inputs, *, params=None):
+        analysis = derived.load_analysis(inputs)
+        table = dict(
+            signed_central_junction_lengths(
+                analysis, pixel_size_um=inputs.pixel_size_um
+            )
+        )
+        if "contact_type" in table:
+            ct = np.asarray(table["contact_type"], dtype=object)
+            ct[ct == ""] = "unlabelled"
+            table["contact_type"] = ct
+        return table

itasc/contact_analysis/records.py

@@ -0,0 +1,129 @@
+"""Qt-free bridge from catalogue *records* to a quantifier's per-position files.
+
+The studio carries positions as normalized catalogue ``record`` dicts (see
+:mod:`itasc.contact_analysis.catalog`). Turning one into the
+:class:`~itasc.contact_analysis.quantifier.PositionInputs` a quantifier
+builds from — and resolving where that quantifier's artifact lives — is pure path
+logic with no Qt. It lives here (rather than in the napari studio layer) so the
+headless aggregation backend (:mod:`.shape_tables`) and the standalone
+``itasc-aggregate`` wheel can resolve the same paths the pipeline does.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import fields as _dataclass_fields
+from pathlib import Path
+
+from .quantifier import PositionInputs, Quantifier, available_quantifiers
+
+__all__ = [
+    "position_inputs_from_record",
+    "output_for_record",
+    "available_fields",
+    "record_build_params",
+    "supported_quantities",
+]
+
+
+def position_inputs_from_record(record: dict) -> PositionInputs:
+    """Build :class:`PositionInputs` from a normalized catalogue record.
+
+    ``pixel_size_um`` / ``time_interval_s`` are **global** build params: they are
+    taken only from the value stamped on the record (the Parameters panel's
+    px/Δt), never auto-resolved from a position's config or label TIFF tags.
+    Absent ⇒ ``None``.
+    """
+    out = record.get("contact_analysis_path")
+    cell = record.get("cell_tracked_labels_path")
+    nucleus = record.get("nucleus_tracked_labels_path")
+    position_dir = record.get("position_path") or (Path(out).parent if out else Path("."))
+    cell_path = Path(cell) if cell else None
+    nucleus_path = Path(nucleus) if nucleus else None
+    return PositionInputs(
+        position_dir=Path(position_dir),
+        cell_labels_path=cell_path,
+        nucleus_labels_path=nucleus_path,
+        pixel_size_um=_positive_float(record.get("pixel_size_um")),
+        time_interval_s=_positive_float(record.get("time_interval_s")),
+        # The contacts artifact is a *produced* input — the contacts quantifier
+        # writes it. The catalogue stamps its expected path on every position
+        # whether or not it has been built yet, so gate on the file actually
+        # existing: an unbuilt contacts product is not an available input.
+        contact_analysis_path=Path(out) if out and Path(out).is_file() else 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
+
+
+def output_for_record(quantifier: Quantifier, record: dict) -> Path:
+    """Where *quantifier*'s artifact lives for a catalogue *record*.
+
+    Contacts keeps using the catalogue's explicit ``contact_analysis_path``
+    column — it predates the quantifier seam and may hold a custom *nested* path
+    that the per-position read/visualize paths also rely on, so building must
+    target the same file. Every other quantifier derives its destination from
+    :meth:`Quantifier.default_output`.
+    """
+    if quantifier.quantity_id == "contacts":
+        explicit = record.get("contact_analysis_path")
+        if explicit:
+            return Path(explicit)
+    return quantifier.default_output(position_inputs_from_record(record))
+
+
+def available_fields(inputs: PositionInputs) -> set[str]:
+    """The populated (non-``None``) ``PositionInputs`` field names — the satisfied
+    prerequisites a quantifier's ``requires`` is checked against."""
+    return {f.name for f in _dataclass_fields(inputs) if getattr(inputs, f.name) is not None}
+
+
+def record_build_params(
+    quantifier: Quantifier, record: dict, params: Mapping[str, object] | None
+) -> dict:
+    """Shared *params* overlaid with the record's own required-build-param values.
+
+    A param like pixel size can be set per-position on the record (the value the
+    build actually reads via ``PositionInputs``) instead of in the shared bar, so
+    the build-param gate must see both. The record's own value wins where present,
+    mirroring ``run()``'s per-record stamping.
+    """
+    merged = dict(params or {})
+    for key in quantifier.required_build_params:
+        value = record.get(key)
+        if value is not None:
+            merged[key] = value
+    return merged
+
+
+def supported_quantities(
+    records: Sequence[dict], *, params: Mapping[str, object] | None = None
+) -> set[str]:
+    """``quantity_id``\\ s of the pooled quantifiers *records* can actually produce.
+
+    A pooled quantifier (one declaring ``table_keys``) is *supported* when at least
+    one record satisfies **both** gates :func:`shape_tables.build_table` applies per
+    position: its ``requires`` inputs are present (:meth:`Quantifier.can_build`) and
+    its ``required_build_params`` are satisfied (pixel size, FOV area, …). That makes
+    "supported" ⟺ "this table would pool at least one non-empty row" — the exact
+    predicate the Aggregate UI greys its checkboxes against, so an enabled box never
+    promises a table the run would silently skip. Producers (no ``table_keys``, e.g.
+    ``contacts``) are never pooled and so never reported.
+    """
+    supported: set[str] = set()
+    for quantifier in (cls() for cls in available_quantifiers()):
+        if not quantifier.table_keys:
+            continue
+        for record in records:
+            inputs = position_inputs_from_record(record)
+            if quantifier.can_build(inputs) and not quantifier.missing_build_params(
+                record_build_params(quantifier, record, params)
+            ):
+                supported.add(quantifier.quantity_id)
+                break
+    return supported

itasc/contact_analysis/shape/__init__.py

@@ -0,0 +1,19 @@
+"""Shape compute core: per-object morphology + relational nucleus-vs-cell shape.
+
+The headless backend for the shape quantifiers. :func:`compute_object_shape` runs
+:func:`skimage.measure.regionprops` over any tracked-label stack (cell *or*
+nucleus) and returns a tidy column-major table; :func:`compute_relational_table`
+pairs each nucleus with its cell and emits relational quantities. Both compute in
+memory — the aggregate stage pools the tables, nothing is persisted per position.
+No Qt / napari import, so scripts and the standalone wheel can use it.
+"""
+
+from .core import DESCRIPTOR_COLUMNS, compute_object_shape
+from .relational import RELATIONAL_COLUMNS, compute_relational_table
+
+__all__ = [
+    "DESCRIPTOR_COLUMNS",
+    "RELATIONAL_COLUMNS",
+    "compute_object_shape",
+    "compute_relational_table",
+]