Skip to content

Object tables and review

See Reviewing and correcting results for the workflow.

patchworks.measure_objects(labels: Any, *, images: Mapping[str, Any] | None = None, axes: str | None = None, pixel_size: Mapping[str, float] | None = None, n_workers: int | None = None) -> dict[str, np.ndarray]

One row per object: size, centroid, bounding box, intensities.

Reads labels once, block by block (its own chunk grid), and never holds more than one block per worker in memory; objects spanning blocks are reassembled exactly.

Parameters:

Name Type Description Default
labels Array or array - like

Integer labels, 0 = background.

required
images mapping of str to array-like

Intensity images of the same shape, by name. Each adds mean_intensity_<name> and std_intensity_<name> columns -- and one more full read of that image, so only ask for what you use.

None
axes str

One letter per axis of labels (default "zyx"-style by ndim).

None
pixel_size mapping

Micrometres per voxel by axis letter. Adds area_um3 (or area_um2) and centroid_<axis>_um columns.

None
n_workers int

Blocks read in parallel (default: the CPUs this job was given).

None

Returns:

Type Description
dict of str to np.ndarray

Columns, all aligned: label, area_voxels, centroid_<axis>, bbox_min_<axis>, bbox_max_<axis> (inclusive, voxel indices), cov_<a><b> (the spread of the object's voxels, in voxels squared: its size and orientation, see :func:shape_columns), plus the optional ones above. Column names follow napari-chunked-regionprops, so either can read the other's tables.

Examples:

>>> lab = np.zeros((1, 4, 6), "int32"); lab[0, 1:3, 1:3] = 1; lab[0, 0, 5] = 7
>>> t = measure_objects(lab)
>>> t["label"].tolist(), t["area_voxels"].tolist()
([1, 7], [4, 1])
>>> t["bbox_max_x"].tolist(), t["centroid_y"].tolist()
([2, 5], [1.5, 0.0])
Source code in src/patchworks/_tables.py
def measure_objects(
    labels: Any,
    *,
    images: Mapping[str, Any] | None = None,
    axes: str | None = None,
    pixel_size: Mapping[str, float] | None = None,
    n_workers: int | None = None,
) -> dict[str, np.ndarray]:
    """One row per object: size, centroid, bounding box, intensities.

    Reads *labels* once, block by block (its own chunk grid), and never holds
    more than one block per worker in memory; objects spanning blocks are
    reassembled exactly.

    Parameters
    ----------
    labels : zarr.Array or array-like
        Integer labels, 0 = background.
    images : mapping of str to array-like, optional
        Intensity images of the same shape, by name. Each adds
        `mean_intensity_<name>` and `std_intensity_<name>` columns --
        and one more full read of that image, so only ask for what you use.
    axes : str, optional
        One letter per axis of *labels* (default `"zyx"`-style by ndim).
    pixel_size : mapping, optional
        Micrometres per voxel by axis letter. Adds `area_um3` (or
        `area_um2`) and `centroid_<axis>_um` columns.
    n_workers : int, optional
        Blocks read in parallel (default: the CPUs this job was given).

    Returns
    -------
    dict of str to np.ndarray
        Columns, all aligned: `label`, `area_voxels`,
        `centroid_<axis>`, `bbox_min_<axis>`, `bbox_max_<axis>`
        (inclusive, voxel indices), `cov_<a><b>` (the spread of the
        object's voxels, in voxels squared: its size and orientation, see
        :func:`shape_columns`), plus the optional ones above. Column
        names follow napari-chunked-regionprops, so either can read the
        other's tables.

    Examples
    --------
    >>> lab = np.zeros((1, 4, 6), "int32"); lab[0, 1:3, 1:3] = 1; lab[0, 0, 5] = 7
    >>> t = measure_objects(lab)
    >>> t["label"].tolist(), t["area_voxels"].tolist()
    ([1, 7], [4, 1])
    >>> t["bbox_max_x"].tolist(), t["centroid_y"].tolist()
    ([2, 5], [1.5, 0.0])
    """
    from .plugins.ome_zarr import _default_axes

    images = dict(images or {})
    ndim = len(labels.shape)
    axes = axes or _default_axes(ndim)
    chunk_shape = getattr(labels, "chunks", None)
    if not chunk_shape or not isinstance(chunk_shape[0], (int, np.integer)):
        chunk_shape = tuple(min(s, 256) for s in labels.shape)
    for name, img in images.items():
        if tuple(img.shape) != tuple(labels.shape):
            raise ValueError(
                f"image {name!r} has shape {tuple(img.shape)}, labels "
                f"{tuple(labels.shape)}: measure at the level the labels "
                "were segmented at"
            )
    img_list = list(images.values())
    chunk_shape = _measure_block_shape(labels, chunk_shape, img_list)
    blocks = list(chunk_slices(labels.shape, chunk_shape))
    nw = n_workers or cpu_allocation()
    # Per worker: the chunks decompressed to read its block (whole image
    # chunks, however deep), the block itself, and the slabs' sums.
    block_nbytes = int(np.prod(chunk_shape)) * (
        np.dtype(labels.dtype).itemsize
        + sum(np.dtype(img.dtype).itemsize for img in img_list)
    )
    read_nbytes = sum(_read_nbytes(a, chunk_shape) for a in (labels, *img_list))
    nw = max(
        1,
        min(
            nw,
            safe_worker_count(
                read_nbytes + block_nbytes + TILE_PARTIAL_BLOCK * 100,
                fn_overhead=1,
            ),
        ),
    )
    # The work holds the GIL, so threads barely help: processes where they
    # can share the arrays by forking (zarr resets its IO thread in a fork).
    use_processes = (
        nw > 1
        and len(blocks) > 1
        and not isinstance(labels, np.ndarray)
        and "fork" in mp.get_all_start_methods()
        and sys.platform.startswith("linux")
    )
    logger.info(
        "measuring %d block(s) of %s with %d %s (~%s each)",
        len(blocks),
        "x".join(map(str, chunk_shape)),
        nw,
        "process(es)" if use_processes else "thread(s)",
        f"{(read_nbytes + block_nbytes) / 1024**3:.1f} GB",
    )

    started = last = _time.monotonic()
    parts = []
    key = id(labels) ^ int(_time.monotonic_ns())
    _MEASURING[key] = (labels, img_list)
    try:
        with warnings.catch_warnings():
            # "multi-threaded, use of fork() may lead to deadlocks", once per
            # worker as it starts: the children only read arrays, through
            # zarr's IO thread, which zarr resets in a fork.
            warnings.simplefilter("ignore", DeprecationWarning)
            ex = (
                ProcessPoolExecutor(
                    max_workers=nw,
                    mp_context=mp.get_context("fork"),
                    initializer=_measure_worker_init,
                )
                if use_processes
                else ThreadPoolExecutor(max_workers=nw)
            )
            with ex:
                futures = [ex.submit(_measure_block, key, sl) for sl in blocks]
                for done, fut in enumerate(as_completed(futures), start=1):
                    part = fut.result()
                    if part is not None:
                        parts.append(part)
                    now = _time.monotonic()
                    if now - last >= _PROGRESS_INTERVAL_S or done == len(
                        blocks
                    ):
                        log_progress(
                            "measure_objects", done, len(blocks), started
                        )
                        last = now
    finally:
        _MEASURING.pop(key, None)

    return table_columns(
        _merge(parts, len(img_list)) if parts else None,
        axes,
        pixel_size,
        list(images),
    )

patchworks.compute_table(store: Union[str, Path], name: str, *, channels: Sequence[int] | None = None, n_workers: int | None = None) -> dict[str, np.ndarray]

Measure labels/<name> of store and store the result as its table.

Parameters:

Name Type Description Default
store str or Path

OME-ZARR image store holding labels/<name>.

required
name str

Label image name.

required
channels sequence of int

Image channels to add mean/std intensity columns for. Read at the pyramid level the labels were segmented at (from their provenance).

None
n_workers int

Parallel block reads.

None

Returns:

Type Description
dict

The columns written.

Source code in src/patchworks/_tables.py
def compute_table(
    store: Union[str, Path],
    name: str,
    *,
    channels: Sequence[int] | None = None,
    n_workers: int | None = None,
) -> dict[str, np.ndarray]:
    """Measure `labels/<name>` of *store* and store the result as its table.

    Parameters
    ----------
    store : str or Path
        OME-ZARR image store holding `labels/<name>`.
    name : str
        Label image name.
    channels : sequence of int, optional
        Image channels to add mean/std intensity columns for. Read at the
        pyramid level the labels were segmented at (from their provenance).
    n_workers : int, optional
        Parallel block reads.

    Returns
    -------
    dict
        The columns written.
    """
    from ._io import load_ome_zarr
    from .plugins.ome_zarr import read_pixel_size

    path = _label_group(store, name)
    grp = zarr.open_group(path, mode="r")
    arr = _level0(grp)
    axes = _spatial_axes(grp, arr.ndim)
    prov = dict(grp.attrs).get(PROVENANCE_KEY) or {}
    settings = prov.get("settings") or {}
    level = int(settings.get("level") or 0)
    images = {}
    for c in channels or ():
        images[f"ch{c}"] = load_ome_zarr(store, channel=int(c), level=level)
    logger.info(
        "measuring labels/%s (%s, %s channel(s))",
        name,
        "x".join(map(str, arr.shape)),
        len(images),
    )
    cols = measure_objects(
        arr,
        images=images,
        axes=axes,
        pixel_size=read_pixel_size(path),
        n_workers=n_workers,
    )
    tile = settings.get("tile_shape")
    write_table(
        path,
        cols,
        attrs={
            "axes": axes,
            "pixel_size": read_pixel_size(path),
            "tile_shape": list(tile) if tile else None,
            "channels": list(images),
        },
    )
    return cols

patchworks.relate_tables(store: Union[str, Path], child: str, parent: str, *, matches: Mapping[int, Mapping[str, float]] | None = None, max_distance_um: float | None = None, n_workers: int | None = None) -> dict[int, dict[str, float]]

Add child's parent columns: which parent object each one is in.

Adds <parent>_id (0 = in none), <parent>_overlap (fraction of the child inside it) and <parent>_overlap_voxels to the child's table, computing the child's table first if it has none.

With max_distance_um, a child touching no parent gets the nearest one within that distance instead (a cilium beside its cell rather than on it), and a <parent>_distance_um column: 0 when overlapping, the gap for those assigned by distance, NaN for none within reach.

Parameters:

Name Type Description Default
store str or Path

OME-ZARR store holding both label images.

required
child str

Label image names, e.g. "cilia_labels" in "cyto_labels".

required
parent str

Label image names, e.g. "cilia_labels" in "cyto_labels".

required
matches mapping

:func:~patchworks.label_relations output for this pair, when already computed -- otherwise it is computed here (a read of both).

None
max_distance_um float

Assign a child touching no parent to the nearest one within this distance (µm); None (default) leaves it in none.

None
n_workers int

Parallel chunk reads.

None

Returns:

Type Description
dict

The matches used.

Source code in src/patchworks/_tables.py
def relate_tables(
    store: Union[str, Path],
    child: str,
    parent: str,
    *,
    matches: Mapping[int, Mapping[str, float]] | None = None,
    max_distance_um: float | None = None,
    n_workers: int | None = None,
) -> dict[int, dict[str, float]]:
    """Add *child*'s parent columns: which *parent* object each one is in.

    Adds `<parent>_id` (0 = in none), `<parent>_overlap` (fraction of
    the child inside it) and `<parent>_overlap_voxels` to the child's
    table, computing the child's table first if it has none.

    With *max_distance_um*, a child touching no parent gets the **nearest**
    one within that distance instead (a cilium beside its cell rather than
    on it), and a `<parent>_distance_um` column: 0 when overlapping, the
    gap for those assigned by distance, NaN for none within reach.

    Parameters
    ----------
    store : str or Path
        OME-ZARR store holding both label images.
    child, parent : str
        Label image names, e.g. `"cilia_labels"` in `"cyto_labels"`.
    matches : mapping, optional
        :func:`~patchworks.label_relations` output for this pair, when
        already computed -- otherwise it is computed here (a read of both).
    max_distance_um : float, optional
        Assign a child touching no parent to the nearest one within this
        distance (µm); None (default) leaves it in none.
    n_workers : int, optional
        Parallel chunk reads.

    Returns
    -------
    dict
        The matches used.
    """
    import dask.array as da

    from ._relations import label_relations

    cpath, ppath = _label_group(store, child), _label_group(store, parent)
    if not has_table(cpath) or is_stale(cpath):
        compute_table(store, child, n_workers=n_workers)
    if matches is None:
        a = da.from_zarr(_level0(zarr.open_group(cpath, mode="r")))
        b = da.from_zarr(_level0(zarr.open_group(ppath, mode="r")))
        a, b = align_chunks(a, b)
        matches = label_relations(a, b, n_workers=n_workers)
    labels = zarr.open_group(f"{cpath}/{TABLE_GROUP}", mode="r")["label"][...]
    pid = np.zeros(labels.size, np.int64)
    frac = np.zeros(labels.size)
    vox = np.zeros(labels.size, np.int64)
    for i, lab in enumerate(labels.tolist()):
        m = matches.get(lab)
        if m is not None:
            pid[i], frac[i], vox[i] = (
                m["match"],
                m["overlap_fraction"],
                m["overlap_voxels"],
            )
    cols = {
        f"{parent}_id": pid,
        f"{parent}_overlap": frac,
        f"{parent}_overlap_voxels": vox,
    }
    if max_distance_um is not None:
        dist = np.where(pid != 0, 0.0, np.nan)
        orphans = np.flatnonzero(pid == 0)
        found = nearest_parents(
            store,
            child,
            parent,
            labels[orphans],
            max_distance_um=float(max_distance_um),
            n_workers=n_workers,
        )
        for i, lab in zip(orphans, labels[orphans].tolist()):
            if lab in found:
                pid[i], dist[i] = found[lab]
        cols[f"{parent}_distance_um"] = dist
    add_columns(cpath, cols)
    # Which parents these columns describe, on the id column itself, so
    # concurrent relations of one child do not overwrite each other.
    from ._io import open_group_any

    id_col = zarr.open_group(cpath, mode="r+")[TABLE_GROUP][f"{parent}_id"]
    id_col.attrs[RELATION_KEY] = {
        "parent_labels": label_fingerprint(
            open_group_any(_label_group(store, parent))
        ),
        "max_distance_um": max_distance_um,
    }
    return dict(matches)

patchworks._tables.nearest_parents(store: Union[str, Path], child: str, parent: str, labels: Sequence[int], *, max_distance_um: float, n_workers: int | None = None) -> dict[int, tuple[int, float]]

The nearest parent object to each of labels, within a distance.

Exact surface-to-surface distance in µm (anisotropic voxels included), from the voxels around each object only: its bounding box grown by the distance. Meant for the few objects touching no parent, not all.

Parameters:

Name Type Description Default
store str or Path

The OME-Zarr image.

required
child str

The label image labels belong to; it needs its table (the bounding boxes).

required
parent str

The label image to search.

required
labels sequence of int

The child objects to place.

required
max_distance_um float

The search distance, in µm.

required
n_workers int

Objects searched at once.

None

Returns:

Type Description
dict

{label: (parent_id, distance_um)} for those with a parent within reach.

Source code in src/patchworks/_tables.py
def nearest_parents(
    store: Union[str, Path],
    child: str,
    parent: str,
    labels: Sequence[int],
    *,
    max_distance_um: float,
    n_workers: int | None = None,
) -> dict[int, tuple[int, float]]:
    """The nearest *parent* object to each of *labels*, within a distance.

    Exact surface-to-surface distance in µm (anisotropic voxels included),
    from the voxels around each object only: its bounding box grown by the
    distance. Meant for the few objects touching no parent, not all.

    Parameters
    ----------
    store : str or Path
        The OME-Zarr image.
    child : str
        The label image *labels* belong to; it needs its table (the bounding
        boxes).
    parent : str
        The label image to search.
    labels : sequence of int
        The child objects to place.
    max_distance_um : float
        The search distance, in µm.
    n_workers : int, optional
        Objects searched at once.

    Returns
    -------
    dict
        `{label: (parent_id, distance_um)}` for those with a parent within
        reach.
    """
    from ._io import open_group_any
    from .plugins.ome_zarr import read_pixel_size

    cpath, ppath = _label_group(store, child), _label_group(store, parent)
    cgroup = open_group_any(cpath)
    carr, parr = _level0(cgroup), _level0(open_group_any(ppath))
    axes = _spatial_axes(cgroup, carr.ndim)
    size = read_pixel_size(cpath)
    spacing = np.array([float(size.get(ax, 1.0)) for ax in axes])
    margin = np.ceil(max_distance_um / spacing).astype(int)
    table = zarr.open_group(f"{cpath}/{TABLE_GROUP}", mode="r")
    all_labels = table["label"][...]
    lo = np.stack([np.asarray(table[f"bbox_min_{ax}"][...]) for ax in axes], 1)
    hi = np.stack([np.asarray(table[f"bbox_max_{ax}"][...]) for ax in axes], 1)
    where = {int(v): i for i, v in enumerate(all_labels)}

    def one(label: int):
        """The nearest parent of one child object.

        Parameters
        ----------
        label : int
            The child object.

        Returns
        -------
        tuple or None
            `(label, (parent_id, distance_um))`, or None when there is none
            within reach.
        """
        i = where.get(int(label))
        if i is None:
            return None
        a = np.maximum(lo[i] - margin, 0)
        b = np.minimum(hi[i] + margin + 1, carr.shape)
        sl = tuple(slice(int(x), int(y)) for x, y in zip(a, b))
        mask = np.asarray(carr[sl]) == label
        region = np.asarray(parr[sl])
        if not region.any() or not mask.any():
            return None
        dist, idx = ndi.distance_transform_edt(
            region == 0, sampling=spacing, return_indices=True
        )
        pos = np.argmin(np.where(mask, dist, np.inf))
        d = float(dist.flat[pos])
        if d > max_distance_um:
            return None
        nearest = tuple(ix.flat[pos] for ix in idx)
        return int(label), (int(region[nearest]), d)

    with ThreadPoolExecutor(max_workers=n_workers or cpu_allocation()) as ex:
        return dict(r for r in ex.map(one, labels) if r is not None)

patchworks._tables.shape_columns(df: 'pd.DataFrame', axes: str, pixel_size: Mapping[str, float] | None) -> dict[str, np.ndarray]

Length, elongation and main axis of each object, from its moments.

length is the extent along the main axis of a uniform rod with the same spread (sqrt(12 * largest variance)): exact for a straight rod, shorter than the path of a curved one. elongation is the ratio of the two largest spreads (1: round, large: rod-like). axis_<a> is the main axis as a unit vector (sign fixed so its first non-zero component is positive).

Parameters:

Name Type Description Default
df DataFrame

The table, with its cov_<a><b> columns.

required
axes str

The spatial axes' names.

required
pixel_size mapping or None

µm per voxel by axis: lengths in µm when given, else voxels.

required

Returns:

Type Description
dict of np.ndarray

length_um (or length_voxels), elongation and axis_<a>; empty without the covariance columns.

Examples:

>>> import pandas as pd
>>> rod = pd.DataFrame({"cov_zz": [0.0], "cov_yy": [0.0], "cov_xx": [12.0],
...     "cov_zy": [0.0], "cov_zx": [0.0], "cov_yx": [0.0]})
>>> cols = shape_columns(rod, "zyx", {"z": 1, "y": 1, "x": 0.5})
>>> round(float(cols["length_um"][0]), 3), float(cols["axis_x"][0])
(6.0, 1.0)
Source code in src/patchworks/_tables.py
def shape_columns(
    df: "pd.DataFrame", axes: str, pixel_size: Mapping[str, float] | None
) -> dict[str, np.ndarray]:
    """Length, elongation and main axis of each object, from its moments.

    `length` is the extent along the main axis of a uniform rod with the
    same spread (`sqrt(12 * largest variance)`): exact for a straight
    rod, shorter than the path of a curved one. `elongation` is the ratio
    of the two largest spreads (1: round, large: rod-like). `axis_<a>`
    is the main axis as a unit vector (sign fixed so its first non-zero
    component is positive).

    Parameters
    ----------
    df : pandas.DataFrame
        The table, with its `cov_<a><b>` columns.
    axes : str
        The spatial axes' names.
    pixel_size : mapping or None
        µm per voxel by axis: lengths in µm when given, else voxels.

    Returns
    -------
    dict of np.ndarray
        `length_um` (or `length_voxels`), `elongation` and
        `axis_<a>`; empty without the covariance columns.

    Examples
    --------
    >>> import pandas as pd
    >>> rod = pd.DataFrame({"cov_zz": [0.0], "cov_yy": [0.0], "cov_xx": [12.0],
    ...     "cov_zy": [0.0], "cov_zx": [0.0], "cov_yx": [0.0]})
    >>> cols = shape_columns(rod, "zyx", {"z": 1, "y": 1, "x": 0.5})
    >>> round(float(cols["length_um"][0]), 3), float(cols["axis_x"][0])
    (6.0, 1.0)
    """
    cov = physical_cov(df, axes, pixel_size)
    unit = "um" if pixel_size else "voxels"
    if not len(df) or np.isnan(cov).all():
        return {}
    w, v = np.linalg.eigh(cov)  # ascending
    w = np.clip(w, 0, None)
    main = v[:, :, -1]
    first = np.argmax(np.abs(main) > 1e-9, axis=1)
    sign = np.sign(main[np.arange(len(main)), first])
    main = main * np.where(sign == 0, 1, sign)[:, None]
    out = {f"length_{unit}": np.sqrt(12 * w[:, -1])}
    with np.errstate(divide="ignore", invalid="ignore"):
        out["elongation"] = (
            np.sqrt(w[:, -1] / w[:, -2]) if w.shape[1] > 1 else np.ones(len(w))
        )
    for k, ax in enumerate(axes):
        out[f"axis_{ax}"] = main[:, k]
    return out

patchworks.read_table(group: Union[str, Path], *, check: bool = True) -> 'pd.DataFrame'

The table of label group group as a DataFrame indexed by label.

Parameters:

Name Type Description Default
group str or Path

The label group.

required
check bool

Refuse a table computed from other labels (default True).

True

Returns:

Type Description
DataFrame

Examples:

>>> read_table("scan.zarr/labels/cilia_labels")
Source code in src/patchworks/_tables.py
def read_table(
    group: Union[str, Path], *, check: bool = True
) -> "pd.DataFrame":
    """The table of label group *group* as a DataFrame indexed by `label`.

    Parameters
    ----------
    group : str or Path
        The label group.
    check : bool, optional
        Refuse a table computed from other labels (default True).

    Returns
    -------
    pandas.DataFrame

    Examples
    --------
    >>> read_table("scan.zarr/labels/cilia_labels")  # doctest: +SKIP
    """
    import pandas as pd

    cols = read_columns(group, check=check)
    return pd.DataFrame(cols).set_index("label")

patchworks.Review

The objects of one store, their flags and the reviewer's decisions.

Parameters:

Name Type Description Default
store str or Path

OME-ZARR image store whose label images carry tables.

required
expect mapping

Expected child counts per parent object: {"cyto_labels": {"nuclei_labels": (1, 1), "cilia_labels": (0, 2)}} -- a cell with no nucleus or 3 cilia is then flagged. Falls back to what the tables' metadata recorded (the workflow's review:).

