itasc 0.2.0.dev0__py3-none-any.whl

itasc/contact_analysis/contacts/contact_labels.py

@@ -0,0 +1,136 @@
+"""Contact cell-type labels — propagate a per-cell label onto contacts.
+
+Each cell–cell contact (a row of the ``edges`` table) is labelled by the
+unordered pair of its two cells' labels, supplied as a generic ``cell_id -> label``
+map. A contact between cell types ``A`` and ``B`` is labelled ``"A-B"`` (sorted), so
+a consumer can ask how subpopulations contact each other — homotypic vs
+heterotypic — without that aggregation living here. The label map is the caller's
+concern (e.g. a downstream, dataset-specific classification); this module is
+label-agnostic.
+
+Headless and Qt-free, like
+:mod:`itasc.contact_analysis.contacts.signed_contact_length`: it operates on an
+already-read
+:class:`~itasc.contact_analysis.contacts.reader.PositionContactAnalysis`
+plus a ``cell_id -> label`` map, so it never opens HDF5 itself and runs unchanged in
+scripts, notebooks, and plugins.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+
+from itasc.contact_analysis.contacts.reader import PositionContactAnalysis
+
+#: Columns the label table carries, in order. Kept as a constant so the empty
+#: table and the populated one cannot drift apart.
+_COLUMNS = (
+    "frame",
+    "edge_id",
+    "cell_a",
+    "cell_b",
+    "label_a",
+    "label_b",
+    "contact_label",
+    "homotypic",
+    "fully_classified",
+    "length",
+)
+
+
+def contact_label_for(
+    labels: Mapping[int, str],
+    cell_a: int,
+    cell_b: int,
+    *,
+    unclassified: str = "unclassified",
+) -> str:
+    """The sorted ``"label_a-label_b"`` contact label for one cell pair.
+
+    Each cell's label is looked up in *labels* (``cell_id -> label``); a cell
+    absent from the map takes *unclassified*. The pair is sorted so the contact
+    type is orientation-independent (``"A-B" == "B-A"``). This is the single
+    definition shared by :func:`label_contacts` (the per-edge table) and the
+    signed-contact-length reaction coordinate, so a contact types identically
+    wherever it is seen.
+    """
+    label_a = labels.get(int(cell_a), unclassified)
+    label_b = labels.get(int(cell_b), unclassified)
+    return "-".join(sorted((label_a, label_b)))
+
+
+def label_contacts(
+    analysis: PositionContactAnalysis,
+    labels: Mapping[int, str],
+    *,
+    unclassified: str = "unclassified",
+) -> dict[str, np.ndarray]:
+    """Label every cell–cell contact by its two cells' NLS subpopulation labels.
+
+    For each ``kind == "cell_cell"`` edge, each endpoint's label is looked up in
+    *labels* (``cell_id -> label``; a cell absent from the map takes
+    *unclassified*) and the unordered-pair contact label
+    ``"-".join(sorted([label_a, label_b]))`` is formed. The vocabulary is whatever
+    *labels* holds — nothing here is hard-wired to positive/negative.
+
+    Border edges (``kind == "border"``, ``cell_b == 0``) are not contacts between
+    two cells and are excluded. Fragments are **not** joined: a boundary split
+    across several edge rows yields several labelled rows that share the same
+    ``(frame, cell_a, cell_b)`` and therefore the same label; ``edge_id`` and
+    ``length`` are carried through so a consumer can join or length-weight later.
+
+    Columns (column-major, all equal length, one row per cell–cell edge):
+
+    * ``frame``               — the edge's frame.
+    * ``edge_id``             — the edge's id within its frame.
+    * ``cell_a`` / ``cell_b`` — the contacting cell ids (as stored, ``a < b``).
+    * ``label_a`` / ``label_b`` — each cell's NLS label, or *unclassified*.
+    * ``contact_label``       — sorted ``"label_a-label_b"`` pair.
+    * ``homotypic``           — ``label_a == label_b`` (True for two unclassified;
+      gate on ``fully_classified`` if that matters).
+    * ``fully_classified``    — both cells had a label in *labels*.
+    * ``length``              — the edge length, carried through for weighting.
+
+    Returns empty (but typed) arrays when there are no cell–cell edges.
+    """
+    edges = analysis.edges
+    frame = np.asarray(edges.get("frame", ()), dtype=np.int64)
+    edge_id = np.asarray(edges.get("edge_id", ()), dtype=np.int64)
+    cell_a = np.asarray(edges.get("cell_a", ()), dtype=np.int64)
+    cell_b = np.asarray(edges.get("cell_b", ()), dtype=np.int64)
+    length = np.asarray(edges.get("length", ()), dtype=float)
+    kind = np.asarray(edges.get("kind", np.full(frame.shape, "cell_cell")), dtype=object)
+
+    out: dict[str, list] = {name: [] for name in _COLUMNS}
+
+    for i in range(frame.size):
+        if str(kind[i]) != "cell_cell":
+            continue
+        ca, cb = int(cell_a[i]), int(cell_b[i])
+        present_a, present_b = ca in labels, cb in labels
+        label_a = labels.get(ca, unclassified)
+        label_b = labels.get(cb, unclassified)
+        out["frame"].append(int(frame[i]))
+        out["edge_id"].append(int(edge_id[i]) if edge_id.size else 0)
+        out["cell_a"].append(ca)
+        out["cell_b"].append(cb)
+        out["label_a"].append(label_a)
+        out["label_b"].append(label_b)
+        out["contact_label"].append(contact_label_for(labels, ca, cb, unclassified=unclassified))
+        out["homotypic"].append(label_a == label_b)
+        out["fully_classified"].append(present_a and present_b)
+        out["length"].append(float(length[i]))
+
+    return {
+        "frame": np.asarray(out["frame"], dtype=np.int64),
+        "edge_id": np.asarray(out["edge_id"], dtype=np.int64),
+        "cell_a": np.asarray(out["cell_a"], dtype=np.int64),
+        "cell_b": np.asarray(out["cell_b"], dtype=np.int64),
+        "label_a": np.asarray(out["label_a"], dtype=object),
+        "label_b": np.asarray(out["label_b"], dtype=object),
+        "contact_label": np.asarray(out["contact_label"], dtype=object),
+        "homotypic": np.asarray(out["homotypic"], dtype=bool),
+        "fully_classified": np.asarray(out["fully_classified"], dtype=bool),
+        "length": np.asarray(out["length"], dtype=float),
+    }

itasc/contact_analysis/contacts/neighborhood.py

@@ -0,0 +1,146 @@
+"""Neighborhood & density derivations over the cell–cell contact graph.
+
+Two headless, Qt-free, **label-agnostic** derivations on an already-read
+:class:`~itasc.contact_analysis.contacts.reader.PositionContactAnalysis`,
+each returning a tidy column-major table (``dict[str, np.ndarray]``):
+
+* :func:`cell_neighbor_counts` — adjacency degree per cell (how many neighbors).
+* :func:`cell_density` — cells per unit field-of-view area. (Counts straight off
+  a ``frame -> [cell_id, …]`` map, so it needs only the cell labels, not the
+  contact graph.)
+
+The ``cell_cell`` edges of the contacts ``edges`` table *are* the adjacency
+graph; degree is the count of incident ``cell_cell`` edges, deduped per neighbor
+(a boundary split across several edge rows still counts as one neighbor).
+
+The classification-dependent derivations (neighbour enrichment; contact-type
+z-score vs a label-shuffle null) are **not** here — they consume a per-cell
+subpopulation ``class_label`` and so live with the dataset that defines it, not in
+this label-agnostic library.
+
+Like :mod:`...contacts.signed_contact_length` and :mod:`...contacts.contact_labels`, these
+operate on the in-memory analysis object only: they never open HDF5, so they run
+unchanged in scripts, notebooks, and the napari plugin.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+
+from itasc.contact_analysis.contacts.reader import PositionContactAnalysis
+
+
+def _frame_adjacency(analysis: PositionContactAnalysis) -> dict[int, dict[int, set[int]]]:
+    """``frame -> {cell_id -> set(neighbor cell_ids)}`` from ``cell_cell`` edges.
+
+    Only ``kind == "cell_cell"`` rows contribute; border edges (``kind ==
+    "border"``) are excluded. Each edge ``(cell_a, cell_b)`` adds each endpoint to
+    the other's neighbor *set*, so a boundary fragmented into several edge rows
+    still counts as a single neighbor relation (the set dedupes). Degree is
+    ``len(neighbors[cell_id])``.
+    """
+    edges = analysis.edges
+    frame = np.asarray(edges.get("frame", ()), dtype=np.int64)
+    cell_a = np.asarray(edges.get("cell_a", ()), dtype=np.int64)
+    cell_b = np.asarray(edges.get("cell_b", ()), dtype=np.int64)
+    kind = np.asarray(edges.get("kind", np.full(frame.shape, "cell_cell")), dtype=object)
+
+    adjacency: dict[int, dict[int, set[int]]] = defaultdict(lambda: defaultdict(set))
+    for i in range(frame.size):
+        if str(kind[i]) != "cell_cell":
+            continue
+        fr, ca, cb = int(frame[i]), int(cell_a[i]), int(cell_b[i])
+        adjacency[fr][ca].add(cb)
+        adjacency[fr][cb].add(ca)
+    return adjacency
+
+
+def _frame_cells(analysis: PositionContactAnalysis) -> dict[int, list[int]]:
+    """``frame -> [cell_id, …]`` (ascending) from the ``cells`` table.
+
+    The cells table is the authority on which cells are present in a frame, so an
+    isolated cell (degree 0) still counts toward degree, abundance, and density.
+    """
+    cells = analysis.cells
+    frame = np.asarray(cells.get("frame", ()), dtype=np.int64)
+    cell_id = np.asarray(cells.get("cell_id", ()), dtype=np.int64)
+    out: dict[int, list[int]] = defaultdict(list)
+    for fr, cid in zip(frame, cell_id):
+        out[int(fr)].append(int(cid))
+    for ids in out.values():
+        ids.sort()
+    return out
+
+
+def cell_neighbor_counts(analysis: PositionContactAnalysis) -> dict[str, np.ndarray]:
+    """Per ``(frame, cell_id)`` adjacency degree — the headline neighbor count.
+
+    One row per cell present in the ``cells`` table for that frame, with
+    ``n_neighbors`` its number of distinct ``cell_cell`` neighbors (0 for an
+    isolated cell). This count is also the numerator for density.
+
+    Columns (column-major, equal length): ``frame``, ``cell_id``,
+    ``n_neighbors`` (int).
+    """
+    adjacency = _frame_adjacency(analysis)
+    frame_cells = _frame_cells(analysis)
+
+    out_frame: list[int] = []
+    out_cell: list[int] = []
+    out_n: list[int] = []
+    for fr in sorted(frame_cells):
+        neighbors = adjacency.get(fr, {})
+        for cid in frame_cells[fr]:
+            out_frame.append(fr)
+            out_cell.append(cid)
+            out_n.append(len(neighbors.get(cid, ())))
+    return {
+        "frame": np.asarray(out_frame, dtype=np.int64),
+        "cell_id": np.asarray(out_cell, dtype=np.int64),
+        "n_neighbors": np.asarray(out_n, dtype=np.int64),
+    }
+
+
+def cell_density(
+    frame_cells: Mapping[int, Sequence[int]],
+    *,
+    fov_area_mm2: float,
+) -> dict[str, np.ndarray]:
+    """Per ``frame`` cell count and ``density = n_cells / fov_area_mm2``.
+
+    Emits one ``label="all"`` row per frame that counts **every** cell in the
+    frame. ``density`` is in cells/mm²; *fov_area_mm2* is the user's field-of-view
+    area and is **required** (a positive number) — there is no silent image-area
+    fallback.
+
+    *frame_cells* maps ``frame -> [cell_id, …]`` (the cell labels present in that
+    frame), so this counts straight off the cell labels with no contacts
+    dependency.
+
+    Columns: ``frame``, ``label`` (str, always ``"all"``), ``n_cells`` (int),
+    ``density`` (float, cells/mm²).
+    """
+    area = float(fov_area_mm2)
+    if not area > 0:
+        raise ValueError("cell_density requires a positive fov_area_mm2")
+
+    out_frame: list[int] = []
+    out_label: list[str] = []
+    out_n: list[int] = []
+    out_density: list[float] = []
+
+    for fr in sorted(frame_cells):
+        n_cells = len(frame_cells[fr])
+        out_frame.append(fr)
+        out_label.append("all")
+        out_n.append(n_cells)
+        out_density.append(n_cells / area)
+
+    return {
+        "frame": np.asarray(out_frame, dtype=np.int64),
+        "label": np.asarray(out_label, dtype=object),
+        "n_cells": np.asarray(out_n, dtype=np.int64),
+        "density": np.asarray(out_density, dtype=float),
+    }

