patchworks 0.11.17__tar.gz → 0.11.19__tar.gz

{patchworks-0.11.17 → patchworks-0.11.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 0.11.17
+Version: 0.11.19
 Summary: Tiled processing of arbitrarily large images with globally consistent labels
 Project-URL: Homepage, https://github.com/imcf/patchworks
 Project-URL: Issues, https://github.com/imcf/patchworks/issues
@@ -34,7 +34,7 @@ Requires-Dist: glasbey; extra == 'all'
 Requires-Dist: imaris-ims-file-reader; extra == 'all'
 Requires-Dist: ipykernel<7; extra == 'all'
 Requires-Dist: lxml-html-clean; extra == 'all'
-Requires-Dist: napari[all]>=0.5.5; extra == 'all'
+Requires-Dist: napari[all]>=0.7.1; extra == 'all'
 Requires-Dist: numpy<2.5; extra == 'all'
 Requires-Dist: nvidia-ml-py; extra == 'all'
 Requires-Dist: psutil; extra == 'all'
@@ -74,7 +74,7 @@ Provides-Extra: napari
 Requires-Dist: glasbey; extra == 'napari'
 Requires-Dist: ipykernel<7; extra == 'napari'
 Requires-Dist: lxml-html-clean; extra == 'napari'
-Requires-Dist: napari[all]>=0.5.5; extra == 'napari'
+Requires-Dist: napari[all]>=0.7.1; extra == 'napari'
 Requires-Dist: numpy<2.5; extra == 'napari'
 Provides-Extra: workflow
 Requires-Dist: snakemake-executor-plugin-slurm; extra == 'workflow'

{patchworks-0.11.17 → patchworks-0.11.19}/docs/guide/snakemake.md

@@ -194,6 +194,172 @@ also re-runs a step when its **code, params or software environment** change —
 so upgrading patchworks would re-do the conversion and overwrite an existing
 result. Keep `mtime` and reruns happen only when an output is missing or stale.
 
+## Running two segmentations (e.g. nuclei + cytoplasm)
+
+Every path the workflow writes — `tiles.json`, `stage.zarr`, per-tile `seg/`,
+the cached model, `labels.done` — lives under `work_dir/<label_name>/`, so
+running the workflow **twice with two configs against the same `work_dir`**
+never collides: each run gets its own private subdirectory, and both reuse
+the *same* already-converted `image.zarr` (conversion never re-runs).
+
+```yaml
+# config/config_nuclei.yaml
+input: "/data/scan.ims"
+work_dir: "/scratch/results"
+label_name: "nuclei_labels"
+channel: 1                # nuclear stain channel
+tile_shape: [16, 1024, 1024]
+cellpose:
+  model: "nuclei"
+  diameter: 15
+  do_3D: true
+```
+
+```yaml
+# config/config_cyto.yaml
+input: "/data/scan.ims"
+work_dir: "/scratch/results"   # same work_dir — image.zarr is reused
+label_name: "cyto_labels"
+channel: 0                # cytoplasm/membrane channel
+tile_shape: [16, 1024, 1024]   # keep this identical across configs — see below
+cellpose:
+  model: "cyto3"
+  diameter: 30
+  do_3D: true
+```
+
+Run them one after another (or as two independent SLURM submissions, even
+concurrently — they touch disjoint files):
+
+```bash
+snakemake --workflow-profile profile/slurm --configfile config/config_nuclei.yaml
+snakemake --workflow-profile profile/slurm --configfile config/config_cyto.yaml
+```
+
+!!! tip "One command for several segmentations + relations"
+    `config/multi.yaml` lists any number of segmentation configs plus which
+    pairs to relate afterward; `pixi run multi` (or `multi-slurm`) runs them
+    in order and writes a CSV per pair — see *One command: multiple
+    segmentations + relations* below for the config format.
+
+Both land side by side in the same store:
+
+```text
+results/image.zarr/labels/nuclei_labels/
+results/image.zarr/labels/cyto_labels/
+```
+
+!!! tip "Keep `tile_shape` (and `level`) identical across configs"
+    Different segmentations of the same image can use different `channel` and
+    `cellpose:` settings freely, but keep `tile_shape`/`level` the same across
+    configs — the label arrays then share the exact same chunk layout, which
+    `label_relations()` (below) requires.
+
+### Relating labels across segmentations
+
+Once you have two segmentations of the same image (e.g. nuclei inside cells),
+`label_relations()` maps each label in one to the label it overlaps most in
+the other — by streaming both arrays chunk by chunk, so it scales to
+hundreds of thousands of objects without loading anything fully into RAM:
+
+```python
+import dask.array as da
+from patchworks import label_relations
+
+nuclei = da.from_zarr("results/image.zarr", component="labels/nuclei_labels/0")
+cells = da.from_zarr("results/image.zarr", component="labels/cyto_labels/0")
+
+table = label_relations(nuclei, cells)
+table[2]
+# {'match': 3, 'overlap_voxels': 4821, 'overlap_fraction': 0.94}
+# -> nucleus 2 belongs to cell 3, 94% of its voxels fall inside it
+```
+
+Save it as a table:
+
+```python
+import csv
+
+with open("nuclei_to_cell.csv", "w", newline="") as f:
+    w = csv.writer(f)
+    w.writerow(["nucleus_id", "cell_id", "overlap_voxels", "overlap_fraction"])
+    for nucleus_id, m in table.items():
+        w.writerow([nucleus_id, m["match"], m["overlap_voxels"], m["overlap_fraction"]])
+```
+
+### One command: multiple segmentations + relations
+
+`scripts/run_multi.py` (wired up as `pixi run multi`) sequences the above
+manually: run every segmentation config listed, then compute + save every
+configured relation — one command instead of juggling several `snakemake`
+calls and a separate Python step.
+
+```yaml
+# config/multi.yaml
+segmentations:
+  - config/config_nuclei.yaml
+  - config/config_cyto.yaml
+
+relations:
+  - a: nuclei_labels
+    b: cyto_labels
+    output: nuclei_to_cyto.csv # written into work_dir
+```
+
+```bash
+pixi run multi-dry    # dry-run every segmentation config (skips relations)
+pixi run multi        # run locally
+pixi run multi-slurm  # submit every segmentation to SLURM
+```
+
+Every listed segmentation config must share the same `work_dir` (so
+`label_relations` has one `image.zarr` to read both label groups from) — the
+script checks this and errors out otherwise. `relations` is optional; omit it
+to just chain segmentations without a relation step.
+
+Both lists are ordinary lists, so 3+ segmentations work the same way — add
+more entries to `segmentations`, then list whichever pairs to relate. There's
+no automatic "chain": list every pair explicitly, e.g. for nuclei + cyto +
+membrane you'd add `nuclei_labels -> cyto_labels`, `nuclei_labels ->
+membrane_labels`, and `cyto_labels -> membrane_labels` as three separate
+entries under `relations`.
+
+## Measurements (fast, whole-volume regionprops)
+
+`skimage.measure.regionprops` needs the full labelled + intensity array in
+RAM — fine for one tile, not for a hundred-thousand-object OME-ZARR. Use
+[`dask-image`](https://image.dask.org)'s `ndmeasure`, which computes directly
+on the dask/zarr-backed arrays, chunk-parallel, without materializing the
+volume:
+
+```bash
+pip install dask-image
+```
+
+```python
+import dask.array as da
+from dask_image.ndmeasure import area, center_of_mass, mean, standard_deviation
+
+labels = da.from_zarr("results/image.zarr", component="labels/cyto_labels/0")
+image = da.from_zarr("results/image.zarr", component="0")[0]  # channel 0, level 0
+
+ids = da.unique(labels[labels > 0]).compute()
+areas = area(image, labels, ids).compute()               # voxel counts
+means = mean(image, labels, ids).compute()                # mean intensity
+stds = standard_deviation(image, labels, ids).compute()
+centroids = center_of_mass(image, labels, ids).compute()  # voxel coords (z, y, x)
+```
+
+Multiply `areas` by the voxel's physical volume and `centroids` by the pixel
+size (both read straight from the OME-ZARR's own `multiscales` metadata) to
+get µm-scale measurements.
+
+For interactively inspecting individual cells by clicking in the viewer
+(not all objects at once), the
+[napari-skimage-regionprops](https://github.com/haesleinhuepf/napari-skimage-regionprops)
+plugin's table widget works well — point it at a cropped region rather than
+the full volume, since it loads its input fully into memory.
+
 ## Custom segmentation function
 
 Not using Cellpose? Run **your own** per-tile function — no need to edit the

{patchworks-0.11.17 → patchworks-0.11.19}/pyproject.toml

@@ -59,15 +59,16 @@ bioio = [
 # imaris reads .ims files natively (HDF5, no JVM) for OME-ZARR conversion.
 imaris = ["imaris-ims-file-reader"]
 # napari enables the interactive viewer plugin.
-# - napari >= 0.5: NumPy 2.0 compatible (older 0.4.x uses np.array(copy=False),
-#   which raises under NumPy 2 -> ValidationError on Viewer()).
+# - napari >= 0.7.1: adds locked_data_level (manual multiscale resolution pin
+#   for 2D *and* 3D) — before this, 3D view always showed the coarsest
+#   pyramid level unconditionally, with no way to change it.
 # - numpy < 2.5: napari/numba don't support numpy 2.5 yet.
 # - ipykernel < 7: napari-console requires ipykernel < 7.
 # - lxml-html-clean: napari's notebook_display imports lxml.html.clean, split
 #   into a separate package in lxml >= 5.2 (else ImportError on Viewer()).
 # - glasbey: distinct high-contrast label LUTs for view_in_napari.
 napari = [
-    "napari[all]>=0.5.5",
+    "napari[all]>=0.7.1",
     "numpy<2.5",
     "ipykernel<7",
     "lxml-html-clean",

{patchworks-0.11.17 → patchworks-0.11.19}/src/patchworks/__init__.py

@@ -36,6 +36,7 @@ from ._distributed import create_stage, spatial_tiles, stage_tile
 from ._io import estimate_empty_tiles, load_ome_zarr
 from ._merge import merge_tile_labels
 from ._relabel import relabel_sequential_array, relabel_sequential_zarr
+from ._relations import label_relations
 
 try:
     __version__ = _pkg_version("patchworks")
@@ -52,6 +53,7 @@ __all__ = [
     "make_local_cluster",
     "relabel_sequential_array",
     "relabel_sequential_zarr",
+    "label_relations",
     "spatial_tiles",
     "create_stage",
     "stage_tile",

patchworks-0.11.19/src/patchworks/_relations.py

@@ -0,0 +1,148 @@
+"""Relate two label images by voxel overlap (e.g. nucleus -> containing cell)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Union
+
+import dask.array as da
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def _as_dask(
+    source: Union["da.Array", str, Path], component: str
+) -> "da.Array":
+    if isinstance(source, (str, Path)):
+        return da.from_zarr(str(source), component=component)
+    return source
+
+
+def _chunk_pairs(a_block: np.ndarray, b_block: np.ndarray) -> np.ndarray:
+    """Non-background ``(a_id, b_id) -> voxel count`` rows for one chunk pair."""
+    mask = (a_block > 0) & (b_block > 0)
+    if not mask.any():
+        return np.empty((0, 3), dtype=np.int64)
+    pairs = np.stack([a_block[mask], b_block[mask]], axis=1).astype(np.int64)
+    uniq, counts = np.unique(pairs, axis=0, return_counts=True)
+    return np.concatenate([uniq, counts[:, None]], axis=1)
+
+
+def label_relations(
+    a: Union["da.Array", str, Path],
+    b: Union["da.Array", str, Path],
+    *,
+    a_component: str = "labels",
+    b_component: str = "labels",
+    n_workers: int | None = None,
+) -> dict[int, dict[str, float]]:
+    """Map each label in *a* to its best-overlapping label in *b*.
+
+    For every non-background label in *a* (e.g. a nucleus segmentation),
+    finds the label in *b* (e.g. a cell/cytoplasm segmentation of the same
+    image) it shares the most voxels with. Streams both arrays chunk by
+    chunk — memory is bounded by the number of distinct label pairs (one row
+    per touching (a, b) pair per chunk), not by volume size.
+
+    *a* and *b* must be two segmentations of the **same image** (identical
+    shape and chunk layout) — e.g. two runs of the Snakemake workflow with
+    different ``label_name``/``cellpose:`` config but the same ``tile_shape``.
+
+    Parameters
+    ----------
+    a, b : da.Array, str or Path
+        Two label arrays of identical shape and chunking. A path is read via
+        ``dask.array.from_zarr(path, component=...)``.
+    a_component, b_component : str, optional
+        Zarr array name inside *a*/*b* when they're store paths (default
+        ``"labels"``).
+    n_workers : int or None, optional
+        Parallel chunk workers. Default ``min(4, cpu_count)``.
+
+    Returns
+    -------
+    dict
+        ``{a_label: {"match": b_label, "overlap_voxels": int,
+        "overlap_fraction": float}}`` — one entry per *a* label that touches
+        at least one non-background *b* voxel. ``overlap_fraction`` is the
+        matched voxel count over *a* label's total voxel count (1.0 = fully
+        contained). Labels in *a* with zero overlap are omitted.
+
+    Examples
+    --------
+    >>> from patchworks import label_relations
+    >>> table = label_relations(
+    ...     "scan.zarr/labels/nuclei", "scan.zarr/labels/cells"
+    ... )  # doctest: +SKIP
+    >>> table[2]  # nucleus 2 sits inside cell 3  # doctest: +SKIP
+    {'match': 3, 'overlap_voxels': 4821, 'overlap_fraction': 0.94}
+    """
+    a = _as_dask(a, a_component)
+    b = _as_dask(b, b_component)
+    if a.shape != b.shape:
+        raise ValueError(f"shape mismatch: a={a.shape} b={b.shape}")
+    if a.chunks != b.chunks:
+        raise ValueError(
+            "a and b must share the same chunk layout "
+            f"(a={a.chunks} b={b.chunks}); rechunk one to match the other, "
+            "e.g. b = b.rechunk(a.chunks)"
+        )
+
+    n_blocks = a.numblocks
+    total = int(np.prod(n_blocks))
+    nw = n_workers if n_workers is not None else min(4, os.cpu_count() or 1)
+
+    def _one(flat_idx: int) -> np.ndarray:
+        idx = np.unravel_index(flat_idx, n_blocks)
+        return _chunk_pairs(
+            np.asarray(a.blocks[idx]), np.asarray(b.blocks[idx])
+        )
+
+    with ThreadPoolExecutor(max_workers=nw) as ex:
+        parts = list(ex.map(_one, range(total)))
+
+    rows = [p for p in parts if p.size]
+    if not rows:
+        return {}
+    all_pairs = np.concatenate(rows, axis=0)
+
+    # Merge duplicate (a_id, b_id) rows across chunks (a label can span
+    # several chunks) by sorting on a combined key and summing runs.
+    key = all_pairs[:, 0] * (int(all_pairs[:, 1].max()) + 1) + all_pairs[:, 1]
+    order = np.argsort(key, kind="stable")
+    all_pairs, key = all_pairs[order], key[order]
+    starts = np.concatenate([[0], np.flatnonzero(np.diff(key)) + 1])
+    merged_counts = np.add.reduceat(all_pairs[:, 2], starts)
+    merged = np.stack(
+        [all_pairs[starts, 0], all_pairs[starts, 1], merged_counts], axis=1
+    )
+
+    a_totals: dict[int, int] = {}
+    for a_id, _, count in merged:
+        a_id = int(a_id)
+        a_totals[a_id] = a_totals.get(a_id, 0) + int(count)
+
+    best: dict[int, tuple[int, int]] = {}
+    for a_id, b_id, count in merged:
+        a_id, b_id, count = int(a_id), int(b_id), int(count)
+        cur = best.get(a_id)
+        if cur is None or count > cur[1]:
+            best[a_id] = (b_id, count)
+
+    logger.info(
+        "label_relations: %d a-labels matched across %d chunks",
+        len(best),
+        total,
+    )
+    return {
+        a_id: {
+            "match": b_id,
+            "overlap_voxels": count,
+            "overlap_fraction": count / a_totals[a_id],
+        }
+        for a_id, (b_id, count) in best.items()
+    }

{patchworks-0.11.17 → patchworks-0.11.19}/src/patchworks/plugins/napari.py

@@ -142,12 +142,14 @@ def _resolve_image(
     return source
 
 
-def _pyramid_scale(path: Union[str, Path], ndim: int) -> list[float] | None:
-    """Read the level-0 physical scale (µm/px) from an OME-ZARR's own metadata.
+def _pyramid_calibration(
+    path: Union[str, Path], ndim: int
+) -> tuple[list[float], list[str]] | tuple[None, None]:
+    """Read the level-0 physical scale and units from an OME-ZARR's metadata.
 
-    Without this, napari shows every axis with an implicit scale of 1, so a
-    volume with anisotropic voxels (e.g. z coarser than x/y) renders with the
-    wrong aspect ratio and no real-world units.
+    Without this, napari shows every axis with an implicit scale of 1 and
+    "pixel" units, so a volume with anisotropic voxels (e.g. z coarser than
+    x/y) renders with the wrong aspect ratio and no real-world units.
 
     Parameters
     ----------
@@ -161,15 +163,20 @@ def _pyramid_scale(path: Union[str, Path], ndim: int) -> list[float] | None:
 
     Returns
     -------
-    list of float or None
-        Physical size per axis, or ``None`` if the store carries no
-        calibration (napari then falls back to its uncalibrated default).
+    tuple
+        ``(scale, units)`` — physical size and unit name per axis — or
+        ``(None, None)`` if the store carries no calibration (napari then
+        falls back to its uncalibrated pixel default).
     """
     from .ome_zarr import _base_scale, _default_axes, _read_zarr_calibration
 
     axes = _default_axes(ndim)
     pixel_size = _read_zarr_calibration(str(path), axes)
-    return _base_scale(axes, pixel_size) if pixel_size else None
+    if not pixel_size:
+        return None, None
+    scale = _base_scale(axes, pixel_size)
+    units = ["micrometer"] * len(scale)
+    return scale, units
 
 
 def _inner_label_names(store: Union[str, Path]) -> list[str]:
@@ -271,6 +278,18 @@ def view_in_napari(
     napari.Viewer
         The viewer instance (useful when ``show=False``).
 
+    Notes
+    -----
+    In 3-D view (the cube icon, or ``viewer.dims.ndisplay = 3``), napari
+    always shows the **coarsest** pyramid level — there is no automatic
+    zoom-based switching in 3-D, only in 2-D. To pin a specific resolution
+    (needs ``napari>=0.7.1``)::
+
+        viewer.layers["labels"].locked_data_level = 0   # full resolution
+        viewer.layers["labels"].locked_data_level = None  # back to coarsest
+
+    A widget for this is also in the layer controls panel in napari>=0.7.1.
+
     Examples
     --------
     >>> view_in_napari("scan.zarr")  # auto-loads scan.zarr/labels/*  # doctest: +SKIP
@@ -279,13 +298,18 @@ def view_in_napari(
 
     img = _resolve_image(image, channel)
     img_ndim = img[0].ndim if isinstance(img, list) else img.ndim
-    img_scale = _pyramid_scale(image, img_ndim) if _is_zarr(image) else None
+    img_scale, img_units = (
+        _pyramid_calibration(image, img_ndim)
+        if _is_zarr(image)
+        else (None, None)
+    )
     viewer = napari.Viewer()
     viewer.add_image(
         img,
         name=image_name,
         multiscale=isinstance(img, list),
         scale=img_scale,
+        units=img_units,
         **add_image_kwargs,
     )
 
@@ -322,12 +346,17 @@ def view_in_napari(
     if labels is not None:
         lab = _resolve_labels(labels, labels_component)
         lab_ndim = lab[0].ndim if isinstance(lab, list) else lab.ndim
-        lab_scale = _pyramid_scale(labels, lab_ndim) if _is_zarr(labels) else None
+        lab_scale, lab_units = (
+            _pyramid_calibration(labels, lab_ndim)
+            if _is_zarr(labels)
+            else (None, None)
+        )
         viewer.add_labels(
             lab,
             name=labels_name,
             multiscale=isinstance(lab, list),
             scale=lab_scale,
+            units=lab_units,
             **label_kwargs,
         )
     elif _is_zarr(image):
@@ -341,11 +370,13 @@ def view_in_napari(
             store = f"{image}/labels/{name}"
             levels = _multiscale_levels(store, None)
             lab = [lvl.astype("int32") for lvl in levels]
+            lab_scale, lab_units = _pyramid_calibration(store, lab[0].ndim)
             viewer.add_labels(
                 lab,
                 name=name,
                 multiscale=True,
-                scale=_pyramid_scale(store, lab[0].ndim),
+                scale=lab_scale,
+                units=lab_units,
                 **label_kwargs,
             )
             logger.info("auto-loaded labels/%s from %s", name, image)

patchworks-0.11.19/tests/test_relations.py

@@ -0,0 +1,43 @@
+import dask.array as da
+import numpy as np
+import pytest
+
+from patchworks import label_relations
+
+
+def test_label_relations_majority_overlap():
+    # nucleus 1 sits fully inside cell 10; nucleus 2 straddles cells 20/21
+    # with more voxels in 20 -> should match 20, not 21.
+    a = np.zeros((4, 10), dtype=np.int32)
+    a[0:2, 0:2] = 1
+    a[0:2, 4:8] = 2
+    b = np.zeros((4, 10), dtype=np.int32)
+    b[0:3, 0:3] = 10
+    b[0:2, 4:6] = 20  # 4 voxels overlap with label 2
+    b[0:2, 6:8] = 21  # 4 voxels overlap with label 2 -> tie, but let's skew it
+    b[0:2, 6:7] = 20  # tip the tie: label 20 now has 6 voxels vs 21's 2
+
+    table = label_relations(da.from_array(a, chunks=(2, 5)), da.from_array(b, chunks=(2, 5)))
+
+    assert table[1]["match"] == 10
+    assert table[1]["overlap_voxels"] == 4
+    assert table[1]["overlap_fraction"] == 1.0
+
+    assert table[2]["match"] == 20
+    assert table[2]["overlap_voxels"] == 6
+
+
+def test_label_relations_no_overlap_omitted():
+    a = np.zeros((2, 2), dtype=np.int32)
+    a[0, 0] = 1
+    b = np.zeros((2, 2), dtype=np.int32)  # all background, no overlap anywhere
+
+    table = label_relations(da.from_array(a, chunks=(2, 2)), da.from_array(b, chunks=(2, 2)))
+    assert table == {}
+
+
+def test_label_relations_chunk_mismatch_raises():
+    a = da.zeros((4, 4), chunks=(2, 4), dtype=np.int32)
+    b = da.zeros((4, 4), chunks=(4, 4), dtype=np.int32)
+    with pytest.raises(ValueError, match="chunk layout"):
+        label_relations(a, b)

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/README.md

@@ -75,6 +75,26 @@ The GPU request lives in `profile/slurm/config.yaml` under
 `set-resources: segment:` (`--gres=gpu:1`). Raise `jobs:` to use more GPUs at
 once.
 
+## Multiple segmentations (nuclei + cytoplasm, …)
+
+Every intermediate path is namespaced under `work_dir/<label_name>/`, so
+running the workflow **twice with two configs** (different `label_name`,
+`channel`, `cellpose:`) against the **same `work_dir`** is safe — both reuse
+the one converted `image.zarr` and land side by side in
+`image.zarr/labels/<label_name>/`. See the
+[full guide](https://imcf.one/patchworks/guide/snakemake/#running-two-segmentations-eg-nuclei--cytoplasm)
+for the two-config recipe and `patchworks.label_relations()` for mapping one
+segmentation onto the other (e.g. nucleus → containing cell).
+
+One command instead of juggling several manual runs: list your configs (and
+which label pairs to relate) in `config/multi.yaml`, then:
+
+```bash
+pixi run multi-dry    # dry-run every segmentation config
+pixi run multi        # run locally
+pixi run multi-slurm  # submit every segmentation to SLURM
+```
+
 ## Output
 
 `<work_dir>/image.zarr` — the image plus `labels/<label_name>/` (multi-scale,

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/Snakefile

@@ -26,4 +26,4 @@ localrules:
 
 rule all:
     input:
-        f"{WORK}/labels.done",
+        f"{RUN}/labels.done",

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/config/config.yaml

@@ -30,6 +30,10 @@ empty_threshold: null # null → Otsu; or a number
 
 # ---- segmentation -----------------------------------------------------------
 method: "cellpose" # "cellpose" (GPU), "threshold" (no GPU; testing), "custom"
+# Also namespaces this run's intermediate files under work_dir/<label_name>/,
+# so a second segmentation (different label_name, e.g. nuclei vs cytoplasm)
+# can safely target the same work_dir — see docs/guide/snakemake.md
+# "Running two segmentations".
 label_name: "cellpose_labels"
 cellpose:
   model: "nuclei"

patchworks-0.11.19/workflow/config/config_cyto.yaml

@@ -0,0 +1,33 @@
+# Example segmentation config: cytoplasm/membrane channel.
+# Paired with config_nuclei.yaml via config/multi.yaml — see
+# docs/guide/snakemake.md "Running two segmentations". Same work_dir as
+# config_nuclei.yaml, and the same tile_shape so patchworks.label_relations()
+# can compare the two label arrays chunk-for-chunk.
+
+input: "/path/to/scan.ims"
+work_dir: "/path/to/results"
+
+reuse_pyramid: false
+convert_chunks: null
+shard: false
+
+channel: 0 # cytoplasm/membrane channel
+level: 0
+tile_shape: [16, 1024, 1024] # keep identical to config_nuclei.yaml
+gpu_memory_gb: null
+overlap: 30
+skip_empty: true
+empty_threshold: null
+
+method: "cellpose"
+label_name: "cyto_labels"
+cellpose:
+  model: "cyto3"
+  diameter: 30
+  do_3D: true
+  gpu: true
+
+pyramid_levels: 5
+pyramid_downscale: 2
+sequential_labels: true
+merge_workers: null

patchworks-0.11.19/workflow/config/config_nuclei.yaml

@@ -0,0 +1,33 @@
+# Example segmentation config: nuclei channel.
+# Paired with config_cyto.yaml via config/multi.yaml — see
+# docs/guide/snakemake.md "Running two segmentations". Both configs share
+# work_dir (and thus image.zarr) with config_cyto.yaml, but keep tile_shape
+# identical across the two so patchworks.label_relations() can compare them.
+
+input: "/path/to/scan.ims"
+work_dir: "/path/to/results"
+
+reuse_pyramid: false
+convert_chunks: null
+shard: false
+
+channel: 1 # nuclear stain channel
+level: 0
+tile_shape: [16, 1024, 1024] # keep identical to config_cyto.yaml
+gpu_memory_gb: null
+overlap: 30
+skip_empty: true
+empty_threshold: null
+
+method: "cellpose"
+label_name: "nuclei_labels"
+cellpose:
+  model: "nuclei"
+  diameter: 15
+  do_3D: true
+  gpu: true
+
+pyramid_levels: 5
+pyramid_downscale: 2
+sequential_labels: true
+merge_workers: null

patchworks-0.11.19/workflow/config/multi.yaml

@@ -0,0 +1,21 @@
+# Drives `pixi run multi` / `scripts/run_multi.py`: runs several segmentation
+# configs (in order) against the same work_dir, then relates their labels by
+# voxel overlap (patchworks.label_relations) and writes a CSV per pair.
+#
+# All listed segmentation configs must share the same work_dir/image.zarr and
+# the same tile_shape/level, so the resulting label arrays are directly
+# comparable — see docs/guide/snakemake.md "Running two segmentations".
+#
+# Both lists are plain lists: 3+ segmentations work the same way — add more
+# entries to `segmentations`, then list whichever pairs you want related in
+# `relations` (there's no automatic "chain"; list every pair explicitly, e.g.
+# nuclei->cyto, nuclei->membrane, cyto->membrane).
+
+segmentations:
+- config/config_nuclei.yaml
+- config/config_cyto.yaml
+
+relations:
+- a: nuclei_labels
+  b: cyto_labels
+  output: nuclei_to_cyto.csv

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/pixi.toml

@@ -1,8 +1,11 @@
 # pixi environment for the patchworks Snakemake workflow.
 #   pixi install
-#   pixi run dry      # dry-run (plan only)
-#   pixi run go       # run locally
-#   pixi run slurm    # submit to SLURM (edit profile/slurm/config.yaml first)
+#   pixi run dry          # dry-run (plan only)
+#   pixi run go           # run locally
+#   pixi run slurm        # submit to SLURM (edit profile/slurm/config.yaml first)
+#   pixi run multi        # run several segmentations + relate their labels (local)
+#   pixi run multi-slurm  # same, on SLURM
+#   pixi run multi-dry    # dry-run every segmentation in config/multi.yaml
 #
 # On a cluster, put this project on a shared filesystem the compute nodes can
 # read: the SLURM jobs re-launch snakemake from this env's interpreter.
@@ -38,3 +41,11 @@ cellpose4 = { features = ["cp4"], solve-group = "cp4" }
 dry = "snakemake -s Snakefile --configfile config/config.yaml --rerun-triggers mtime -n -p"
 go = "snakemake -s Snakefile --configfile config/config.yaml --rerun-triggers mtime --cores 8"
 slurm = "snakemake --workflow-profile profile/slurm --configfile config/config.yaml"
+
+# Run every segmentation config listed in config/multi.yaml (in order), then
+# relate their labels by voxel overlap (patchworks.label_relations) and write
+# a CSV per configured pair — see config/multi.yaml and
+# docs/guide/snakemake.md "Running two segmentations".
+multi-dry = "python scripts/run_multi.py --config config/multi.yaml -n"
+multi = "python scripts/run_multi.py --config config/multi.yaml"
+multi-slurm = "python scripts/run_multi.py --config config/multi.yaml --profile profile/slurm"

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/rules/common.smk

@@ -7,8 +7,17 @@ IMAGE = f"{WORK}/image.zarr"
 # directory) lets Snakemake skip conversion when the store already exists and
 # avoids wiping the whole store on a re-run (same trick as imcf/sopa).
 IMAGE_OK = f"{IMAGE}/zarr.json"
-TILES = f"{WORK}/tiles.json"
-STAGE = f"{WORK}/stage.zarr"
+
+# Everything below is per-segmentation, namespaced under WORK/<label_name>/, so
+# running the workflow twice with two configs (different label_name, e.g.
+# "nuclei_labels" and "cell_labels") against the *same* work_dir never
+# collides — each gets its own tiles/stage/seg/model/labels.done, and both
+# read the *same* already-converted image.zarr. See docs/guide/snakemake.md
+# "Running two segmentations" for the two-config recipe.
+LABEL_NAME = config.get("label_name", "labels")
+RUN = f"{WORK}/{LABEL_NAME}"
+TILES = f"{RUN}/tiles.json"
+STAGE = f"{RUN}/stage.zarr"
 # Completion sentinel for the stage store. Tracking a touch()ed marker instead
 # of directory(STAGE) keeps Snakemake from deleting/recreating the store on a
 # re-run and avoids directory-mtime quirks (same touch() discipline as sopa).
@@ -17,16 +26,18 @@ STAGE_OK = f"{STAGE}.done"
 
 # Logs: one shared file for the sequential CPU steps (convert/prepare/merge),
 # one file per tile for the GPU segment jobs.
-LOGS = f"{WORK}/logs"
+LOGS = f"{RUN}/logs"
 STEPLOG = f"{LOGS}/steps.log"
 
 # Marker that the segmentation model is cached locally. Produced by a local
 # rule (runs on the networked submit host) so offline GPU nodes never download.
-MODEL_OK = f"{WORK}/model.ready"
+# Namespaced per-run too: two configs using different models must each fetch
+# their own, rather than the second silently reusing the first's marker.
+MODEL_OK = f"{RUN}/model.ready"
 
 
 def occupied_done(wildcards):
     """Per-tile markers for the occupied tiles (resolved after the checkpoint)."""
     tiles = checkpoints.prepare.get().output.tiles
     occupied = json.loads(Path(tiles).read_text())["occupied"]
-    return [f"{WORK}/seg/{i}.done" for i in occupied]
+    return [f"{RUN}/seg/{i}.done" for i in occupied]

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/rules/merge.smk

@@ -4,7 +4,7 @@ rule merge:
     input:
         occupied_done,
     output:
-        touch(f"{WORK}/labels.done"),
+        touch(f"{RUN}/labels.done"),
     log:
         STEPLOG,
     script:

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/rules/segment.smk

@@ -35,7 +35,7 @@ rule segment:
         image=IMAGE_OK,
         model=MODEL_OK,
     output:
-        f"{WORK}/seg/{{index}}.done",
+        f"{RUN}/seg/{{index}}.done",
     log:
         f"{LOGS}/segment/{{index}}.log",
     script:

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/scripts/_pw.py

@@ -87,20 +87,26 @@ def open_image(work_dir, channel, level):
     )
 
 
-def stage_path(work_dir):
-    """Path of the staged-labels store.
+def stage_path(work_dir, label_name):
+    """Path of the staged-labels store for one segmentation run.
+
+    Namespaced under ``<work_dir>/<label_name>/`` so two segmentations
+    (different ``label_name``) can target the same ``work_dir`` without
+    colliding — see docs/guide/snakemake.md "Running two segmentations".
 
     Parameters
     ----------
     work_dir : str or Path
         Workflow output directory.
+    label_name : str
+        This run's ``label_name`` (from config).
 
     Returns
     -------
     str
-        ``<work_dir>/stage.zarr``.
+        ``<work_dir>/<label_name>/stage.zarr``.
     """
-    return str(Path(work_dir) / "stage.zarr")
+    return str(Path(work_dir) / label_name / "stage.zarr")
 
 
 def load_tiles_json(path):

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/scripts/merge.py

@@ -17,16 +17,19 @@ from _pw import stage_path, start_log
 start_log(snakemake.log[0])  # noqa: F821
 cfg = snakemake.config  # noqa: F821
 work_dir = cfg["work_dir"]
+label_name = cfg.get("label_name", "labels")
 image_store = str(Path(work_dir) / "image.zarr")
-merged_store = str(Path(work_dir) / "_merged.zarr")
+merged_store = str(Path(work_dir) / label_name / "_merged.zarr")
 
 # merge_tile_labels defaults to min(4, cpu_count) workers, so it ignores
 # whatever cpus_per_task the "merge" rule was actually allocated in the SLURM
 # profile. Read the real allocation (SLURM_CPUS_PER_TASK) so the job uses all
 # the cores it's paying for; merge_workers: in config.yaml can still override.
-default_workers = int(os.environ.get("SLURM_CPUS_PER_TASK", os.cpu_count() or 4))
+default_workers = int(
+    os.environ.get("SLURM_CPUS_PER_TASK", os.cpu_count() or 4)
+)
 merged = merge_tile_labels(
-    stage_path(work_dir),
+    stage_path(work_dir, label_name),
     write_to=merged_store,
     input_component="staged",
     sequential_labels=cfg.get("sequential_labels", True),
@@ -36,18 +39,18 @@ merged = merge_tile_labels(
 group = write_labels(
     image_store,
     merged,
-    name=cfg.get("label_name", "labels"),
+    name=label_name,
     n_levels=int(cfg.get("pyramid_levels", 5)),
     downscale=int(cfg.get("pyramid_downscale", 2)),
     overwrite=True,
 )
 
 shutil.rmtree(merged_store, ignore_errors=True)
-shutil.rmtree(stage_path(work_dir), ignore_errors=True)
+shutil.rmtree(stage_path(work_dir, label_name), ignore_errors=True)
 # Also drop the checkpoint's completion sentinel (stage.zarr.done): the
 # "prepare" rule's stage=touch(STAGE_OK) output must not outlive the store it
 # claims exists, or a future rerun (e.g. re-segmenting for new labels) skips
 # "prepare" and "segment" tries to open a stage.zarr that's already gone.
-Path(f"{stage_path(work_dir)}.done").unlink(missing_ok=True)
+Path(f"{stage_path(work_dir, label_name)}.done").unlink(missing_ok=True)
 print(f"[patchworks] labels written to {group}")
 open(snakemake.output[0], "w").close()  # noqa: F821

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/scripts/prepare_tiles.py

@@ -16,6 +16,8 @@ from _pw import open_image, stage_path, start_log
 start_log(snakemake.log[0])  # noqa: F821
 cfg = snakemake.config  # noqa: F821
 work_dir = cfg["work_dir"]
+label_name = cfg.get("label_name", "labels")
+Path(work_dir, label_name).mkdir(parents=True, exist_ok=True)
 image = open_image(work_dir, cfg["channel"], cfg["level"])
 
 ts = cfg.get("tile_shape", "auto")
@@ -46,9 +48,9 @@ if cfg.get("skip_empty", True):
     occ = info["occupancy"].ravel()  # row-major, matches spatial_tiles
     occupied = [i for i in range(len(tiles)) if occ[i]]
 
-create_stage(stage_path(work_dir), image.shape, tile_shape)
+create_stage(stage_path(work_dir, label_name), image.shape, tile_shape)
 
-Path(work_dir, "tiles.json").write_text(
+Path(work_dir, label_name, "tiles.json").write_text(
     json.dumps(
         {
             "tile_shape": list(tile_shape),

patchworks-0.11.19/workflow/scripts/run_multi.py

@@ -0,0 +1,160 @@
+"""Run several segmentation configs, then relate their labels by overlap.
+
+Usage:
+    python scripts/run_multi.py --config config/multi.yaml
+    python scripts/run_multi.py --config config/multi.yaml --profile profile/slurm
+    python scripts/run_multi.py --config config/multi.yaml -n   # dry-run only
+
+See config/multi.yaml and docs/guide/snakemake.md "Running two segmentations"
+for the config format. Each listed segmentation config is run as an ordinary
+`snakemake --configfile ...` invocation (this script is a thin sequencer, not
+a Snakemake rule — the segmentations already namespace their own paths under
+work_dir/<label_name>/, so running them one after another here is exactly
+equivalent to running each snakemake command by hand). Once all segmentations
+finish, each configured relation pair is computed via
+patchworks.label_relations and written as a CSV in work_dir.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def _load_yaml(path: Path) -> dict:
+    return yaml.safe_load(path.read_text())
+
+
+def _run_snakemake(
+    configfile: Path,
+    *,
+    workflow_dir: Path,
+    profile: str | None,
+    cores: int,
+    dry_run: bool,
+) -> None:
+    cmd = [
+        "snakemake",
+        "-s",
+        str(workflow_dir / "Snakefile"),
+        "--configfile",
+        str(configfile),
+    ]
+    if profile:
+        cmd += ["--workflow-profile", profile]
+    else:
+        cmd += ["--cores", str(cores), "--rerun-triggers", "mtime"]
+    if dry_run:
+        cmd += ["-n", "-p"]
+    print(f"[run_multi] $ {' '.join(cmd)}", flush=True)
+    subprocess.run(cmd, check=True, cwd=workflow_dir)
+
+
+def _resolve(workflow_dir: Path, path_str: str) -> Path:
+    path = Path(path_str)
+    return path if path.is_absolute() else workflow_dir / path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--config", required=True, help="multi-segmentation config YAML"
+    )
+    parser.add_argument(
+        "--profile",
+        default=None,
+        help="Snakemake --workflow-profile (e.g. profile/slurm); omit to run locally",
+    )
+    parser.add_argument(
+        "--cores",
+        type=int,
+        default=8,
+        help="local run: --cores (ignored with --profile)",
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="pass -n -p to every Snakemake run; skips relations",
+    )
+    args = parser.parse_args()
+
+    workflow_dir = Path(__file__).resolve().parent.parent
+    multi_cfg_path = _resolve(workflow_dir, args.config)
+    multi_cfg = _load_yaml(multi_cfg_path)
+
+    seg_config_paths = [
+        _resolve(workflow_dir, c) for c in multi_cfg["segmentations"]
+    ]
+    for cfg_path in seg_config_paths:
+        _run_snakemake(
+            cfg_path,
+            workflow_dir=workflow_dir,
+            profile=args.profile,
+            cores=args.cores,
+            dry_run=args.dry_run,
+        )
+
+    relations = multi_cfg.get("relations", [])
+    if args.dry_run or not relations:
+        return
+
+    seg_cfgs = [_load_yaml(p) for p in seg_config_paths]
+    work_dirs = {cfg["work_dir"] for cfg in seg_cfgs}
+    if len(work_dirs) != 1:
+        print(
+            f"[run_multi] ERROR: segmentation configs use different work_dir "
+            f"({sorted(work_dirs)}); label_relations needs one shared "
+            "image.zarr to compare against.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    work_dir = work_dirs.pop()
+    image_store = f"{work_dir}/image.zarr"
+
+    import dask.array as da
+
+    from patchworks import label_relations
+
+    for rel in relations:
+        a_name, b_name = rel["a"], rel["b"]
+        out_path = Path(work_dir) / rel.get(
+            "output", f"{a_name}_to_{b_name}.csv"
+        )
+        print(f"[run_multi] relating {a_name} -> {b_name} …", flush=True)
+        a = da.from_zarr(image_store, component=f"labels/{a_name}/0")
+        b = da.from_zarr(image_store, component=f"labels/{b_name}/0")
+        table = label_relations(a, b)
+
+        with open(out_path, "w", newline="") as f:
+            writer = csv.writer(f)
+            writer.writerow(
+                [
+                    f"{a_name}_id",
+                    f"{b_name}_id",
+                    "overlap_voxels",
+                    "overlap_fraction",
+                ]
+            )
+            for a_id, m in table.items():
+                writer.writerow(
+                    [
+                        a_id,
+                        m["match"],
+                        m["overlap_voxels"],
+                        m["overlap_fraction"],
+                    ]
+                )
+        print(f"[run_multi] wrote {out_path} ({len(table)} rows)", flush=True)
+
+
+if __name__ == "__main__":
+    main()

{patchworks-0.11.17 → patchworks-0.11.19}/workflow/scripts/segment_tile.py

@@ -12,6 +12,7 @@ start_log(snakemake.log[0])  # noqa: F821
 cfg = snakemake.config  # noqa: F821
 index = int(snakemake.wildcards.index)  # noqa: F821
 work_dir = cfg["work_dir"]
+label_name = cfg.get("label_name", "labels")
 
 manifest = load_tiles_json(snakemake.input.tiles)  # noqa: F821
 image = open_image(work_dir, cfg["channel"], cfg["level"])
@@ -19,7 +20,7 @@ image = open_image(work_dir, cfg["channel"], cfg["level"])
 stage_tile(
     image,
     build_fn(cfg),
-    stage_path(work_dir),
+    stage_path(work_dir, label_name),
     index,
     tile_shape=tuple(manifest["tile_shape"]),
     overlap=int(manifest["overlap"]),