None
min_overlap float or mapping

A child less than this fraction inside its parent is flagged (default 0.5; per {child: {parent: value}} if a mapping).

None
seam_tolerance int

Voxels of slack when matching two objects meeting at a tile seam.

1
names iterable of str

Only these label images (default: every one with a table).

None
position mapping

Classify objects by where they sit in their parent: {"cilia_labels": {"parent": "cyto_labels", "apical": "nuclei_labels"}} -- see :meth:positions. Falls back to the store's recorded rules.

None

Examples:

>>> rv = Review("scan.zarr", expect={"cells": {"nuclei": (1, 1)}})
>>> rv.flags("nuclei")[:3]
>>> rv.decide("nuclei", 17, "wrong")
>>> rv.summary("nuclei")
Source code in src/patchworks/_review.py
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
class Review:
    """The objects of one store, their flags and the reviewer's decisions.

    Parameters
    ----------
    store : str or Path
        OME-ZARR image store whose label images carry tables.
    expect : mapping, optional
        Expected child counts per parent object:
        `{"cyto_labels": {"nuclei_labels": (1, 1), "cilia_labels": (0, 2)}}`
        -- a cell with no nucleus or 3 cilia is then flagged. Falls back to
        what the tables' metadata recorded (the workflow's `review:`).
    min_overlap : float or mapping, optional
        A child less than this fraction inside its parent is flagged
        (default 0.5; per `{child: {parent: value}}` if a mapping).
    seam_tolerance : int, optional
        Voxels of slack when matching two objects meeting at a tile seam.
    names : iterable of str, optional
        Only these label images (default: every one with a table).
    position : mapping, optional
        Classify objects by where they sit in their parent:
        `{"cilia_labels": {"parent": "cyto_labels", "apical":
        "nuclei_labels"}}` -- see :meth:`positions`. Falls back to the
        store's recorded rules.

    Examples
    --------
    >>> rv = Review("scan.zarr", expect={"cells": {"nuclei": (1, 1)}})  # doctest: +SKIP
    >>> rv.flags("nuclei")[:3]  # doctest: +SKIP
    >>> rv.decide("nuclei", 17, "wrong")  # doctest: +SKIP
    >>> rv.summary("nuclei")  # doctest: +SKIP
    """

    def __init__(
        self,
        store: Union[str, Path],
        *,
        expect: Mapping[str, Mapping[str, Iterable[int]]] | None = None,
        min_overlap: float | Mapping[str, Mapping[str, float]] | None = None,
        seam_tolerance: int = 1,
        names: Iterable[str] | None = None,
        position: Mapping[str, Mapping[str, Any]] | None = None,
    ) -> None:
        """Load the tables, the rules and the decisions; see the class docstring
        for the parameters.
        """
        self.store = str(store).rstrip("/")
        self.seam_tolerance = int(seam_tolerance)
        self.names: list[str] = []
        self.meta: dict[str, dict[str, Any]] = {}
        self.tables: dict[str, pd.DataFrame] = {}
        self.stale: list[str] = []
        rules = read_rules(self.store)
        wanted = None if names is None else set(names)
        if wanted is not None:
            # A position rule also needs its parent's and its reference's tables.
            for child, rule in {
                **(rules.get("position") or {}),
                **(position or {}),
            }.items():
                if child in wanted and rule:
                    spec = str(rule.get("apical", ""))
                    wanted |= {
                        str(rule.get("parent")),
                        spec.removeprefix("towards:"),
                    } - {""}
        for name in table_names(self.store):
            if wanted is not None and name not in wanted:
                continue
            group = _label_group(self.store, name)
            if not has_table(group):
                continue
            if is_stale(group):
                self.stale.append(name)
                continue
            self.names.append(name)
            self.meta[name] = table_meta(group)
            self.tables[name] = read_table(group, check=False)
        if self.stale:
            logger.warning(
                "tables of %s were computed from older labels and are "
                "ignored; recompute them (patchworks tables %s)",
                ", ".join(self.stale),
                self.store,
            )
        # A table's parents are the label images it has relation columns for.
        self.parents = {
            n: [
                p
                for p in self.names
                if p != n
                and f"{p}_id" in self.tables[n]
                and f"{p}_overlap" in self.tables[n]
            ]
            for n in self.names
        }
        self.children = {
            n: [c for c in self.names if n in self.parents[c]]
            for n in self.names
        }
        self.expect: dict[str, dict[str, tuple[int, int]]] = {}
        for n, rules_n in (rules.get("expect") or {}).items():
            for child, rng in rules_n.items():
                self.expect.setdefault(n, {})[child] = _range(rng)
        self._recorded_overlap = rules.get("min_overlap")
        for n, rules in (expect or {}).items():
            for child, rng in rules.items():
                self.expect.setdefault(n, {})[child] = _range(rng)
        self._min_overlap = min_overlap
        self.position: dict[str, dict[str, Any]] = {
            k: dict(v) for k, v in (rules.get("position") or {}).items()
        }
        for child, rule in (position or {}).items():
            self.position[child] = dict(rule)
        for child, rule in list(self.position.items()):
            if child not in self.tables or "parent" not in rule:
                # A rule for a label image left out on purpose (names=, as
                # each relate job loads just its pair) is no news.
                if "parent" not in rule or wanted is None or child in wanted:
                    logger.warning(
                        "position rule for %s ignored: %s", child, rule
                    )
                del self.position[child]
        self.decisions: dict[str, dict[int, dict[str, Any]]] = {}
        self.seed: dict[str, int] = {}
        for n in self.names:
            self._load_decisions(n)
        self._cache: dict[str, pd.DataFrame] = {}
        self._flag_cache: dict[str, tuple[pd.DataFrame, pd.DataFrame]] = {}

    # -- decisions ---------------------------------------------------------

    def _table_group(self, name: str, mode: str = "r"):
        """The table group of label image *name*.

        Parameters
        ----------
        name : str
            The label image.
        mode : str, optional
            zarr's mode (default `"r"`).

        Returns
        -------
        zarr.Group
        """
        from ._io import open_group_any

        return open_group_any(
            f"{_label_group(self.store, name)}/{TABLE_GROUP}", mode=mode
        )

    def _load_decisions(self, name: str) -> None:
        """Load the decisions saved for *name*, unless made on other labels.

        Parameters
        ----------
        name : str
            The label image.
        """
        log = dict(self._table_group(name).attrs.get(REVIEW_KEY) or {})
        fingerprint = label_fingerprint(
            open_group_any(_label_group(self.store, name))
        )
        decisions = log.get("decisions") or {}
        if decisions and log.get("labels") != fingerprint:
            logger.warning(
                "%s: the review decisions were made on older labels; "
                "starting a fresh review",
                name,
            )
            decisions = {}
        self.decisions[name] = {int(k): v for k, v in decisions.items()}
        self.seed[name] = int(log.get("seed", 0))

    def _save(self, name: str) -> None:
        """Save the decisions about *name* into its table's attrs.

        Parameters
        ----------
        name : str
            The label image.

        Raises
        ------
        PermissionError
            When the store cannot be written (read-only, or a .zip bundle).
        """
        try:
            group = self._table_group(name, mode="r+")
        except Exception as exc:
            raise PermissionError(
                f"cannot save review decisions into {self.store} (read-only, "
                "or a .zip bundle?): review a writable copy of the store"
            ) from exc
        group.attrs[REVIEW_KEY] = {
            "updated": _dt.datetime.now(_dt.timezone.utc).isoformat(),
            "labels": label_fingerprint(
                open_group_any(_label_group(self.store, name))
            ),
            "seed": self.seed[name],
            "decisions": {
                str(k): v for k, v in sorted(self.decisions[name].items())
            },
        }
        self._cache.clear()
        self._flag_cache.clear()

    def decide(
        self,
        name: str,
        label: int,
        action: str,
        *,
        parent: str | None = None,
        parent_id: int | None = None,
        into: int | None = None,
        position: str | None = None,
        queue: str = "flagged",
        reviewer: str | None = None,
    ) -> None:
        """Record a decision about object *label* of label image *name*.

        Parameters
        ----------
        name : str
            The label image.
        label : int
            The object.
        action : {"ok", "wrong", "parent", "merge", "position"}
            `ok`: correct as it is. `wrong`: not a real object (dropped
            from the corrected tables). `parent`: belongs to *parent_id*
            of label image *parent* (0 = to none). `merge`: the same
            object as *into*. `position`: its position class is
            *position* (one of :data:`POSITIONS`), whatever was computed.
        parent : str, optional
            The parent label image, for `parent`.
        parent_id : int, optional
            The parent object it belongs to, for `parent` (0: none).
        into : int, optional
            The object it is merged into, for `merge`.
        position : str, optional
            Its position class, for `position`.
        queue : str, optional
            The queue it was reviewed from; `"random"` decisions feed the
            error estimate.
        reviewer : str, optional
            Who decided, recorded with the decision.

        Raises
        ------
        KeyError
            When *name* has no table or no such object.
        ValueError
            For an unknown action, or one missing its argument.
        """
        if name not in self.tables:
            raise KeyError(f"no table for labels/{name}")
        label = int(label)
        if label not in self.tables[name].index:
            raise KeyError(f"{name} has no object {label}")
        if action not in ACTIONS:
            raise ValueError(f"action must be one of {ACTIONS}, got {action!r}")
        entry: dict[str, Any] = {
            "action": action,
            "queue": queue,
            "time": _dt.datetime.now(_dt.timezone.utc).isoformat(
                timespec="seconds"
            ),
        }
        if reviewer:
            entry["by"] = reviewer
        if action == "parent":
            if parent not in self.parents[name]:
                raise ValueError(
                    f"{name} has no parent image {parent!r} "
                    f"(has {self.parents[name]})"
                )
            pid = int(parent_id or 0)
            if pid and pid not in self.tables[parent].index:
                raise KeyError(f"{parent} has no object {pid}")
            entry.update(parent=parent, parent_id=pid)
            previous = self.decisions[name].get(label, {})
            if previous.get("action") == "parent":
                entry["parents"] = {**previous.get("parents", {}), parent: pid}
            else:
                entry["parents"] = {parent: pid}
        elif action == "position":
            if name not in self.position:
                raise ValueError(f"{name} has no position rule")
            if position not in POSITIONS:
                raise ValueError(f"position must be one of {POSITIONS}")
            entry["position"] = position
        elif action == "merge":
            into = int(into or 0)
            if into == label or into not in self.tables[name].index:
                raise KeyError(f"cannot merge {name} {label} into {into}")
            entry["into"] = into
        self.decisions[name][label] = entry
        self._save(name)

    def relations(self) -> list[tuple[str, str]]:
        """Every (child, parent) pair the tables relate."""
        return [(c, p) for c in self.names for p in self.parents[c]]

    def undo(self, name: str, label: int) -> None:
        """Forget the decision about *label* (it goes back to unreviewed).

        Parameters
        ----------
        name : str
            The label image.
        label : int
            The object.
        """
        if self.decisions[name].pop(int(label), None) is not None:
            self._save(name)

    # -- the corrected view --------------------------------------------------

    def roots(self, name: str) -> dict[int, int]:
        """Where each decided object ends up.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        dict of int to int
                0 if rejected, the object it was merged into (followed to the
            end)
            otherwise. Undecided objects are absent (they map to themselves).
        """
        dec = self.decisions[name]
        out: dict[int, int] = {}
        for label in dec:
            seen, cur = {label}, label
            while True:
                d = dec.get(cur)
                if d is None or d["action"] in ("ok", "parent", "position"):
                    break
                if d["action"] == "wrong":
                    cur = 0
                    break
                cur = int(d["into"])
                if cur in seen:  # a merge cycle: keep the smallest id
                    cur = min(seen)
                    break
                seen.add(cur)
            if cur != label:
                out[label] = cur
        return out

    def _corrected(self, name: str) -> "pd.DataFrame":
        """*name*'s rows with the decisions applied, before derived columns.

        Derived columns (counts, shape, position) need other tables' rows,
        never their derived columns, so nothing here recurses.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        pandas.DataFrame
        """
        key = ("rows", name)
        if key in self._cache:
            return self._cache[key]
        import pandas as pd

        df = self.tables[name].copy()
        dec = self.decisions[name]
        for p in self.parents[name]:
            col = f"{p}_id"
            for label, d in dec.items():
                if d["action"] == "parent" and p in d.get("parents", {}):
                    df.loc[label, col] = d["parents"][p]
                    df.loc[label, f"{p}_overlap"] = np.nan
            proots = self.roots(p)
            if proots:
                df[col] = _remap(df[col].to_numpy(dtype=np.int64), proots)
        roots = self.roots(name)
        if roots:
            # A new array: a Series made from a RangeIndex shares its cached
            # values under pandas 3, and updating it in place rewrote them --
            # the merge was compared with itself and never applied.
            target = pd.Series(
                [roots.get(int(i), int(i)) for i in df.index],
                index=df.index,
                dtype=np.int64,
            )
            df = df[target != 0]
            target = target[target != 0]
            if (target != target.index).any():
                df = _combine(df, target)
        qc = pd.Series("", index=df.index)
        for label, d in dec.items():
            if label in qc.index:
                qc[label] = "ok" if d["action"] == "ok" else "fixed"
        for label, root in roots.items():
            if root and root in qc.index:
                qc[root] = "fixed"
        df["qc"] = qc
        self._cache[key] = df
        return df

    def hover_features(self, name: str) -> "pd.DataFrame":
        """Per-label features for napari's status bar.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        pandas.DataFrame
            Each object's parent(s), number of children, position and review
            status, with an `index` column of labels.
        """
        eff = self.effective(name)
        cols = [f"{p}_id" for p in self.parents[name]]
        cols += [f"n_{c}" for c in self.children[name]]
        cols += [c for c in ("position", "qc") if c in eff]
        return (
            eff[[c for c in cols if c in eff]]
            .reset_index()
            .rename(columns={eff.index.name or "label": "index"})
        )

    def effective(self, name: str) -> "pd.DataFrame":
        """*name*'s table with every decision applied.

        Rejected objects are dropped; merged objects become one row (sizes
        added, centroids, spreads and intensities combined exactly, boxes
        joined); parent columns follow reassignments and the parents' own
        merges; `qc` says `ok`, `fixed` or `""` (not reviewed).
        Derived columns: `n_<child>` (children counted), `length_um`,
        `elongation`, `axis_<a>` (shape, see
        :func:`~patchworks._tables.shape_columns`) and, for label images
        with a position rule, `position` and its measures (see
        :meth:`positions`).

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        pandas.DataFrame
            Indexed by label; cached until the next decision.
        """
        if name in self._cache:
            return self._cache[name]
        from ._tables import shape_columns

        df = self._corrected(name).copy()
        for child in self.children[name]:
            ce = self._corrected(child)
            counts = ce[f"{name}_id"].value_counts()
            df[f"n_{child}"] = (
                counts.reindex(df.index).fillna(0).astype(np.int64)
            )
        meta = self.meta[name]
        for col, values in shape_columns(
            df, meta.get("axes") or "", meta.get("pixel_size")
        ).items():
            df[col] = values
        if name in self.position:
            for col, values in self.positions(name, df).items():
                df[col] = values
        for child in self.children[name]:
            if (
                child in self.position
                and self.position[child]["parent"] == name
            ):
                pos = self.effective(child)
                table = (
                    pos[pos[f"{name}_id"] != 0]
                    .groupby([f"{name}_id", "position"])
                    .size()
                    .unstack(fill_value=0)
                )
                for cls in POSITIONS:
                    counts = table[cls] if cls in table else None
                    df[f"n_{child}_{cls}"] = (
                        counts.reindex(df.index).fillna(0).astype(np.int64)
                        if counts is not None
                        else 0
                    )
        self._cache[name] = df
        return df

    def positions(
        self, name: str, df: "pd.DataFrame | None" = None
    ) -> dict[str, Any]:
        """Where each object of *name* sits in its parent.

        Per parent object, an apical axis: a fixed direction (`"+z"`:
        apical is up the z axis), or pointing away from the parent's
        children of another label image (`"nuclei_labels"`: away from
        the nucleus, for epithelia whose nuclei sit basally), or towards
        them (`"towards:<name>"`). Each object's **base** is its end
        nearer the parent's centre (a cilium grows out from its base).

        The class is the parent surface the base is nearest to -- top
        (`apical`), bottom (`basal`) or side wall (`lateral`) --
        each depth measured relative to the parent's size in that
        direction; `central` when deeper than `central_depth` (default
        0.5, i.e. half-way) from all three. The parent's shape is taken
        from its moments (an equivalent cylinder), so this is a
        classification, not a surface distance.

        Parameters
        ----------
        name : str
            A label image with a position rule.
        df : pandas.DataFrame, optional
            Its rows, when already corrected (default: :meth:`_corrected`).

        Returns
        -------
        dict
            Columns `position` (the class; `outside` with no
            parent; `unknown` when the axis cannot be told, e.g. no nucleus),
            `position_axial` (-1 basal .. +1 apical, in half-heights of the
            parent along its axis), `position_radial` (0 on the axis .. 1 at
            the side) and `angle_to_axis_deg` (0: along the apical axis, 90:
            across it). A reviewer's `position` decision overrides the class.
        """
        from ._tables import physical_centroids, physical_cov

        rule = self.position[name]
        parent = rule["parent"]
        df = self._corrected(name) if df is None else df
        n = len(df)
        out: dict[str, Any] = {
            "position": np.full(n, "unknown", dtype=object),
            "position_axial": np.full(n, np.nan),
            "position_radial": np.full(n, np.nan),
            "angle_to_axis_deg": np.full(n, np.nan),
        }
        if parent not in self.parents[name] or not n:
            return out
        axes = self.meta[name].get("axes") or ""
        size = self.meta[name].get("pixel_size")
        pe = self._corrected(parent)
        pid = df[f"{parent}_id"].to_numpy(dtype=np.int64)
        spread = [f"cov_{a}{a}" for a in axes]
        missing = [
            t
            for t, d in ((name, df), (parent, pe))
            if not set(spread) <= set(d)
        ]
        if missing:
            logger.warning(
                "no spread (cov_*) columns in the table(s) of %s -- written "
                "by an older patchworks; recompute them (patchworks tables "
                "%s) to classify positions",
                ", ".join(missing),
                self.store,
            )
            out["position"][pid == 0] = "outside"
            return out
        out["position"][pid == 0] = "outside"
        inside = np.flatnonzero(np.isin(pid, pe.index.to_numpy()))
        if not inside.size:
            return out
        prow = pe.index.get_indexer(pid[inside])
        centre = physical_centroids(pe, axes, size)[prow]
        pcov = physical_cov(pe, axes, size)[prow]
        axis = self._apical_axes(name, rule, pe, axes, size)[prow]

        c = physical_centroids(df, axes, size)[inside]
        w, v = np.linalg.eigh(physical_cov(df, axes, size)[inside])
        main = v[:, :, -1]
        half = np.sqrt(12 * np.clip(w[:, -1], 0, None)) / 2
        ends = np.stack([c + half[:, None] * main, c - half[:, None] * main])
        near = np.argmin(np.linalg.norm(ends - centre, axis=2), axis=0)
        base = ends[near, np.arange(inside.size)]

        rel = base - centre
        along = np.einsum("ij,ij->i", rel, axis)
        var_a = np.einsum("ij,ijk,ik->i", axis, pcov, axis)
        axial = along / np.sqrt(3 * np.clip(var_a, 1e-12, None))
        perp = rel - along[:, None] * axis
        across = np.sqrt(
            2 * np.clip(np.trace(pcov, axis1=1, axis2=2) - var_a, 1e-12, None)
        )
        radial = np.linalg.norm(perp, axis=1) / across
        angle = np.degrees(
            np.arccos(np.clip(np.abs(np.einsum("ij,ij->i", main, axis)), 0, 1))
        )
        # The surface the base is nearest to, each depth relative to the
        # parent's size in that direction: top, bottom or side wall. Deeper
        # than `central_depth` from all three: central.
        depth = np.stack([1 - axial, 1 + axial, 1 - radial], 1)
        cls = np.array(["apical", "basal", "lateral"], dtype=object)[
            np.argmin(depth, axis=1)
        ]
        cls[depth.min(axis=1) > float(rule.get("central_depth", 0.5))] = (
            "central"
        )
        known = np.isfinite(axis).all(axis=1)
        cls[~known] = "unknown"
        out["position"][inside] = cls
        out["position_axial"][inside] = np.where(known, axial, np.nan)
        out["position_radial"][inside] = np.where(known, radial, np.nan)
        out["angle_to_axis_deg"][inside] = np.where(known, angle, np.nan)
        for label, d in self.decisions[name].items():
            if d["action"] == "position" and label in df.index:
                out["position"][df.index.get_loc(label)] = d["position"]
        return out

    def _apical_axes(self, name, rule, pe, axes, size) -> np.ndarray:
        """Unit apical direction per parent object.

        Parameters
        ----------
        name : str
            The child label image, named in messages.
        rule : mapping
            Its position rule: `parent` and `apical`.
        pe : pandas.DataFrame
            The parent's corrected rows.
        axes : str
            The spatial axes' names.
        size : mapping or None
            µm per voxel by axis.

        Returns
        -------
        np.ndarray
            `(n_parents, ndim)`; NaN rows where the direction cannot be told.
        """
        from ._tables import physical_centroids, physical_cov

        spec = str(rule.get("apical", ""))
        n = len(pe)
        if spec in _AXES_SIGNS:
            ax, sign = _AXES_SIGNS[spec]
            if ax not in axes:
                raise ValueError(f"apical {spec!r}: {name} has axes {axes!r}")
            vec = np.zeros(len(axes))
            vec[axes.index(ax)] = sign
            return np.tile(vec, (n, 1))
        towards = spec.startswith("towards:")
        ref = spec.split(":", 1)[1] if towards else spec
        parent = rule["parent"]
        if ref not in self.tables or parent not in self.parents.get(ref, []):
            # Not an error: the relation may simply not be computed yet (a
            # concurrent relate job). Positions stay "unknown"; the rest of
            # the workbook is still worth writing.
            logger.warning(
                "apical %r for %s: needs %r related to %r (its objects inside "
                "the parent objects), or a direction like '+z'; positions "
                "left unknown",
                spec,
                name,
                ref,
                parent,
            )
            return np.full((n, len(axes)), np.nan)
        re = self._corrected(ref)
        re = re[re[f"{parent}_id"].isin(pe.index)]
        weights = re["area_voxels"].to_numpy(dtype=float)
        rc = physical_centroids(re, axes, size) * weights[:, None]
        import pandas as pd

        sums = pd.DataFrame(rc).groupby(re[f"{parent}_id"].to_numpy()).sum()
        wsum = pd.Series(weights).groupby(re[f"{parent}_id"].to_numpy()).sum()
        refc = (sums.div(wsum, axis=0)).reindex(pe.index).to_numpy()
        centre = physical_centroids(pe, axes, size)
        vec = centre - refc if not towards else refc - centre
        norm = np.linalg.norm(vec, axis=1)
        scale = np.sqrt(
            np.trace(physical_cov(pe, axes, size), axis1=1, axis2=2)
        )
        with np.errstate(invalid="ignore", divide="ignore"):
            vec = vec / norm[:, None]
        vec[~(norm > 0.1 * scale)] = np.nan  # reference at the centre: no axis
        return vec

    # -- flags and queues ----------------------------------------------------

    def min_overlap(self, child: str, parent: str) -> float:
        """The overlap below which a child is flagged as outside its parent.

        The rule given, else the one recorded with the store, else 0.5.

        Parameters
        ----------
        child, parent : str
            The two label images.

        Returns
        -------
        float
        """
        for rule in (self._min_overlap, self._recorded_overlap):
            if isinstance(rule, Mapping):
                value = (rule.get(child) or {}).get(parent)
                if value is not None:
                    return float(value)
            elif rule is not None:
                return float(rule)
        return 0.5

    def flag_table(self, name: str) -> "pd.DataFrame":
        """Flagged objects of *name*, most suspicious first.

        Cached until the next decision: the panel asks several times per
        key press, and a poor segmentation can flag a large share of
        hundreds of thousands of objects.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        pandas.DataFrame
            `score` and `partner` (-1: none), indexed by label.
        """
        if name not in self._flag_cache:
            rows = self._flag_rows(name)
            g = rows.groupby("label")
            table = (g["score"].max() + 0.1 * (g.size() - 1)).to_frame("score")
            table["partner"] = g["partner"].max()
            table = table.sort_index().sort_values(
                "score", ascending=False, kind="stable"
            )
            self._flag_cache[name] = (table, rows)
        return self._flag_cache[name][0]

    def reasons(self, name: str, label: int) -> list[str]:
        """Why object *label* of *name* is flagged (empty if it isn't).

        Parameters
        ----------
        name : str
            The label image.
        label : int
            The object.

        Returns
        -------
        list of str
        """
        self.flag_table(name)
        rows = self._flag_cache[name][1]
        return rows.loc[rows["label"] == int(label), "reason"].tolist()

    def flags(self, name: str) -> list[Flag]:
        """Every flagged object of *name*, its reasons, most suspicious first.

        See :meth:`flag_table` for the fast form.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        list of Flag
        """
        table = self.flag_table(name)
        rows = self._flag_cache[name][1]
        by_label = rows.groupby("label")["reason"].apply(list)
        return [
            Flag(
                int(label),
                by_label[label],
                float(r.score),
                None if r.partner < 0 else int(r.partner),
            )
            for label, r in zip(table.index, table.itertuples())
        ]

    def _flag_rows(self, name: str) -> "pd.DataFrame":
        """One row per (object, reason) of *name*.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        pandas.DataFrame
            Columns `label`, `reason`, `score`, `partner`.
        """
        import pandas as pd

        eff = self.effective(name)
        ids = eff.index.to_numpy()
        parts = []

        def rule_(mask, reasons, scores, partners=None):
            """Add a flag row for each object *mask* selects.

            Parameters
            ----------
            mask : np.ndarray of bool
                The objects flagged, over the effective table's rows.
            reasons : iterable of str
                One reason per flagged object.
            scores : float or array
                How suspicious, one value or one per flagged object.
            partners : array, optional
                    The other object involved, per flagged object (default
                none: -1).
            """
            labels = ids[mask]
            if labels.size:
                parts.append(
                    pd.DataFrame(
                        {
                            "label": labels.astype(np.int64),
                            "reason": list(reasons),
                            "score": np.broadcast_to(
                                np.asarray(scores, float), labels.shape
                            ),
                            "partner": (
                                -1
                                if partners is None
                                else np.asarray(partners, np.int64)
                            ),
                        }
                    )
                )

        for p in self.parents[name]:
            pid = eff[f"{p}_id"].to_numpy()
            ov = eff[f"{p}_overlap"].to_numpy(dtype=float)
            limit = self.min_overlap(name, p)
            nice = _nice(p)
            orphan = pid == 0
            by_distance = f"{p}_distance_um" in eff
            rule_(
                orphan,
                [
                    f"not inside or near any {nice}"
                    if by_distance
                    else f"not inside any {nice}"
                ]
                * int(orphan.sum()),
                3.0,
            )
            gap = (
                eff[f"{p}_distance_um"].to_numpy(dtype=float)
                if by_distance
                else np.zeros(len(eff))
            )
            near = (pid != 0) & (gap > 0)
            rule_(
                near,
                (
                    f"outside {nice} #{q}, {g:.2g} µm away"
                    for q, g in zip(pid[near], gap[near])
                ),
                1.5,
            )
            weak = (pid != 0) & (ov < limit) & ~(gap > 0)
            rule_(
                weak,
                (
                    f"only {v:.0%} inside {nice} #{q}"
                    for v, q in zip(ov[weak], pid[weak])
                ),
                2.0 + (limit - ov[weak]),
            )
        for child, (lo, hi) in self.expect.get(name, {}).items():
            if f"n_{child}" not in eff:
                continue
            n = eff[f"n_{child}"].to_numpy()
            off = (n < lo) | (n > hi)
            want = f"{lo}" if lo == hi else f"{lo}-{hi}"
            rule_(
                off,
                (f"{k} {_nice(child)} (expected {want})" for k in n[off]),
                2.0,
            )
        if name in self.position and "position" in eff:
            rule = self.position[name]
            unknown = (eff["position"] == "unknown").to_numpy()
            ref = str(rule.get("apical", "")).removeprefix("towards:")
            rule_(
                unknown,
                [
                    f"position unclear: its {_nice(rule['parent'])} has no "
                    f"{_nice(ref)} to orient it"
                ]
                * int(unknown.sum()),
                1.2,
            )
        if len(eff) >= 20:
            logv = np.log(eff["area_voxels"].to_numpy(dtype=float))
            med = np.median(logv)
            mad = 1.4826 * np.median(np.abs(logv - med))
            if mad > 0:
                z = (logv - med) / mad
                odd = np.abs(z) > 3.5
                rule_(
                    odd,
                    (
                        f"unusually large ({math.exp(lv - med):.1f}x the median)"
                        if zz > 0
                        else f"unusually small ({math.exp(lv - med):.2f}x the median)"
                        for zz, lv in zip(z[odd], logv[odd])
                    ),
                    1.0 + np.minimum(np.abs(z[odd]) / 10, 1.0),
                )
        pairs = self._seam_pairs(name, eff)
        if pairs:
            a, b, axes = (np.array(x) for x in zip(*pairs))
            for one, other in ((a, b), (b, a)):
                mask = np.isin(ids, one)
                order = pd.Series(other, index=one)
                order = order[~order.index.duplicated()]
                partners = order.reindex(ids[mask]).to_numpy()
                ax = pd.Series(axes, index=one)
                ax = ax[~ax.index.duplicated()].reindex(ids[mask]).to_numpy()
                rule_(
                    mask,
                    (
                        f"meets #{q} exactly at a tile seam ({x}): "
                        "one object split?"
                        for q, x in zip(partners, ax)
                    ),
                    2.5,
                    partners,
                )
        if not parts:
            return pd.DataFrame(
                {
                    "label": np.empty(0, np.int64),
                    "reason": [],
                    "score": np.empty(0),
                    "partner": np.empty(0, np.int64),
                }
            )
        return pd.concat(parts, ignore_index=True)

    def _seam_pairs(self, name: str, eff: "pd.DataFrame"):
        """Pairs of objects that meet face to face on a tile boundary.

        Two objects, one ending on the seam and the other starting there,
        whose footprints across the seam coincide: either two neighbours
        pressed together, or one object the tiling cut in two. Worth a look
        either way; from bounding boxes alone, so no voxels are read.

        Parameters
        ----------
        name : str
            The label image.
        eff : pandas.DataFrame
            Its effective table.

        Returns
        -------
        list of tuple of int
            `(a, b)` labels.
        """
        from scipy.spatial import cKDTree

        meta = self.meta[name]
        tile = meta.get("tile_shape")
        axes = meta.get("axes") or ""
        if not tile or len(eff) < 2 or not axes:
            return []
        shape = meta["labels"]["shape"]
        tile = list(tile)[-len(axes) :]
        tol = self.seam_tolerance
        lo = {ax: eff[f"bbox_min_{ax}"].to_numpy() for ax in axes}
        hi = {ax: eff[f"bbox_max_{ax}"].to_numpy() + 1 for ax in axes}
        ids = eff.index.to_numpy()
        pairs = []
        for k, ax in enumerate(axes):
            t = int(tile[k])
            if t <= 0 or t >= shape[k]:
                continue
            others = [a for a in axes if a != ax]
            end_s = np.round(hi[ax] / t) * t
            beg_s = np.round(lo[ax] / t) * t
            ok_m = (
                (np.abs(hi[ax] - end_s) <= tol)
                & (end_s > 0)
                & (end_s < shape[k])
            )
            ok_p = (
                (np.abs(lo[ax] - beg_s) <= tol)
                & (beg_s > 0)
                & (beg_s < shape[k])
            )
            for s in np.intersect1d(end_s[ok_m], beg_s[ok_p]):
                m = np.flatnonzero(ok_m & (end_s == s))
                p = np.flatnonzero(ok_p & (beg_s == s))
                if not m.size or not p.size:
                    continue

                def box(idx):
                    """The bounding boxes of objects *idx* on the seam's face
                    axes.

                    Parameters
                    ----------
                    idx : np.ndarray
                        Row indices.

                    Returns
                    -------
                    tuple of np.ndarray
                        `(starts, stops)`, float.
                    """
                    b0 = np.stack([lo[a][idx] for a in others], 1).astype(float)
                    b1 = np.stack([hi[a][idx] for a in others], 1).astype(float)
                    return b0, b1

                m0, m1 = box(m)
                p0, p1 = box(p)
                pc = (p0 + p1) / 2
                reach = np.linalg.norm(m1 - m0, axis=1) / 2 + (
                    np.linalg.norm(p1 - p0, axis=1).max() / 2
                )
                tree = cKDTree(pc)
                for i, js in enumerate(
                    tree.query_ball_point((m0 + m1) / 2, reach)
                ):
                    if not js:
                        continue
                    js = np.asarray(js)
                    inter = np.prod(
                        np.clip(
                            np.minimum(m1[i], p1[js])
                            - np.maximum(m0[i], p0[js]),
                            0,
                            None,
                        ),
                        axis=1,
                    )
                    small = np.minimum(
                        np.prod(m1[i] - m0[i]), np.prod(p1[js] - p0[js], axis=1)
                    )
                    exact = (hi[ax][m[i]] == s) | (lo[ax][p[js]] == s)
                    for j in js[(inter >= 0.5 * small) & exact]:
                        if ids[m[i]] != ids[p[j]]:
                            pairs.append((int(ids[m[i]]), int(ids[p[j]]), ax))
        return pairs

    def queue(self, name: str, mode: str = "flagged") -> list[int]:
        """Objects still to review, in review order.

        Parameters
        ----------
        name : str
            The label image.
        mode : str, optional
            `flagged` (default): flagged objects, most suspicious first.
            `random`: a fixed random order over every object (the error
            estimate). `all`: every object by id.

        Returns
        -------
        list of int

        Raises
        ------
        ValueError
            For another mode.
        """
        done = self.decisions[name]
        if mode == "flagged":
            return [
                int(x) for x in self.flag_table(name).index if x not in done
            ]
        if mode == "random":
            return [x for x in self.random_order(name) if x not in done]
        if mode == "all":
            return [int(x) for x in self.effective(name).index if x not in done]
        raise ValueError(f"queue must be one of {QUEUES}, got {mode!r}")

    def random_order(self, name: str) -> list[int]:
        """Every object of *name* in a fixed random order (the review's seed).

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        list of int
        """
        ids = self.tables[name].index.to_numpy()
        rng = np.random.default_rng(self.seed[name])
        return [int(x) for x in ids[rng.permutation(ids.size)]]

    def summary(self, name: str) -> dict[str, Any]:
        """Counts of objects, flags and decisions, and the error estimate.

        The estimate uses the longest run of the random order that has been
        fully reviewed (from any queue: a decision is the truth about that
        object however it came up), so it stays unbiased.

        Parameters
        ----------
        name : str
            The label image.

        Returns
        -------
        dict
        """
        dec = self.decisions[name]
        # A segmentation error: rejected, joined or re-parented. A position
        # correction is a classification fix, counted on its own.
        wrong = {
            k
            for k, d in dec.items()
            if d["action"] in ("wrong", "merge", "parent")
        }
        sample = 0
        errors = 0
        for label in self.random_order(name):
            if label not in dec:
                break
            sample += 1
            errors += label in wrong
        flagged = self.flag_table(name).index
        lo, hi = wilson_interval(errors, sample)
        return {
            "objects": int(len(self.tables[name])),
            "flagged": len(flagged),
            "flagged_open": sum(int(x) not in dec for x in flagged),
            "reviewed": len(dec),
            "ok": sum(d["action"] == "ok" for d in dec.values()),
            "wrong": sum(d["action"] == "wrong" for d in dec.values()),
            "fixed": sum(
                d["action"] in ("parent", "merge") for d in dec.values()
            ),
            "position_fixed": sum(
                d["action"] == "position" for d in dec.values()
            ),
            "sample": sample,
            "sample_errors": errors,
            "error_rate": errors / sample if sample else None,
            "error_ci": (lo, hi) if sample else None,
        }

    # -- outputs -------------------------------------------------------------

    def export(self, out_dir: Union[str, Path], fmt: str = "csv") -> list[Path]:
        """Write every corrected table to *out_dir*, one file per label image.

        Parameters
        ----------
        out_dir : str or Path
            The directory (created if missing).
        fmt : str, optional
            `csv` (default) loads straight into napari-chunked-regionprops
            ("Reload previous results"). `xlsx` falls back to csv for a table
            longer than Excel allows. `parquet` needs pyarrow.

        Returns
        -------
        list of Path
            The files written.
        """
        out = Path(out_dir)
        out.mkdir(parents=True, exist_ok=True)
        written = []
        for name in self.names:
            df = self.effective(name)
            kind = fmt
            if fmt == "xlsx" and len(df) + 1 > EXCEL_MAX_ROWS:
                logger.warning(
                    "%s has %d objects, more than an Excel sheet holds; "
                    "writing csv instead",
                    name,
                    len(df),
                )
                kind = "csv"
            path = out / f"{name}.{kind}"
            if kind == "csv":
                df.to_csv(path)
            elif kind == "xlsx":
                df.to_excel(path, sheet_name=name[:31])
            elif kind == "parquet":
                df.to_parquet(path)
            else:
                raise ValueError(
                    f"format must be csv, xlsx or parquet: {fmt!r}"
                )
            written.append(path)
        return written

    def relation_workbook(
        self, child: str, parent: str, path: Union[str, Path]
    ) -> Path:
        """Write the *child* -> *parent* workbook from the corrected tables.

        Sheet *child*: each object, its parent, overlap and review status.
        Sheet *parent*: each parent object and how many children it holds.
        Written as two csv files (`<stem>_<name>.csv`) when a sheet would
        exceed Excel's row limit.

        Parameters
        ----------
        child, parent : str
            The two label images, the child related to the parent.
        path : str or Path
            The `.xlsx` file.

        Returns
        -------
        Path
            The file written (the first csv when split).
        """
        path = Path(path)
        ce = self.effective(child)
        pe = self.effective(parent)
        a = ce[
            [f"{parent}_id", f"{parent}_overlap_voxels", f"{parent}_overlap"]
        ]
        a = a.rename(
            columns={
                f"{parent}_id": f"{parent}_id",
                f"{parent}_overlap_voxels": "overlap_voxels",
                f"{parent}_overlap": "overlap_fraction",
            }
        ).copy()
        a[f"{parent}_id"] = a[f"{parent}_id"].where(a[f"{parent}_id"] != 0)
        if (
            "position" in ce
            and self.position.get(child, {}).get("parent") == parent
        ):
            a["position"] = ce["position"]
        a["qc"] = ce["qc"]
        a.index.name = f"{child}_id"
        grouped = ce[ce[f"{parent}_id"] != 0].groupby(f"{parent}_id")
        b = pe[[]].copy()
        b[f"{child}_count"] = (
            grouped.size().reindex(pe.index).fillna(0).astype(np.int64)
        )
        b["total_overlap_voxels"] = (
            grouped[f"{parent}_overlap_voxels"]
            .sum()
            .reindex(pe.index)
            .fillna(0)
            .astype(np.int64)
        )
        for cls in POSITIONS:
            col = f"n_{child}_{cls}"
            if col in pe:
                b[f"{child}_{cls}"] = pe[col]
        b["qc"] = pe["qc"]
        b.index.name = f"{parent}_id"
        if max(len(a), len(b)) + 1 > EXCEL_MAX_ROWS:
            logger.warning(
                "%s -> %s exceeds Excel's row limit; writing csv files",
                child,
                parent,
            )
            a.to_csv(path.with_name(f"{path.stem}_{child}.csv"))
            b.to_csv(path.with_name(f"{path.stem}_{parent}.csv"))
            return path.with_name(f"{path.stem}_{child}.csv")
        import pandas as pd

        with pd.ExcelWriter(path) as xl:
            a.to_excel(xl, sheet_name=child[:31])
            b.to_excel(xl, sheet_name=parent[:31])
        return path

    def write_reviewed_labels(
        self, name: str, *, suffix: str = "_reviewed"
    ) -> str:
        """Write the labels with the decisions applied to the voxels.

        Rejected objects are erased and merged objects get one id; the
        corrected table goes with them. The corrected tables and workbooks
        never need this; it is for figures and for tools that read label images
        only.

        Parameters
        ----------
        name : str
            The label image.
        suffix : str, optional
            Appended to *name* for the new label image (default
            `"_reviewed"`).

        Returns
        -------
        str
            The new label image's name.
        """
        import dask.array as da

        from ._provenance import PROVENANCE_KEY
        from ._tables import _level0, write_table
        from .plugins.ome_zarr import write_labels

        group = open_group_any(_label_group(self.store, name))
        level0 = da.from_zarr(_level0(group))
        roots = self.roots(name)
        top = int(max(self.tables[name].index.max(), max(roots, default=0)))
        lut = np.arange(top + 1, dtype=level0.dtype)
        for label, root in roots.items():
            lut[label] = root
        fixed = level0.map_blocks(lambda b: lut[b], dtype=level0.dtype)
        prov = dict(group.attrs).get(PROVENANCE_KEY) or {}
        settings = prov.get("settings") or {}
        record = dict(prov)
        record["review"] = {
            "from": name,
            "decisions": len(self.decisions[name]),
        }
        out = f"{name}{suffix}"
        write_labels(
            self.store,
            fixed,
            name=out,
            overwrite=True,
            level=int(settings.get("level") or 0),
            progress=False,
            provenance=record,
        )
        eff = self.effective(name).drop(columns=["qc"])
        cols = {"label": eff.index.to_numpy()}
        cols.update({c: eff[c].to_numpy() for c in eff.columns})
        meta = {
            k: v
            for k, v in self.meta[name].items()
            if k not in ("labels", "columns", "parents")
        }
        write_table(
            _label_group(self.store, out),
            cols,
            attrs={**meta, "reviewed_from": name},
        )
        return out

