patchworks 2.6.8__tar.gz → 2.6.10__tar.gz

{patchworks-2.6.8 → patchworks-2.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 2.6.8
+Version: 2.6.10
 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

{patchworks-2.6.8 → patchworks-2.6.10}/docs/api/plugins/cellpose.md

@@ -1,3 +1,5 @@
 # Cellpose plugin
 
 ::: patchworks.plugins.cellpose.cellpose_fn
+
+::: patchworks.plugins.cellpose.cellpose_anisotropy

patchworks-2.6.10/docs/api/volume_filter.md

@@ -0,0 +1,9 @@
+# Volume filtering
+
+::: patchworks.filter_labels_by_size
+
+::: patchworks.voxel_volume
+
+::: patchworks.min_voxels_for_volume
+
+::: patchworks.max_voxels_for_volume

{patchworks-2.6.8 → patchworks-2.6.10}/docs/examples/cellpose_3d.md

@@ -14,19 +14,19 @@ plane orientations and takes a 3-D consensus.
 from functools import partial
 from patchworks import auto_tile_shape_cellpose, make_local_cluster, tile_process
 from patchworks.plugins.cellpose import cellpose_fn
+from patchworks.plugins.ome_zarr import read_pixel_size
 
 IMAGE = "image.zarr"
 OUTPUT = "labels_3d.zarr"
 CHANNEL = 0
 DIAMETER = 20  # pixels
-ANISOTROPY = 3.0  # z_spacing / xy_spacing
 
 fn = cellpose_fn(
     "cyto3",
     gpu=True,
     do_3D=True,
     diameter=DIAMETER,
-    anisotropy=ANISOTROPY,
+    voxel_size=read_pixel_size(IMAGE),  # -> anisotropy = z / lateral
 )
 
 # Tile shape: full z, xy tiled for memory
@@ -59,6 +59,15 @@ finally:
     cluster.close()
 ```
 
+!!! tip "Anisotropy is derived from the calibration, not retyped"
+    `do_3D` without `anisotropy` assumes isotropic voxels, which fragments
+    objects across z for any real (anisotropic) dataset. Passing
+    `voxel_size` derives it as `z / lateral` via
+    [`cellpose_anisotropy`](../api/plugins/cellpose.md) instead of keeping a
+    second, driftable copy of the calibration in code. An explicit
+    `anisotropy=` still wins if you pass one. The Snakemake workflow does
+    this automatically — see [Configure the run](../guide/snakemake.md#3-configure-the-run).
+
 ## Memory notes
 
 In `do_3D=True` mode, each tile has shape `(z_full, y_tile, x_tile)`.

{patchworks-2.6.8 → patchworks-2.6.10}/docs/examples/cellpose_3d.py

@@ -12,19 +12,19 @@ from patchworks import (
     tile_process,
 )
 from patchworks.plugins.cellpose import cellpose_fn
+from patchworks.plugins.ome_zarr import read_pixel_size
 
 IMAGE = "image.zarr"
 OUTPUT = "labels_3d.zarr"
 CHANNEL = 0
 DIAMETER = 20  # pixels
-ANISOTROPY = 3.0  # z-spacing / xy-spacing
 
 fn = cellpose_fn(
     "cyto3",
     gpu=True,
     do_3D=True,
     diameter=DIAMETER,
-    anisotropy=ANISOTROPY,
+    voxel_size=read_pixel_size(IMAGE),  # -> anisotropy = z / lateral
 )
 
 tile_fn = partial(

{patchworks-2.6.8 → patchworks-2.6.10}/docs/guide/merging.md

@@ -133,6 +133,59 @@ merged = merge_tile_labels(
 )
 ```
 
+## Filtering by size after merge
+
+Once labels are globally consistent, [`filter_labels_by_size`](../api/volume_filter.md)
+can drop objects outside a voxel-count range, in place — too small, too large,
+or both:
+
+```python
+from patchworks import filter_labels_by_size, merge_tile_labels
+
+merged = merge_tile_labels("stage.zarr", write_to="labels.zarr", sequential_labels=True)
+# drop anything under 500 voxels, over 50000, or both -- give either bound alone
+n_kept, n_removed = filter_labels_by_size(
+    "labels.zarr", "labels", min_voxels=500, max_voxels=50000
+)
+```
+
+This has to run **after** the merge, not per tile: a tile only sees whatever
+fragment of an object landed inside its own bounds, so a per-tile filter would
+judge (and possibly drop) an object crossing a tile boundary as if it were
+only that fragment's size — including judging it too *large*, for a
+`max_voxels` filter, when several separate objects in one tile would in fact
+merge back into one across the boundary.
+
+Like the merge itself, it is a two-pass streaming zarr scan — the array never
+has to fit in RAM. `relabel=True` (the default) folds the size filter into
+the same lookup table that renumbers survivors to a contiguous `1..N` range,
+so dropping out-of-range objects costs no extra pass over the volume beyond
+the scan that already counts them.
+
+Physical thresholds (µm³) convert to a voxel count via
+[`min_voxels_for_volume`](../api/volume_filter.md)/[`max_voxels_for_volume`](../api/volume_filter.md),
+using the same `{"z": .., "y": .., "x": ..}` calibration deconvolution and
+Cellpose's `anisotropy` are derived from. The two round in opposite
+directions — `min_voxels_for_volume` rounds up (an object must *reach* the
+threshold), `max_voxels_for_volume` rounds down (an object must not *exceed*
+it):
+
+```python
+from patchworks import max_voxels_for_volume, min_voxels_for_volume
+from patchworks.plugins.ome_zarr import read_pixel_size
+
+voxel_size = read_pixel_size("image.zarr")
+min_voxels = min_voxels_for_volume(5.0, voxel_size)
+max_voxels = max_voxels_for_volume(500.0, voxel_size)
+n_kept, n_removed = filter_labels_by_size(
+    "labels.zarr", "labels", min_voxels, max_voxels
+)
+```
+
+On the cluster, set `min_volume: 5.0`/`max_volume: 500.0` in the config
+instead — see [Configure the run](snakemake.md#3-configure-the-run). Either
+or both run automatically between `merge` and the pyramid build.
+
 ## Sequential label numbering
 
 By default, merged labels are globally unique but may be **gappy** — boundary

{patchworks-2.6.8 → patchworks-2.6.10}/docs/guide/snakemake.md

@@ -68,12 +68,16 @@ method: "cellpose"             # "cellpose" (GPU), "threshold" (no GPU), "custom
 label_name: "cellpose"         # name under image.zarr/labels/
 dilate: 0                      # optional: pixels to grow labels by, any method
 dilate_gpu: false               # dilate via cupy instead of scipy (needs a GPU)
+min_volume: null               # optional: drop objects smaller than this many µm³
+max_volume: null               # optional: drop objects larger than this many µm³
 cellpose:
   model: "cyto3"
   diameter: 30
   do_3D: true
   gpu: true
   # extra model.eval() kwargs, e.g. flow_threshold: 0.4
+  # anisotropy: 2.2   # optional: overrides the value derived automatically
+  #                   # from image.zarr's calibration for do_3D (see tip below)
 
 # label pyramid
 pyramid_levels: 5
@@ -94,6 +98,29 @@ sequential_labels: true        # renumber labels to a contiguous 1..N
     labels afterwards](custom_segmentation.md#growing-labels-afterwards-dilation)
     for how it works and the equivalent direct-API call.
 
+!!! tip "Dropping objects by size with `min_volume`/`max_volume`"
+    `min_volume: N` drops any object smaller than `N` µm³; `max_volume: N`
+    drops any object larger than `N` µm³ (e.g. several objects merged into
+    one blob). Set either, both, or neither (`null`, the default, disables
+    each). Both run once on the **fully merged** image — not per tile, where
+    an object crossing a tile boundary would look smaller or larger than it
+    really is. Runs after `merge` and before the pyramid is built, so every
+    pyramid level reflects the filtered result, and needs `image.zarr` to
+    carry a pixel size (the same calibration deconvolution's voxel sizes and
+    Cellpose's `anisotropy` are derived from — see the tip below); an
+    uncalibrated store raises rather than silently skipping the filter. See
+    [Filtering by size after merge](merging.md#filtering-by-size-after-merge)
+    for the equivalent direct-API call.
+
+!!! tip "3-D anisotropy is derived automatically"
+    Cellpose's `do_3D` assumes isotropic voxels unless told otherwise —
+    without an `anisotropy`, a real (anisotropic) dataset gets objects
+    fragmented or distorted across z. `segment` now derives it from
+    `image.zarr`'s own calibration (`z` voxel size ÷ lateral voxel size)
+    whenever `do_3D: true` and `cellpose.anisotropy` isn't set explicitly, so
+    there's usually nothing to configure. Set `anisotropy:` yourself in the
+    `cellpose:` block to override it.
+
 !!! tip "Tile size vs runtime"
     `tile_shape: "auto"` sizes each tile to your GPU's VRAM. Smaller tiles =
     more (faster) jobs; very large 3-D tiles are slow. Keep `do_3D: false` (2-D

{patchworks-2.6.8 → patchworks-2.6.10}/mkdocs.yml

@@ -58,6 +58,7 @@ nav:
   - tile_process: api/tile_process.md
   - merge_tile_labels: api/merge_tile_labels.md
   - dilate_labels: api/postprocess.md
+  - Volume filtering: api/volume_filter.md
   - Tile sizing: api/chunks.md
   - I/O helpers: api/io.md
   - Relabelling: api/relabel.md

{patchworks-2.6.8 → patchworks-2.6.10}/src/patchworks/__init__.py

@@ -55,6 +55,12 @@ from ._occupancy import (
 from ._postprocess import dilate_labels
 from ._relabel import relabel_sequential_array, relabel_sequential_zarr
 from ._relations import label_relations
+from ._volume_filter import (
+    filter_labels_by_size,
+    max_voxels_for_volume,
+    min_voxels_for_volume,
+    voxel_volume,
+)
 
 try:
     __version__ = _pkg_version("patchworks")
@@ -85,4 +91,8 @@ __all__ = [
     "create_stage",
     "stage_tile",
     "dilate_labels",
+    "filter_labels_by_size",
+    "min_voxels_for_volume",
+    "max_voxels_for_volume",
+    "voxel_volume",
 ]

patchworks-2.6.10/src/patchworks/_volume_filter.py

@@ -0,0 +1,249 @@
+"""Drop label objects outside a size range, in place, after merge.
+
+Meant to run once, globally, on the fully merged label array -- not per
+tile, where an object's true size isn't known yet (a tile only sees
+whatever fragment of it landed inside that tile's bounds, so a per-tile
+filter would clip or drop objects that are only small, or only large,
+*within one tile*).
+
+Two-pass streaming algorithm, mirroring :func:`patchworks.relabel_sequential_zarr`
+-- safe for arrays far larger than RAM. Pass 1 does a chunk-wise
+unique+count to get every label's voxel count (bounded memory: a Python
+dict keyed by label id, not the voxels themselves). Pass 2 builds a LUT
+that zeroes labels outside ``[min_voxels, max_voxels]`` -- optionally
+renumbering the survivors to a contiguous range in the same pass -- and
+applies it chunk by chunk, writing back into the same store.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from itertools import product as _iproduct
+
+import numpy as np
+import zarr
+
+logger = logging.getLogger(__name__)
+
+_LUT_WARN_THRESHOLD = 100_000_000  # warn when max_label > 100 M (LUT > 800 MB)
+
+
+def voxel_volume(voxel_size: "dict[str, float]") -> float:
+    """Physical volume of one voxel, from a per-axis calibration.
+
+    Axes missing from *voxel_size* are treated as 1.0 -- e.g. a 2-D
+    calibration with no ``z`` gives an area, not a bogus volume shrunk by a
+    fake axis. Units follow whatever *voxel_size* is in (micrometers for
+    :func:`patchworks.plugins.ome_zarr.read_pixel_size`).
+
+    Parameters
+    ----------
+    voxel_size : dict
+        Per-axis physical size, e.g. ``{"z": .., "y": .., "x": ..}``.
+
+    Returns
+    -------
+    float
+        Product of the given axis sizes.
+
+    Examples
+    --------
+    >>> voxel_volume({"z": 0.24, "y": 0.10833, "x": 0.10833})
+    0.0028164933359999997
+    """
+    vol = 1.0
+    for size in voxel_size.values():
+        vol *= size
+    return vol
+
+
+def min_voxels_for_volume(
+    min_volume: float, voxel_size: "dict[str, float]"
+) -> int:
+    """Convert a physical volume threshold to a voxel count.
+
+    Rounds up: an object must reach *min_volume* to survive, so a partial
+    voxel's worth of extra volume should not tip it over the line.
+
+    Parameters
+    ----------
+    min_volume : float
+        Minimum object volume to keep, in the same physical units as
+        *voxel_size* (micrometers³ for an NGFF calibration).
+    voxel_size : dict
+        Per-axis physical size -- see :func:`voxel_volume`.
+
+    Returns
+    -------
+    int
+        Minimum voxel count for an object to survive filtering.
+
+    Examples
+    --------
+    >>> min_voxels_for_volume(5.0, {"z": 0.24, "y": 0.10833, "x": 0.10833})
+    1776
+    """
+    return math.ceil(min_volume / voxel_volume(voxel_size))
+
+
+def max_voxels_for_volume(
+    max_volume: float, voxel_size: "dict[str, float]"
+) -> int:
+    """Convert a physical volume threshold to a voxel count.
+
+    Rounds down, the mirror image of :func:`min_voxels_for_volume`: an
+    object must not *exceed* *max_volume*, so a voxel count whose volume
+    would tip past it must not survive.
+
+    Parameters
+    ----------
+    max_volume : float
+        Maximum object volume to keep, in the same physical units as
+        *voxel_size* (micrometers³ for an NGFF calibration).
+    voxel_size : dict
+        Per-axis physical size -- see :func:`voxel_volume`.
+
+    Returns
+    -------
+    int
+        Maximum voxel count for an object to survive filtering.
+
+    Examples
+    --------
+    >>> max_voxels_for_volume(5.0, {"z": 0.24, "y": 0.10833, "x": 0.10833})
+    1775
+    """
+    return math.floor(max_volume / voxel_volume(voxel_size))
+
+
+def _chunk_slices(shape, chunks):
+    """Every zarr chunk's index expression, in all dimensions.
+
+    Iterating actual chunk boundaries (rather than z-slabs) keeps each read
+    bounded to one chunk's worth of memory, whatever the array's shape.
+    """
+    n_per_dim = [(s + c - 1) // c for s, c in zip(shape, chunks)]
+    return [
+        tuple(
+            slice(i * c, min((i + 1) * c, s))
+            for i, c, s in zip(idx, chunks, shape)
+        )
+        for idx in _iproduct(*[range(n) for n in n_per_dim])
+    ]
+
+
+def filter_labels_by_size(
+    store_path: str,
+    component: str,
+    min_voxels: "int | None" = None,
+    max_voxels: "int | None" = None,
+    *,
+    relabel: bool = True,
+) -> "tuple[int, int]":
+    """Drop label objects outside ``[min_voxels, max_voxels]``, in place.
+
+    Two-pass streaming scan (see module docstring) -- the array never has
+    to fit in RAM.
+
+    Parameters
+    ----------
+    store_path : str
+        Path to the zarr store containing the label array.
+    component : str
+        Array name inside the store to filter in place.
+    min_voxels : int, optional
+        Objects with fewer voxels than this are zeroed (dropped). ``None``
+        (default) sets no lower bound. Use :func:`min_voxels_for_volume` to
+        derive this from a physical volume and calibration.
+    max_voxels : int, optional
+        Objects with more voxels than this are zeroed (dropped) -- e.g. a
+        segmentation artifact where several objects merged into one giant
+        blob. ``None`` (default) sets no upper bound. Use
+        :func:`max_voxels_for_volume` to derive this from a physical volume
+        and calibration.
+    relabel : bool, optional
+        Renumber the surviving objects to a contiguous ``1..N`` range in
+        the same LUT that drops the out-of-range ones (default ``True``)
+        -- otherwise the removed ids leave permanent gaps and survivors
+        keep their original ids.
+
+    Returns
+    -------
+    tuple of int
+        ``(n_kept, n_removed)``.
+
+    Examples
+    --------
+    >>> import zarr
+    >>> root = zarr.open_group("labels.zarr", mode="w")  # doctest: +SKIP
+    >>> root.create_array(
+    ...     "labels", shape=(4, 4), chunks=(4, 4), dtype="int32"
+    ... )[:] = [
+    ...     [0, 1, 1, 0],
+    ...     [0, 1, 1, 0],
+    ...     [0, 0, 0, 2],
+    ...     [0, 0, 0, 0],
+    ... ]  # doctest: +SKIP
+    >>> filter_labels_by_size("labels.zarr", "labels", min_voxels=2)  # doctest: +SKIP
+    (1, 1)
+    """
+    if min_voxels is None and max_voxels is None:
+        raise ValueError(
+            "filter_labels_by_size needs min_voxels, max_voxels, or both"
+        )
+
+    root = zarr.open_group(store_path, mode="r+")
+    z = root[component]
+    slices = _chunk_slices(z.shape, z.chunks)
+
+    counts: "dict[int, int]" = {}
+    for sl in slices:
+        ids, n = np.unique(np.asarray(z[sl]), return_counts=True)
+        for label_id, count in zip(ids.tolist(), n.tolist()):
+            if label_id == 0:
+                continue
+            counts[label_id] = counts.get(label_id, 0) + count
+
+    kept = sorted(
+        i
+        for i, c in counts.items()
+        if (min_voxels is None or c >= min_voxels)
+        and (max_voxels is None or c <= max_voxels)
+    )
+    n_kept = len(kept)
+    n_removed = len(counts) - n_kept
+
+    # Sized to the largest id *seen*, not just the largest surviving one --
+    # a removed object's id can still exceed every kept id and must stay
+    # in bounds so the LUT gather below maps it to 0 rather than indexing
+    # past the end.
+    max_label = max(counts) if counts else 0
+    if max_label > _LUT_WARN_THRESHOLD:
+        logger.warning(
+            "filter_labels_by_size: max_label=%d -> LUT size ~%.0f MB.",
+            max_label,
+            max_label * 8 / 1024**2,
+        )
+    lut = np.zeros(max_label + 1, dtype=np.int64)
+    if kept:
+        lut[kept] = np.arange(1, n_kept + 1) if relabel else np.asarray(kept)
+
+    max_out = n_kept if relabel else max_label
+    out_dtype = np.uint16 if max_out < np.iinfo(np.uint16).max else np.uint32
+    for sl in slices:
+        block = np.asarray(z[sl])
+        z[sl] = lut[block].astype(out_dtype)
+
+    bounds = "-".join(
+        str(v) if v is not None else "" for v in (min_voxels, max_voxels)
+    )
+    logger.info(
+        "filter_labels_by_size: dropped %d/%d object(s) outside [%s] voxels, "
+        "%d remain",
+        n_removed,
+        len(counts),
+        bounds,
+        n_kept,
+    )
+    return n_kept, n_removed

patchworks-2.6.10/tests/test_pw.py

@@ -0,0 +1,123 @@
+"""Tests for workflow/scripts/_pw.py's config-to-segmentation-function wiring."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(
+    0, str(Path(__file__).resolve().parents[1] / "workflow" / "scripts")
+)
+
+import numpy as np  # noqa: E402
+
+
+def test_with_voxel_size_fills_in_cellposes_calibration(tmp_path):
+    """The same auto-fill a custom function's voxel_size gets (see
+
+    _with_voxel_size's docstring) must also reach cellpose_fn, or do_3D
+    silently assumes isotropic voxels -- fragmenting objects across z for
+    any real (anisotropic) calibration. This checks the actual calibration
+    read + injection against a real store, not just that the parameter
+    exists (see test_cellpose.py for that).
+    """
+    from _pw import _with_voxel_size
+    from patchworks.plugins.cellpose import cellpose_fn
+    from patchworks.plugins.ome_zarr import to_ome_zarr
+
+    arr = np.zeros((4, 8, 8), dtype="uint16")
+    to_ome_zarr(
+        arr,
+        str(tmp_path / "image.zarr"),
+        axes="zyx",
+        pixel_size={"z": 0.24, "y": 0.10833, "x": 0.10833},
+        n_levels=1,
+        progress=False,
+    )
+    cfg = {"work_dir": str(tmp_path)}
+
+    kwargs = _with_voxel_size(cellpose_fn, {}, cfg)
+
+    assert kwargs["voxel_size"]["z"] == 0.24
+    assert kwargs["voxel_size"]["x"] == 0.10833
+
+
+def test_with_voxel_size_never_overrides_an_explicit_value(tmp_path):
+    """An explicit voxel_size must win, and win *cheaply*: no image.zarr
+
+    exists in work_dir at all here, so if this read past the early return it
+    would raise, not just return the wrong value.
+    """
+    from _pw import _with_voxel_size
+    from patchworks.plugins.cellpose import cellpose_fn
+
+    cfg = {"work_dir": str(tmp_path)}
+    explicit = {"z": 1.0, "y": 1.0, "x": 1.0}
+
+    kwargs = _with_voxel_size(cellpose_fn, {"voxel_size": explicit}, cfg)
+
+    assert kwargs["voxel_size"] == explicit
+
+
+def test_validate_config_accepts_a_positive_min_volume():
+    from _pw import validate_config
+
+    validate_config({"method": "threshold", "min_volume": 5.0})
+
+
+def test_validate_config_accepts_no_min_volume():
+    from _pw import validate_config
+
+    validate_config({"method": "threshold"})
+    validate_config({"method": "threshold", "min_volume": None})
+
+
+def test_validate_config_rejects_a_non_positive_min_volume():
+    import pytest
+    from _pw import validate_config
+
+    with pytest.raises(ValueError, match="min_volume"):
+        validate_config({"method": "threshold", "min_volume": 0})
+    with pytest.raises(ValueError, match="min_volume"):
+        validate_config({"method": "threshold", "min_volume": -1.0})
+    with pytest.raises(ValueError, match="min_volume"):
+        validate_config({"method": "threshold", "min_volume": "5"})
+
+
+def test_validate_config_accepts_a_positive_max_volume():
+    from _pw import validate_config
+
+    validate_config({"method": "threshold", "max_volume": 500.0})
+    validate_config({"method": "threshold", "max_volume": None})
+
+
+def test_validate_config_rejects_a_non_positive_max_volume():
+    import pytest
+    from _pw import validate_config
+
+    with pytest.raises(ValueError, match="max_volume"):
+        validate_config({"method": "threshold", "max_volume": 0})
+    with pytest.raises(ValueError, match="max_volume"):
+        validate_config({"method": "threshold", "max_volume": -1.0})
+    with pytest.raises(ValueError, match="max_volume"):
+        validate_config({"method": "threshold", "max_volume": "5"})
+
+
+def test_validate_config_accepts_max_volume_above_min_volume():
+    from _pw import validate_config
+
+    validate_config(
+        {"method": "threshold", "min_volume": 5.0, "max_volume": 500.0}
+    )
+
+
+def test_validate_config_rejects_max_volume_at_or_below_min_volume():
+    import pytest
+    from _pw import validate_config
+
+    with pytest.raises(ValueError, match="max_volume"):
+        validate_config(
+            {"method": "threshold", "min_volume": 5.0, "max_volume": 5.0}
+        )
+    with pytest.raises(ValueError, match="max_volume"):
+        validate_config(
+            {"method": "threshold", "min_volume": 500.0, "max_volume": 5.0}
+        )