itasc/contact_analysis/contacts/reader.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import h5py
+import numpy as np
+
+
+def _read_dataset(dataset: h5py.Dataset) -> np.ndarray:
+    if h5py.check_string_dtype(dataset.dtype) is not None:
+        return dataset.asstr()[:]
+    return dataset[:]
+
+
+def _read_table(group: h5py.Group) -> dict[str, np.ndarray]:
+    return {name: _read_dataset(dataset) for name, dataset in group.items()}
+
+
+@dataclass(frozen=True)
+class PositionContactAnalysis:
+    cells: dict[str, np.ndarray]
+    edges: dict[str, np.ndarray]
+    t1_events: dict[str, np.ndarray]
+    cell_tracked_labels_path: str
+    nucleus_tracked_labels_path: str
+    _edge_coord_y: np.ndarray = field(repr=False)
+    _edge_coord_x: np.ndarray = field(repr=False)
+
+    @property
+    def coord_y(self) -> np.ndarray:
+        return self._edge_coord_y
+
+    @property
+    def coord_x(self) -> np.ndarray:
+        return self._edge_coord_x
+
+
+def read_position_contacts(path: str | Path) -> PositionContactAnalysis:
+    path = Path(path)
+    with h5py.File(path, "r") as h5:
+        provenance = h5["provenance"].attrs
+        cell_tracked_labels_path = str(provenance["cell_tracked_labels_path"])
+        nucleus_tracked_labels_path = str(provenance["nucleus_tracked_labels_path"])
+        cells = _read_table(h5["cells/table"])
+        edges = _read_table(h5["edges/table"])
+        t1_events = _read_table(h5["t1_events/table"])
+        edge_coord_y = h5["edges/coordinates/y"][:]
+        edge_coord_x = h5["edges/coordinates/x"][:]
+    return PositionContactAnalysis(
+        cells=cells,
+        edges=edges,
+        t1_events=t1_events,
+        cell_tracked_labels_path=cell_tracked_labels_path,
+        nucleus_tracked_labels_path=nucleus_tracked_labels_path,
+        _edge_coord_y=edge_coord_y,
+        _edge_coord_x=edge_coord_x,
+    )