__init__(store: Union[str, Path], *, expect: Mapping[str, Mapping[str, Iterable[int]]] | None = None, min_overlap: float | Mapping[str, Mapping[str, float]] | None = None, seam_tolerance: int = 1, names: Iterable[str] | None = None, position: Mapping[str, Mapping[str, Any]] | None = None) -> None

Load the tables, the rules and the decisions; see the class docstring for the parameters.

Source code in src/patchworks/_review.py
def __init__(
    self,
    store: Union[str, Path],
    *,
    expect: Mapping[str, Mapping[str, Iterable[int]]] | None = None,
    min_overlap: float | Mapping[str, Mapping[str, float]] | None = None,
    seam_tolerance: int = 1,
    names: Iterable[str] | None = None,
    position: Mapping[str, Mapping[str, Any]] | None = None,
) -> None:
    """Load the tables, the rules and the decisions; see the class docstring
    for the parameters.
    """
    self.store = str(store).rstrip("/")
    self.seam_tolerance = int(seam_tolerance)
    self.names: list[str] = []
    self.meta: dict[str, dict[str, Any]] = {}
    self.tables: dict[str, pd.DataFrame] = {}
    self.stale: list[str] = []
    rules = read_rules(self.store)
    wanted = None if names is None else set(names)
    if wanted is not None:
        # A position rule also needs its parent's and its reference's tables.
        for child, rule in {
            **(rules.get("position") or {}),
            **(position or {}),
        }.items():
            if child in wanted and rule:
                spec = str(rule.get("apical", ""))
                wanted |= {
                    str(rule.get("parent")),
                    spec.removeprefix("towards:"),
                } - {""}
    for name in table_names(self.store):
        if wanted is not None and name not in wanted:
            continue
        group = _label_group(self.store, name)
        if not has_table(group):
            continue
        if is_stale(group):
            self.stale.append(name)
            continue
        self.names.append(name)
        self.meta[name] = table_meta(group)
        self.tables[name] = read_table(group, check=False)
    if self.stale:
        logger.warning(
            "tables of %s were computed from older labels and are "
            "ignored; recompute them (patchworks tables %s)",
            ", ".join(self.stale),
            self.store,
        )
    # A table's parents are the label images it has relation columns for.
    self.parents = {
        n: [
            p
            for p in self.names
            if p != n
            and f"{p}_id" in self.tables[n]
            and f"{p}_overlap" in self.tables[n]
        ]
        for n in self.names
    }
    self.children = {
        n: [c for c in self.names if n in self.parents[c]]
        for n in self.names
    }
    self.expect: dict[str, dict[str, tuple[int, int]]] = {}
    for n, rules_n in (rules.get("expect") or {}).items():
        for child, rng in rules_n.items():
            self.expect.setdefault(n, {})[child] = _range(rng)
    self._recorded_overlap = rules.get("min_overlap")
    for n, rules in (expect or {}).items():
        for child, rng in rules.items():
            self.expect.setdefault(n, {})[child] = _range(rng)
    self._min_overlap = min_overlap
    self.position: dict[str, dict[str, Any]] = {
        k: dict(v) for k, v in (rules.get("position") or {}).items()
    }
    for child, rule in (position or {}).items():
        self.position[child] = dict(rule)
    for child, rule in list(self.position.items()):
        if child not in self.tables or "parent" not in rule:
            # A rule for a label image left out on purpose (names=, as
            # each relate job loads just its pair) is no news.
            if "parent" not in rule or wanted is None or child in wanted:
                logger.warning(
                    "position rule for %s ignored: %s", child, rule
                )
            del self.position[child]
    self.decisions: dict[str, dict[int, dict[str, Any]]] = {}
    self.seed: dict[str, int] = {}
    for n in self.names:
        self._load_decisions(n)
    self._cache: dict[str, pd.DataFrame] = {}
    self._flag_cache: dict[str, tuple[pd.DataFrame, pd.DataFrame]] = {}

decide(name: str, label: int, action: str, *, parent: str | None = None, parent_id: int | None = None, into: int | None = None, position: str | None = None, queue: str = 'flagged', reviewer: str | None = None) -> None

Record a decision about object label of label image name.

Parameters:

Name Type Description Default
name str

The label image.

required
label int

The object.

required
action ('ok', 'wrong', 'parent', 'merge', 'position')

ok: correct as it is. wrong: not a real object (dropped from the corrected tables). parent: belongs to parent_id of label image parent (0 = to none). merge: the same object as into. position: its position class is position (one of :data:POSITIONS), whatever was computed.

"ok"
parent str

The parent label image, for parent.

None
parent_id int

The parent object it belongs to, for parent (0: none).

None
into int

The object it is merged into, for merge.

None
position str

Its position class, for position.

None
queue str

The queue it was reviewed from; "random" decisions feed the error estimate.

'flagged'
reviewer str

Who decided, recorded with the decision.

None

Raises:

Type Description
KeyError

When name has no table or no such object.

ValueError

For an unknown action, or one missing its argument.

Source code in src/patchworks/_review.py
def decide(
    self,
    name: str,
    label: int,
    action: str,
    *,
    parent: str | None = None,
    parent_id: int | None = None,
    into: int | None = None,
    position: str | None = None,
    queue: str = "flagged",
    reviewer: str | None = None,
) -> None:
    """Record a decision about object *label* of label image *name*.

    Parameters
    ----------
    name : str
        The label image.
    label : int
        The object.
    action : {"ok", "wrong", "parent", "merge", "position"}
        `ok`: correct as it is. `wrong`: not a real object (dropped
        from the corrected tables). `parent`: belongs to *parent_id*
        of label image *parent* (0 = to none). `merge`: the same
        object as *into*. `position`: its position class is
        *position* (one of :data:`POSITIONS`), whatever was computed.
    parent : str, optional
        The parent label image, for `parent`.
    parent_id : int, optional
        The parent object it belongs to, for `parent` (0: none).
    into : int, optional
        The object it is merged into, for `merge`.
    position : str, optional
        Its position class, for `position`.
    queue : str, optional
        The queue it was reviewed from; `"random"` decisions feed the
        error estimate.
    reviewer : str, optional
        Who decided, recorded with the decision.

    Raises
    ------
    KeyError
        When *name* has no table or no such object.
    ValueError
        For an unknown action, or one missing its argument.
    """
    if name not in self.tables:
        raise KeyError(f"no table for labels/{name}")
    label = int(label)
    if label not in self.tables[name].index:
        raise KeyError(f"{name} has no object {label}")
    if action not in ACTIONS:
        raise ValueError(f"action must be one of {ACTIONS}, got {action!r}")
    entry: dict[str, Any] = {
        "action": action,
        "queue": queue,
        "time": _dt.datetime.now(_dt.timezone.utc).isoformat(
            timespec="seconds"
        ),
    }
    if reviewer:
        entry["by"] = reviewer
    if action == "parent":
        if parent not in self.parents[name]:
            raise ValueError(
                f"{name} has no parent image {parent!r} "
                f"(has {self.parents[name]})"
            )
        pid = int(parent_id or 0)
        if pid and pid not in self.tables[parent].index:
            raise KeyError(f"{parent} has no object {pid}")
        entry.update(parent=parent, parent_id=pid)
        previous = self.decisions[name].get(label, {})
        if previous.get("action") == "parent":
            entry["parents"] = {**previous.get("parents", {}), parent: pid}
        else:
            entry["parents"] = {parent: pid}
    elif action == "position":
        if name not in self.position:
            raise ValueError(f"{name} has no position rule")
        if position not in POSITIONS:
            raise ValueError(f"position must be one of {POSITIONS}")
        entry["position"] = position
    elif action == "merge":
        into = int(into or 0)
        if into == label or into not in self.tables[name].index:
            raise KeyError(f"cannot merge {name} {label} into {into}")
        entry["into"] = into
    self.decisions[name][label] = entry
    self._save(name)