itasc/contact_analysis/contacts/signed_contact_length.py

@@ -0,0 +1,143 @@
+"""Signed contact length — the signed central junction-length reaction coordinate.
+
+Boltzmann-inversion of this coordinate yields the effective potential / barrier
+``ΔE_eff`` of T1 transitions: the energy a junction climbs to reach the
+four-fold vertex. That inversion and the resulting potential-landscape plot are
+downstream concerns owned by the data repo, not this package — this
+module only computes the signed lengths themselves. It is the ITASC
+analogue of the reference's ``extract_central_junction_lengths`` /
+``plot_signed_lengths_neg_log_p_histogram`` (``morphogenesis-on-chip_analysis``),
+but the sign comes from the ``t1_events`` table (``losing`` ↔ ``gaining`` pairs)
+rather than curated "quad" JSONs.
+
+Headless and Qt-free: it operates on an already-read
+:class:`~itasc.contact_analysis.contacts.reader.PositionContactAnalysis`,
+so it never opens HDF5 itself and runs unchanged in scripts, notebooks, and the
+napari plugin.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Mapping
+
+import numpy as np
+
+from itasc.contact_analysis.contacts.contact_labels import contact_label_for
+from itasc.contact_analysis.contacts.reader import PositionContactAnalysis
+
+
+def signed_central_junction_lengths(
+    analysis: PositionContactAnalysis,
+    *,
+    pixel_size_um: float | None = None,
+    labels: Mapping[int, str] | None = None,
+) -> dict[str, np.ndarray]:
+    """Signed central junction length per T1 event, per frame.
+
+    For each T1 event the central junction is the edge that flips from the
+    *losing* cell pair (pre-transition) to the *gaining* pair (post-transition).
+    Every frame in which an event's losing edge exists contributes a **negative**
+    sample (``−length``); every frame its gaining edge exists contributes a
+    **positive** one (``+length``). The magnitude is the edge length; it crosses
+    zero at the four-fold vertex, so pooled and inverted these reproduce the
+    reference's double-well potential without curated quads.
+
+    Fragmented contacts are joined first: the build splits a single cell-cell
+    boundary into several edge rows (one per disconnected segment from
+    ``_coordinate_segments``), so the lengths of all rows sharing a
+    ``(frame, cell-pair)`` are **summed** into one total junction length before
+    signing. Otherwise each fragment would enter the landscape as its own
+    (short) sample. This is the headless analogue of the v1
+    ``find_shared_boundary`` / ``order_boundary_pixels`` join that produced one
+    length per junction.
+
+    All frames an edge exists are used (no ± window) — matching the reference,
+    which histograms the whole movie.
+
+    Columns (column-major, all equal length):
+
+    * ``t1_event_id`` — the event each sample belongs to.
+    * ``frame`` — the frame the sample is read from.
+    * ``signed_length`` — ``±length``, in µm when *pixel_size_um* is given else px.
+    * ``role`` — ``"losing"`` (negative) or ``"gaining"`` (positive).
+    * ``contact_type`` — the event's **transition pair** ``"<losing>→<gaining>"``
+      (e.g. ``"A-A→A-B"``), where each side is the contact label
+      (:func:`...contact_labels.contact_label_for`) of that junction's cell pair.
+      ``""`` when no *labels* map is given (the label-agnostic default). A single
+      per-event label is used (not per-side), so both the negative losing lobe and
+      the positive gaining lobe of an event share it and a grouped curve still
+      spans ``L = 0`` for the barrier.
+
+    *labels* maps ``cell_id -> label`` (an optional, caller-supplied per-cell
+    classification); a cell absent from it is ``"unclassified"``.
+
+    Returns empty (but typed) arrays when there are no events or no matching
+    edges; an event whose losing/gaining edges never appear in ``edges`` simply
+    contributes nothing.
+    """
+    edges = analysis.edges
+    events = analysis.t1_events
+    scale = float(pixel_size_um) if pixel_size_um else 1.0
+
+    e_frame = np.asarray(edges.get("frame", ()), dtype=np.int64)
+    e_a = np.asarray(edges.get("cell_a", ()), dtype=np.int64)
+    e_b = np.asarray(edges.get("cell_b", ()), dtype=np.int64)
+    e_len = np.asarray(edges.get("length", ()), dtype=float)
+
+    # Join fragments: sum every edge row sharing a (pair, frame) into one total
+    # junction length, so a boundary split across segments enters the landscape
+    # once at its real length rather than as several short samples.
+    total_length: dict[tuple[frozenset[int], int], float] = defaultdict(float)
+    for fr, ca, cb, ln in zip(e_frame, e_a, e_b, e_len):
+        total_length[(frozenset((int(ca), int(cb))), int(fr))] += float(ln)
+
+    # Unordered cell-pair -> [(frame, total_length), …], frame-sorted, so each
+    # event reads its losing and gaining edge in one lookup over all the frames
+    # they appear in.
+    pair_frames: dict[frozenset[int], list[tuple[int, float]]] = defaultdict(list)
+    for (pair, fr), total in total_length.items():
+        pair_frames[pair].append((fr, total))
+    for entries in pair_frames.values():
+        entries.sort()
+
+    ev_id = np.asarray(events.get("t1_event_id", ()), dtype=np.int64)
+    l_a = np.asarray(events.get("losing_cell_a", ()), dtype=np.int64)
+    l_b = np.asarray(events.get("losing_cell_b", ()), dtype=np.int64)
+    g_a = np.asarray(events.get("gaining_cell_a", ()), dtype=np.int64)
+    g_b = np.asarray(events.get("gaining_cell_b", ()), dtype=np.int64)
+
+    out_event: list[int] = []
+    out_frame: list[int] = []
+    out_signed: list[float] = []
+    out_role: list[str] = []
+    out_type: list[str] = []
+
+    for i in range(ev_id.size):
+        eid = int(ev_id[i])
+        # One transition label per event ("<losing>→<gaining>"), shared by both
+        # lobes so a grouped curve keeps its losing (−) and gaining (+) sides
+        # together and the barrier at L=0 stays defined.
+        if labels:
+            losing_type = contact_label_for(labels, int(l_a[i]), int(l_b[i]))
+            gaining_type = contact_label_for(labels, int(g_a[i]), int(g_b[i]))
+            contact_type = f"{losing_type}→{gaining_type}"
+        else:
+            contact_type = ""
+        for sign, role, pair in (
+            (-1.0, "losing", frozenset((int(l_a[i]), int(l_b[i])))),
+            (+1.0, "gaining", frozenset((int(g_a[i]), int(g_b[i])))),
+        ):
+            for frame, length in pair_frames.get(pair, ()):
+                out_event.append(eid)
+                out_frame.append(frame)
+                out_signed.append(sign * length * scale)
+                out_role.append(role)
+                out_type.append(contact_type)
+
+    return {
+        "t1_event_id": np.asarray(out_event, dtype=np.int64),
+        "frame": np.asarray(out_frame, dtype=np.int64),
+        "signed_length": np.asarray(out_signed, dtype=float),
+        "role": np.asarray(out_role, dtype=object),
+        "contact_type": np.asarray(out_type, dtype=object),
+    }

itasc/contact_analysis/curation.py

@@ -0,0 +1,185 @@
+"""The curation artifact — hand QC exclusions joined onto the measurement tables.
+
+A separate, git-versioned tidy table kept apart from the disposable measurement
+tables (the dividing line is who made the decisions in it). Schema, one row per
+exclusion::
+
+    experiment_id, position_id, frame, excluded, exclusion_reason
+
+``frame`` empty/NA means *the whole position* (every frame). At export the table
+is **left-joined** onto a measurement table by the natural keys the table already
+carries — a frame-level exclusion matches ``(experiment_id, position_id, frame)``;
+a position-level exclusion (``frame`` NA) matches ``(experiment_id, position_id)``
+— marking matched rows ``excluded = True`` and copying the reason. Rows with no
+entry default to kept; filter, don't delete. The measurement source is never
+mutated.
+
+This restores the curation that commit 95df159 removed, re-keyed on the natural
+keys (the old version, at rev 39d0df2, joined on a deterministic row ``id``).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+__all__ = [
+    "CURATION_COLUMNS",
+    "empty_curation",
+    "read_curation",
+    "write_curation",
+    "append_exclusion",
+    "remove_exclusion",
+    "apply_curation",
+    "filter_excluded",
+]
+
+#: The columns a curation CSV carries.
+CURATION_COLUMNS = (
+    "experiment_id",
+    "position_id",
+    "frame",
+    "excluded",
+    "exclusion_reason",
+)
+
+
+def read_curation(path: Path | str | None) -> pd.DataFrame | None:
+    """Read the curation CSV at *path*, or ``None`` when *path* is unset/absent.
+
+    A missing file is not an error: an uncurated series simply keeps every row.
+    """
+    if path is None:
+        return None
+    path = Path(path)
+    if not path.is_file():
+        return None
+    return pd.read_csv(path)
+
+
+def empty_curation() -> pd.DataFrame:
+    """An empty curation table with the canonical columns (object dtype).
+
+    Object columns keep an empty ``frame`` as ``NA`` (whole-position) rather than
+    coercing the column to a float that would render NaN on write.
+    """
+    return pd.DataFrame({col: pd.Series(dtype="object") for col in CURATION_COLUMNS})
+
+
+def write_curation(path: Path | str, curation: pd.DataFrame) -> None:
+    """Write *curation* to *path* as CSV (creating the parent dir), index-free."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    curation.to_csv(path, index=False)
+
+
+def append_exclusion(
+    curation: pd.DataFrame | None,
+    *,
+    experiment_id: str,
+    position_id: str,
+    frame: int | None,
+    reason: str,
+) -> pd.DataFrame:
+    """Return *curation* with one exclusion row added.
+
+    ``frame=None`` records a **whole-position** exclusion (stored as NA); a numeric
+    *frame* records a single-frame exclusion. Idempotent on the
+    ``(experiment_id, position_id, frame)`` key: an existing row with the same key
+    is replaced (its reason updated) rather than duplicated. The input is not
+    mutated.
+    """
+    base = empty_curation() if curation is None else curation
+    out = remove_exclusion(
+        base, experiment_id=experiment_id, position_id=position_id, frame=frame
+    )
+    new_row = {
+        "experiment_id": str(experiment_id),
+        "position_id": str(position_id),
+        "frame": pd.NA if frame is None else int(frame),
+        "excluded": True,
+        "exclusion_reason": str(reason),
+    }
+    return pd.concat([out, pd.DataFrame([new_row])], ignore_index=True)
+
+
+def remove_exclusion(
+    curation: pd.DataFrame | None,
+    *,
+    experiment_id: str,
+    position_id: str,
+    frame: int | None,
+) -> pd.DataFrame:
+    """Return *curation* without the row(s) matching the given key.
+
+    ``frame=None`` removes the **whole-position** row (``frame`` NA); a numeric
+    *frame* removes that single-frame row. A non-matching key is a no-op. The
+    input is not mutated.
+    """
+    if curation is None or len(curation) == 0:
+        return empty_curation()
+    out = curation.copy()
+    key = (out["experiment_id"].astype(str) == str(experiment_id)) & (
+        out["position_id"].astype(str) == str(position_id)
+    )
+    if frame is None:
+        key &= out["frame"].isna()
+    else:
+        frame_numeric = pd.to_numeric(out["frame"], errors="coerce")
+        key &= frame_numeric.notna() & (frame_numeric == float(frame))
+    return out.loc[~key].reset_index(drop=True)
+
+
+def apply_curation(
+    table: pd.DataFrame, curation: pd.DataFrame | None
+) -> pd.DataFrame:
+    """Return *table* with ``excluded`` / ``exclusion_reason`` columns marked.
+
+    A measurement row is marked excluded iff a curation entry matches it by either
+    ``(experiment_id, position_id, frame)`` (frame-level) or
+    ``(experiment_id, position_id)`` with the curation ``frame`` NA
+    (position-level). Keys are compared as strings (CSV round-trips ids as
+    strings); ``frame`` as an integer. Unmatched rows default to kept with an empty
+    reason. The input frame is not mutated.
+    """
+    out = table.copy()
+    out["excluded"] = False
+    out["exclusion_reason"] = ""
+    if curation is None or len(curation) == 0:
+        return out
+
+    exp = out["experiment_id"].astype(str)
+    pos = out["position_id"].astype(str)
+
+    for _, entry in curation.iterrows():
+        if not bool(entry.get("excluded", True)):
+            continue  # a future un-exclude override; ignored for now
+        key = (exp == str(entry["experiment_id"])) & (pos == str(entry["position_id"]))
+        frame = entry.get("frame")
+        if pd.notna(frame):
+            if "frame" not in out.columns:
+                continue  # a frame-level entry cannot match a frameless table
+            # An outer-merged table can carry NaN frames (whole-position rows);
+            # coerce instead of astype("int64") so those rows don't crash the cast.
+            frame_numeric = pd.to_numeric(out["frame"], errors="coerce")
+            key &= frame_numeric.notna() & (frame_numeric == float(frame))
+        out.loc[key, "excluded"] = True
+        out.loc[key, "exclusion_reason"] = str(entry.get("exclusion_reason", ""))
+
+    return out
+
+
+def filter_excluded(marked: pd.DataFrame) -> tuple[pd.DataFrame, int]:
+    """Drop the rows :func:`apply_curation` marked excluded.
+
+    Returns ``(kept, n_dropped)`` where *kept* has the two marker columns removed
+    (so it matches the source schema) and a reset index. A frame with no
+    ``excluded`` column is returned unchanged with ``n_dropped == 0``.
+    """
+    if "excluded" not in marked.columns:
+        return marked, 0
+    excluded = marked["excluded"].astype(bool)
+    n_dropped = int(excluded.sum())
+    drop_cols = [c for c in ("excluded", "exclusion_reason") if c in marked.columns]
+    kept = marked.loc[~excluded].drop(columns=drop_cols).reset_index(drop=True)
+    return kept, n_dropped