relations() -> list[tuple[str, str]]

Every (child, parent) pair the tables relate.

Source code in src/patchworks/_review.py
def relations(self) -> list[tuple[str, str]]:
    """Every (child, parent) pair the tables relate."""
    return [(c, p) for c in self.names for p in self.parents[c]]

undo(name: str, label: int) -> None

Forget the decision about label (it goes back to unreviewed).

Parameters:

Name Type Description Default
name str

The label image.

required
label int

The object.

required
Source code in src/patchworks/_review.py
def undo(self, name: str, label: int) -> None:
    """Forget the decision about *label* (it goes back to unreviewed).

    Parameters
    ----------
    name : str
        The label image.
    label : int
        The object.
    """
    if self.decisions[name].pop(int(label), None) is not None:
        self._save(name)

roots(name: str) -> dict[int, int]

Where each decided object ends up.

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
dict of int to int
0 if rejected, the object it was merged into (followed to the

end) otherwise. Undecided objects are absent (they map to themselves).

Source code in src/patchworks/_review.py
def roots(self, name: str) -> dict[int, int]:
    """Where each decided object ends up.

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    dict of int to int
            0 if rejected, the object it was merged into (followed to the
        end)
        otherwise. Undecided objects are absent (they map to themselves).
    """
    dec = self.decisions[name]
    out: dict[int, int] = {}
    for label in dec:
        seen, cur = {label}, label
        while True:
            d = dec.get(cur)
            if d is None or d["action"] in ("ok", "parent", "position"):
                break
            if d["action"] == "wrong":
                cur = 0
                break
            cur = int(d["into"])
            if cur in seen:  # a merge cycle: keep the smallest id
                cur = min(seen)
                break
            seen.add(cur)
        if cur != label:
            out[label] = cur
    return out

hover_features(name: str) -> 'pd.DataFrame'

Per-label features for napari's status bar.

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
DataFrame

Each object's parent(s), number of children, position and review status, with an index column of labels.

Source code in src/patchworks/_review.py
def hover_features(self, name: str) -> "pd.DataFrame":
    """Per-label features for napari's status bar.

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    pandas.DataFrame
        Each object's parent(s), number of children, position and review
        status, with an `index` column of labels.
    """
    eff = self.effective(name)
    cols = [f"{p}_id" for p in self.parents[name]]
    cols += [f"n_{c}" for c in self.children[name]]
    cols += [c for c in ("position", "qc") if c in eff]
    return (
        eff[[c for c in cols if c in eff]]
        .reset_index()
        .rename(columns={eff.index.name or "label": "index"})
    )

effective(name: str) -> 'pd.DataFrame'

name's table with every decision applied.

Rejected objects are dropped; merged objects become one row (sizes added, centroids, spreads and intensities combined exactly, boxes joined); parent columns follow reassignments and the parents' own merges; qc says ok, fixed or "" (not reviewed). Derived columns: n_<child> (children counted), length_um, elongation, axis_<a> (shape, see :func:~patchworks._tables.shape_columns) and, for label images with a position rule, position and its measures (see :meth:positions).

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
DataFrame

Indexed by label; cached until the next decision.

Source code in src/patchworks/_review.py
def effective(self, name: str) -> "pd.DataFrame":
    """*name*'s table with every decision applied.

    Rejected objects are dropped; merged objects become one row (sizes
    added, centroids, spreads and intensities combined exactly, boxes
    joined); parent columns follow reassignments and the parents' own
    merges; `qc` says `ok`, `fixed` or `""` (not reviewed).
    Derived columns: `n_<child>` (children counted), `length_um`,
    `elongation`, `axis_<a>` (shape, see
    :func:`~patchworks._tables.shape_columns`) and, for label images
    with a position rule, `position` and its measures (see
    :meth:`positions`).

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    pandas.DataFrame
        Indexed by label; cached until the next decision.
    """
    if name in self._cache:
        return self._cache[name]
    from ._tables import shape_columns

    df = self._corrected(name).copy()
    for child in self.children[name]:
        ce = self._corrected(child)
        counts = ce[f"{name}_id"].value_counts()
        df[f"n_{child}"] = (
            counts.reindex(df.index).fillna(0).astype(np.int64)
        )
    meta = self.meta[name]
    for col, values in shape_columns(
        df, meta.get("axes") or "", meta.get("pixel_size")
    ).items():
        df[col] = values
    if name in self.position:
        for col, values in self.positions(name, df).items():
            df[col] = values
    for child in self.children[name]:
        if (
            child in self.position
            and self.position[child]["parent"] == name
        ):
            pos = self.effective(child)
            table = (
                pos[pos[f"{name}_id"] != 0]
                .groupby([f"{name}_id", "position"])
                .size()
                .unstack(fill_value=0)
            )
            for cls in POSITIONS:
                counts = table[cls] if cls in table else None
                df[f"n_{child}_{cls}"] = (
                    counts.reindex(df.index).fillna(0).astype(np.int64)
                    if counts is not None
                    else 0
                )
    self._cache[name] = df
    return df

positions(name: str, df: 'pd.DataFrame | None' = None) -> dict[str, Any]

Where each object of name sits in its parent.

Per parent object, an apical axis: a fixed direction ("+z": apical is up the z axis), or pointing away from the parent's children of another label image ("nuclei_labels": away from the nucleus, for epithelia whose nuclei sit basally), or towards them ("towards:<name>"). Each object's base is its end nearer the parent's centre (a cilium grows out from its base).

The class is the parent surface the base is nearest to -- top (apical), bottom (basal) or side wall (lateral) -- each depth measured relative to the parent's size in that direction; central when deeper than central_depth (default 0.5, i.e. half-way) from all three. The parent's shape is taken from its moments (an equivalent cylinder), so this is a classification, not a surface distance.

Parameters:

Name Type Description Default
name str

A label image with a position rule.

required
df DataFrame

Its rows, when already corrected (default: :meth:_corrected).

None

Returns:

Type Description
dict

Columns position (the class; outside with no parent; unknown when the axis cannot be told, e.g. no nucleus), position_axial (-1 basal .. +1 apical, in half-heights of the parent along its axis), position_radial (0 on the axis .. 1 at the side) and angle_to_axis_deg (0: along the apical axis, 90: across it). A reviewer's position decision overrides the class.

Source code in src/patchworks/_review.py
def positions(
    self, name: str, df: "pd.DataFrame | None" = None
) -> dict[str, Any]:
    """Where each object of *name* sits in its parent.

    Per parent object, an apical axis: a fixed direction (`"+z"`:
    apical is up the z axis), or pointing away from the parent's
    children of another label image (`"nuclei_labels"`: away from
    the nucleus, for epithelia whose nuclei sit basally), or towards
    them (`"towards:<name>"`). Each object's **base** is its end
    nearer the parent's centre (a cilium grows out from its base).

    The class is the parent surface the base is nearest to -- top
    (`apical`), bottom (`basal`) or side wall (`lateral`) --
    each depth measured relative to the parent's size in that
    direction; `central` when deeper than `central_depth` (default
    0.5, i.e. half-way) from all three. The parent's shape is taken
    from its moments (an equivalent cylinder), so this is a
    classification, not a surface distance.

    Parameters
    ----------
    name : str
        A label image with a position rule.
    df : pandas.DataFrame, optional
        Its rows, when already corrected (default: :meth:`_corrected`).

    Returns
    -------
    dict
        Columns `position` (the class; `outside` with no
        parent; `unknown` when the axis cannot be told, e.g. no nucleus),
        `position_axial` (-1 basal .. +1 apical, in half-heights of the
        parent along its axis), `position_radial` (0 on the axis .. 1 at
        the side) and `angle_to_axis_deg` (0: along the apical axis, 90:
        across it). A reviewer's `position` decision overrides the class.
    """
    from ._tables import physical_centroids, physical_cov

    rule = self.position[name]
    parent = rule["parent"]
    df = self._corrected(name) if df is None else df
    n = len(df)
    out: dict[str, Any] = {
        "position": np.full(n, "unknown", dtype=object),
        "position_axial": np.full(n, np.nan),
        "position_radial": np.full(n, np.nan),
        "angle_to_axis_deg": np.full(n, np.nan),
    }
    if parent not in self.parents[name] or not n:
        return out
    axes = self.meta[name].get("axes") or ""
    size = self.meta[name].get("pixel_size")
    pe = self._corrected(parent)
    pid = df[f"{parent}_id"].to_numpy(dtype=np.int64)
    spread = [f"cov_{a}{a}" for a in axes]
    missing = [
        t
        for t, d in ((name, df), (parent, pe))
        if not set(spread) <= set(d)
    ]
    if missing:
        logger.warning(
            "no spread (cov_*) columns in the table(s) of %s -- written "
            "by an older patchworks; recompute them (patchworks tables "
            "%s) to classify positions",
            ", ".join(missing),
            self.store,
        )
        out["position"][pid == 0] = "outside"
        return out
    out["position"][pid == 0] = "outside"
    inside = np.flatnonzero(np.isin(pid, pe.index.to_numpy()))
    if not inside.size:
        return out
    prow = pe.index.get_indexer(pid[inside])
    centre = physical_centroids(pe, axes, size)[prow]
    pcov = physical_cov(pe, axes, size)[prow]
    axis = self._apical_axes(name, rule, pe, axes, size)[prow]

    c = physical_centroids(df, axes, size)[inside]
    w, v = np.linalg.eigh(physical_cov(df, axes, size)[inside])
    main = v[:, :, -1]
    half = np.sqrt(12 * np.clip(w[:, -1], 0, None)) / 2
    ends = np.stack([c + half[:, None] * main, c - half[:, None] * main])
    near = np.argmin(np.linalg.norm(ends - centre, axis=2), axis=0)
    base = ends[near, np.arange(inside.size)]

    rel = base - centre
    along = np.einsum("ij,ij->i", rel, axis)
    var_a = np.einsum("ij,ijk,ik->i", axis, pcov, axis)
    axial = along / np.sqrt(3 * np.clip(var_a, 1e-12, None))
    perp = rel - along[:, None] * axis
    across = np.sqrt(
        2 * np.clip(np.trace(pcov, axis1=1, axis2=2) - var_a, 1e-12, None)
    )
    radial = np.linalg.norm(perp, axis=1) / across
    angle = np.degrees(
        np.arccos(np.clip(np.abs(np.einsum("ij,ij->i", main, axis)), 0, 1))
    )
    # The surface the base is nearest to, each depth relative to the
    # parent's size in that direction: top, bottom or side wall. Deeper
    # than `central_depth` from all three: central.
    depth = np.stack([1 - axial, 1 + axial, 1 - radial], 1)
    cls = np.array(["apical", "basal", "lateral"], dtype=object)[
        np.argmin(depth, axis=1)
    ]
    cls[depth.min(axis=1) > float(rule.get("central_depth", 0.5))] = (
        "central"
    )
    known = np.isfinite(axis).all(axis=1)
    cls[~known] = "unknown"
    out["position"][inside] = cls
    out["position_axial"][inside] = np.where(known, axial, np.nan)
    out["position_radial"][inside] = np.where(known, radial, np.nan)
    out["angle_to_axis_deg"][inside] = np.where(known, angle, np.nan)
    for label, d in self.decisions[name].items():
        if d["action"] == "position" and label in df.index:
            out["position"][df.index.get_loc(label)] = d["position"]
    return out

min_overlap(child: str, parent: str) -> float

The overlap below which a child is flagged as outside its parent.

The rule given, else the one recorded with the store, else 0.5.

Parameters:

Name Type Description Default
child str

The two label images.

required
parent str

The two label images.

required

Returns:

Type Description
float
Source code in src/patchworks/_review.py
def min_overlap(self, child: str, parent: str) -> float:
    """The overlap below which a child is flagged as outside its parent.

    The rule given, else the one recorded with the store, else 0.5.

    Parameters
    ----------
    child, parent : str
        The two label images.

    Returns
    -------
    float
    """
    for rule in (self._min_overlap, self._recorded_overlap):
        if isinstance(rule, Mapping):
            value = (rule.get(child) or {}).get(parent)
            if value is not None:
                return float(value)
        elif rule is not None:
            return float(rule)
    return 0.5

flag_table(name: str) -> 'pd.DataFrame'

Flagged objects of name, most suspicious first.

Cached until the next decision: the panel asks several times per key press, and a poor segmentation can flag a large share of hundreds of thousands of objects.

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
DataFrame

score and partner (-1: none), indexed by label.

Source code in src/patchworks/_review.py
def flag_table(self, name: str) -> "pd.DataFrame":
    """Flagged objects of *name*, most suspicious first.

    Cached until the next decision: the panel asks several times per
    key press, and a poor segmentation can flag a large share of
    hundreds of thousands of objects.

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    pandas.DataFrame
        `score` and `partner` (-1: none), indexed by label.
    """
    if name not in self._flag_cache:
        rows = self._flag_rows(name)
        g = rows.groupby("label")
        table = (g["score"].max() + 0.1 * (g.size() - 1)).to_frame("score")
        table["partner"] = g["partner"].max()
        table = table.sort_index().sort_values(
            "score", ascending=False, kind="stable"
        )
        self._flag_cache[name] = (table, rows)
    return self._flag_cache[name][0]

reasons(name: str, label: int) -> list[str]

Why object label of name is flagged (empty if it isn't).

Parameters:

Name Type Description Default
name str

The label image.

required
label int

The object.

required

Returns:

Type Description
list of str
Source code in src/patchworks/_review.py
def reasons(self, name: str, label: int) -> list[str]:
    """Why object *label* of *name* is flagged (empty if it isn't).

    Parameters
    ----------
    name : str
        The label image.
    label : int
        The object.

    Returns
    -------
    list of str
    """
    self.flag_table(name)
    rows = self._flag_cache[name][1]
    return rows.loc[rows["label"] == int(label), "reason"].tolist()

flags(name: str) -> list[Flag]

Every flagged object of name, its reasons, most suspicious first.

See :meth:flag_table for the fast form.

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
list of Flag
Source code in src/patchworks/_review.py
def flags(self, name: str) -> list[Flag]:
    """Every flagged object of *name*, its reasons, most suspicious first.

    See :meth:`flag_table` for the fast form.

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    list of Flag
    """
    table = self.flag_table(name)
    rows = self._flag_cache[name][1]
    by_label = rows.groupby("label")["reason"].apply(list)
    return [
        Flag(
            int(label),
            by_label[label],
            float(r.score),
            None if r.partner < 0 else int(r.partner),
        )
        for label, r in zip(table.index, table.itertuples())
    ]

queue(name: str, mode: str = 'flagged') -> list[int]

Objects still to review, in review order.

Parameters:

Name Type Description Default
name str

The label image.

required
mode str

flagged (default): flagged objects, most suspicious first. random: a fixed random order over every object (the error estimate). all: every object by id.

'flagged'

Returns:

Type Description
list of int

Raises:

Type Description
ValueError

For another mode.

Source code in src/patchworks/_review.py
def queue(self, name: str, mode: str = "flagged") -> list[int]:
    """Objects still to review, in review order.

    Parameters
    ----------
    name : str
        The label image.
    mode : str, optional
        `flagged` (default): flagged objects, most suspicious first.
        `random`: a fixed random order over every object (the error
        estimate). `all`: every object by id.

    Returns
    -------
    list of int

    Raises
    ------
    ValueError
        For another mode.
    """
    done = self.decisions[name]
    if mode == "flagged":
        return [
            int(x) for x in self.flag_table(name).index if x not in done
        ]
    if mode == "random":
        return [x for x in self.random_order(name) if x not in done]
    if mode == "all":
        return [int(x) for x in self.effective(name).index if x not in done]
    raise ValueError(f"queue must be one of {QUEUES}, got {mode!r}")

random_order(name: str) -> list[int]

Every object of name in a fixed random order (the review's seed).

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
list of int
Source code in src/patchworks/_review.py
def random_order(self, name: str) -> list[int]:
    """Every object of *name* in a fixed random order (the review's seed).

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    list of int
    """
    ids = self.tables[name].index.to_numpy()
    rng = np.random.default_rng(self.seed[name])
    return [int(x) for x in ids[rng.permutation(ids.size)]]

summary(name: str) -> dict[str, Any]

Counts of objects, flags and decisions, and the error estimate.

The estimate uses the longest run of the random order that has been fully reviewed (from any queue: a decision is the truth about that object however it came up), so it stays unbiased.

Parameters:

Name Type Description Default
name str

The label image.

required

Returns:

Type Description
dict
Source code in src/patchworks/_review.py
def summary(self, name: str) -> dict[str, Any]:
    """Counts of objects, flags and decisions, and the error estimate.

    The estimate uses the longest run of the random order that has been
    fully reviewed (from any queue: a decision is the truth about that
    object however it came up), so it stays unbiased.

    Parameters
    ----------
    name : str
        The label image.

    Returns
    -------
    dict
    """
    dec = self.decisions[name]
    # A segmentation error: rejected, joined or re-parented. A position
    # correction is a classification fix, counted on its own.
    wrong = {
        k
        for k, d in dec.items()
        if d["action"] in ("wrong", "merge", "parent")
    }
    sample = 0
    errors = 0
    for label in self.random_order(name):
        if label not in dec:
            break
        sample += 1
        errors += label in wrong
    flagged = self.flag_table(name).index
    lo, hi = wilson_interval(errors, sample)
    return {
        "objects": int(len(self.tables[name])),
        "flagged": len(flagged),
        "flagged_open": sum(int(x) not in dec for x in flagged),
        "reviewed": len(dec),
        "ok": sum(d["action"] == "ok" for d in dec.values()),
        "wrong": sum(d["action"] == "wrong" for d in dec.values()),
        "fixed": sum(
            d["action"] in ("parent", "merge") for d in dec.values()
        ),
        "position_fixed": sum(
            d["action"] == "position" for d in dec.values()
        ),
        "sample": sample,
        "sample_errors": errors,
        "error_rate": errors / sample if sample else None,
        "error_ci": (lo, hi) if sample else None,
    }

export(out_dir: Union[str, Path], fmt: str = 'csv') -> list[Path]

Write every corrected table to out_dir, one file per label image.

Parameters:

Name Type Description Default
out_dir str or Path

The directory (created if missing).

required
fmt str

csv (default) loads straight into napari-chunked-regionprops ("Reload previous results"). xlsx falls back to csv for a table longer than Excel allows. parquet needs pyarrow.

'csv'

Returns:

Type Description
list of Path

The files written.

Source code in src/patchworks/_review.py
def export(self, out_dir: Union[str, Path], fmt: str = "csv") -> list[Path]:
    """Write every corrected table to *out_dir*, one file per label image.

    Parameters
    ----------
    out_dir : str or Path
        The directory (created if missing).
    fmt : str, optional
        `csv` (default) loads straight into napari-chunked-regionprops
        ("Reload previous results"). `xlsx` falls back to csv for a table
        longer than Excel allows. `parquet` needs pyarrow.

    Returns
    -------
    list of Path
        The files written.
    """
    out = Path(out_dir)
    out.mkdir(parents=True, exist_ok=True)
    written = []
    for name in self.names:
        df = self.effective(name)
        kind = fmt
        if fmt == "xlsx" and len(df) + 1 > EXCEL_MAX_ROWS:
            logger.warning(
                "%s has %d objects, more than an Excel sheet holds; "
                "writing csv instead",
                name,
                len(df),
            )
            kind = "csv"
        path = out / f"{name}.{kind}"
        if kind == "csv":
            df.to_csv(path)
        elif kind == "xlsx":
            df.to_excel(path, sheet_name=name[:31])
        elif kind == "parquet":
            df.to_parquet(path)
        else:
            raise ValueError(
                f"format must be csv, xlsx or parquet: {fmt!r}"
            )
        written.append(path)
    return written

relation_workbook(child: str, parent: str, path: Union[str, Path]) -> Path

Write the child -> parent workbook from the corrected tables.

Sheet child: each object, its parent, overlap and review status. Sheet parent: each parent object and how many children it holds. Written as two csv files (<stem>_<name>.csv) when a sheet would exceed Excel's row limit.

Parameters:

Name Type Description Default
child str

The two label images, the child related to the parent.

required
parent str

The two label images, the child related to the parent.

required
path str or Path

The .xlsx file.

required

Returns:

Type Description
Path

The file written (the first csv when split).

Source code in src/patchworks/_review.py
def relation_workbook(
    self, child: str, parent: str, path: Union[str, Path]
) -> Path:
    """Write the *child* -> *parent* workbook from the corrected tables.

    Sheet *child*: each object, its parent, overlap and review status.
    Sheet *parent*: each parent object and how many children it holds.
    Written as two csv files (`<stem>_<name>.csv`) when a sheet would
    exceed Excel's row limit.

    Parameters
    ----------
    child, parent : str
        The two label images, the child related to the parent.
    path : str or Path
        The `.xlsx` file.

    Returns
    -------
    Path
        The file written (the first csv when split).
    """
    path = Path(path)
    ce = self.effective(child)
    pe = self.effective(parent)
    a = ce[
        [f"{parent}_id", f"{parent}_overlap_voxels", f"{parent}_overlap"]
    ]
    a = a.rename(
        columns={
            f"{parent}_id": f"{parent}_id",
            f"{parent}_overlap_voxels": "overlap_voxels",
            f"{parent}_overlap": "overlap_fraction",
        }
    ).copy()
    a[f"{parent}_id"] = a[f"{parent}_id"].where(a[f"{parent}_id"] != 0)
    if (
        "position" in ce
        and self.position.get(child, {}).get("parent") == parent
    ):
        a["position"] = ce["position"]
    a["qc"] = ce["qc"]
    a.index.name = f"{child}_id"
    grouped = ce[ce[f"{parent}_id"] != 0].groupby(f"{parent}_id")
    b = pe[[]].copy()
    b[f"{child}_count"] = (
        grouped.size().reindex(pe.index).fillna(0).astype(np.int64)
    )
    b["total_overlap_voxels"] = (
        grouped[f"{parent}_overlap_voxels"]
        .sum()
        .reindex(pe.index)
        .fillna(0)
        .astype(np.int64)
    )
    for cls in POSITIONS:
        col = f"n_{child}_{cls}"
        if col in pe:
            b[f"{child}_{cls}"] = pe[col]
    b["qc"] = pe["qc"]
    b.index.name = f"{parent}_id"
    if max(len(a), len(b)) + 1 > EXCEL_MAX_ROWS:
        logger.warning(
            "%s -> %s exceeds Excel's row limit; writing csv files",
            child,
            parent,
        )
        a.to_csv(path.with_name(f"{path.stem}_{child}.csv"))
        b.to_csv(path.with_name(f"{path.stem}_{parent}.csv"))
        return path.with_name(f"{path.stem}_{child}.csv")
    import pandas as pd

    with pd.ExcelWriter(path) as xl:
        a.to_excel(xl, sheet_name=child[:31])
        b.to_excel(xl, sheet_name=parent[:31])
    return path

write_reviewed_labels(name: str, *, suffix: str = '_reviewed') -> str

Write the labels with the decisions applied to the voxels.

Rejected objects are erased and merged objects get one id; the corrected table goes with them. The corrected tables and workbooks never need this; it is for figures and for tools that read label images only.

Parameters:

Name Type Description Default
name str

The label image.

required
suffix str

Appended to name for the new label image (default "_reviewed").

'_reviewed'

Returns:

Type Description
str

The new label image's name.

Source code in src/patchworks/_review.py
def write_reviewed_labels(
    self, name: str, *, suffix: str = "_reviewed"
) -> str:
    """Write the labels with the decisions applied to the voxels.

    Rejected objects are erased and merged objects get one id; the
    corrected table goes with them. The corrected tables and workbooks
    never need this; it is for figures and for tools that read label images
    only.

    Parameters
    ----------
    name : str
        The label image.
    suffix : str, optional
        Appended to *name* for the new label image (default
        `"_reviewed"`).

    Returns
    -------
    str
        The new label image's name.
    """
    import dask.array as da

    from ._provenance import PROVENANCE_KEY
    from ._tables import _level0, write_table
    from .plugins.ome_zarr import write_labels

    group = open_group_any(_label_group(self.store, name))
    level0 = da.from_zarr(_level0(group))
    roots = self.roots(name)
    top = int(max(self.tables[name].index.max(), max(roots, default=0)))
    lut = np.arange(top + 1, dtype=level0.dtype)
    for label, root in roots.items():
        lut[label] = root
    fixed = level0.map_blocks(lambda b: lut[b], dtype=level0.dtype)
    prov = dict(group.attrs).get(PROVENANCE_KEY) or {}
    settings = prov.get("settings") or {}
    record = dict(prov)
    record["review"] = {
        "from": name,
        "decisions": len(self.decisions[name]),
    }
    out = f"{name}{suffix}"
    write_labels(
        self.store,
        fixed,
        name=out,
        overwrite=True,
        level=int(settings.get("level") or 0),
        progress=False,
        provenance=record,
    )
    eff = self.effective(name).drop(columns=["qc"])
    cols = {"label": eff.index.to_numpy()}
    cols.update({c: eff[c].to_numpy() for c in eff.columns})
    meta = {
        k: v
        for k, v in self.meta[name].items()
        if k not in ("labels", "columns", "parents")
    }
    write_table(
        _label_group(self.store, out),
        cols,
        attrs={**meta, "reviewed_from": name},
    )
    return out

patchworks.plugins.review.review_in_napari(store: Union[str, Path], *, expect: dict | None = None, min_overlap: float | None = None, position: dict | None = None, show: bool = True, viewer: Any = None)

Open store in napari with the review panel docked.

Parameters:

Name Type Description Default
store str or Path

OME-ZARR image store whose label images carry object tables (the workflow writes them; patchworks tables adds them).

required
expect dict | None

Review rules, see :class:patchworks._review.Review.

None
min_overlap dict | None

Review rules, see :class:patchworks._review.Review.

None
position dict | None

Review rules, see :class:patchworks._review.Review.

None
show bool

Start the napari event loop (blocking).

True
viewer Viewer

Reuse a viewer that already shows the store's layers.

None

Returns:

Type Description
tuple

(viewer, widget).

Source code in src/patchworks/plugins/review.py
def review_in_napari(
    store: Union[str, Path],
    *,
    expect: dict | None = None,
    min_overlap: float | None = None,
    position: dict | None = None,
    show: bool = True,
    viewer: Any = None,
):
    """Open *store* in napari with the review panel docked.

    Parameters
    ----------
    store : str or Path
        OME-ZARR image store whose label images carry object tables
        (the workflow writes them; `patchworks tables` adds them).
    expect, min_overlap, position
        Review rules, see :class:`patchworks._review.Review`.
    show : bool
        Start the napari event loop (blocking).
    viewer : napari.Viewer, optional
        Reuse a viewer that already shows the store's layers.

    Returns
    -------
    tuple
        `(viewer, widget)`.
    """
    from .napari import _require_napari, view_in_napari

    napari = _require_napari()
    rv = Review(
        store, expect=expect, min_overlap=min_overlap, position=position
    )
    if not rv.names:
        raise ValueError(
            f"no label image in {store} has an object table yet: run "
            f"`patchworks tables {store}` first"
            + (f" (stale: {', '.join(rv.stale)})" if rv.stale else "")
        )
    if viewer is None:
        viewer = view_in_napari(store, show=False)
    widget = ReviewWidget(viewer, rv)
    viewer.window.add_dock_widget(widget, name="Review", area="right")
    if show:
        napari.run()
    return viewer, widget