patchworks 2.6.8__tar.gz → 2.6.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 2.6.8
+Version: 2.6.9
 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.9}/src/patchworks/__init__.py

@@ -55,6 +55,11 @@ 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,
+    min_voxels_for_volume,
+    voxel_volume,
+)
 
 try:
     __version__ = _pkg_version("patchworks")
@@ -85,4 +90,7 @@ __all__ = [
     "create_stage",
     "stage_tile",
     "dilate_labels",
+    "filter_labels_by_size",
+    "min_voxels_for_volume",
+    "voxel_volume",
 ]

patchworks-2.6.9/src/patchworks/_volume_filter.py

@@ -0,0 +1,198 @@
+"""Drop label objects below a volume threshold, 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 *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 under the threshold -- 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 _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,
+    *,
+    relabel: bool = True,
+) -> "tuple[int, int]":
+    """Drop label objects smaller than *min_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
+        Objects with fewer voxels than this are zeroed (dropped). Use
+        :func:`min_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 small 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)
+    """
+    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 c >= min_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)
+
+    logger.info(
+        "filter_labels_by_size: dropped %d/%d object(s) under %d voxels, "
+        "%d remain",
+        n_removed,
+        len(counts),
+        min_voxels,
+        n_kept,
+    )
+    return n_kept, n_removed

{patchworks-2.6.8 → patchworks-2.6.9}/tests/test_pw.py

@@ -55,3 +55,28 @@ def test_with_voxel_size_never_overrides_an_explicit_value(tmp_path):
     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"})

patchworks-2.6.9/tests/test_volume_filter.py

@@ -0,0 +1,135 @@
+"""Tests for the global, post-merge label volume filter."""
+
+import numpy as np
+import zarr
+
+
+def test_voxel_volume_multiplies_given_axes():
+    from patchworks import voxel_volume
+
+    assert voxel_volume({"z": 0.24, "y": 0.10833, "x": 0.10833}) == (
+        0.24 * 0.10833 * 0.10833
+    )
+
+
+def test_voxel_volume_missing_axis_treated_as_one():
+    from patchworks import voxel_volume
+
+    assert voxel_volume({"y": 0.5, "x": 0.5}) == 0.25
+
+
+def test_min_voxels_for_volume_rounds_up():
+    from patchworks import min_voxels_for_volume
+
+    calibration = {"z": 0.24, "y": 0.10833, "x": 0.10833}
+    assert min_voxels_for_volume(5.0, calibration) == 1776
+
+
+def _write_labels(path, array, chunks):
+    root = zarr.open_group(path, mode="w")
+    arr = root.create_array(
+        "labels", shape=array.shape, chunks=chunks, dtype="int32"
+    )
+    arr[:] = array
+    return root
+
+
+def test_filter_labels_by_size_drops_small_objects(tmp_path):
+    from patchworks import filter_labels_by_size
+
+    array = np.array(
+        [
+            [0, 1, 1, 0],
+            [0, 1, 1, 0],
+            [0, 0, 0, 2],
+            [0, 0, 0, 0],
+        ]
+    )
+    path = str(tmp_path / "labels.zarr")
+    root = _write_labels(path, array, chunks=(4, 4))
+
+    n_kept, n_removed = filter_labels_by_size(path, "labels", min_voxels=2)
+
+    assert (n_kept, n_removed) == (1, 1)
+    assert np.array_equal(
+        np.asarray(root["labels"]),
+        [
+            [0, 1, 1, 0],
+            [0, 1, 1, 0],
+            [0, 0, 0, 0],
+            [0, 0, 0, 0],
+        ],
+    )
+
+
+def test_filter_labels_by_size_relabels_surviving_ids_sequentially(tmp_path):
+    """Dropping id 1 must not leave id 2 with a gap where 1 used to be."""
+    from patchworks import filter_labels_by_size
+
+    array = np.array(
+        [
+            [1, 0, 2, 2],
+            [0, 0, 2, 2],
+        ]
+    )
+    path = str(tmp_path / "labels.zarr")
+    root = _write_labels(path, array, chunks=(2, 4))
+
+    filter_labels_by_size(path, "labels", min_voxels=2)
+
+    assert np.array_equal(
+        np.asarray(root["labels"]),
+        [
+            [0, 0, 1, 1],
+            [0, 0, 1, 1],
+        ],
+    )
+
+
+def test_filter_labels_by_size_relabel_false_keeps_original_ids(tmp_path):
+    from patchworks import filter_labels_by_size
+
+    array = np.array(
+        [
+            [1, 0, 5, 5],
+            [0, 0, 5, 5],
+        ]
+    )
+    path = str(tmp_path / "labels.zarr")
+    root = _write_labels(path, array, chunks=(2, 4))
+
+    filter_labels_by_size(path, "labels", min_voxels=2, relabel=False)
+
+    assert np.array_equal(
+        np.asarray(root["labels"]),
+        [
+            [0, 0, 5, 5],
+            [0, 0, 5, 5],
+        ],
+    )
+
+
+def test_filter_labels_by_size_works_across_multiple_chunks(tmp_path):
+    """A removed object's id can exceed every surviving id and still must
+
+    stay in bounds of the LUT built from the largest id *seen*, not just
+    the largest surviving one -- this is the case a single-chunk array
+    can't exercise, since chunking is what makes the scan streaming at all.
+    """
+    from patchworks import filter_labels_by_size
+
+    array = np.zeros((4, 4), dtype="int32")
+    array[0:2, 0:2] = 1  # 4 voxels, kept
+    array[2:4, 2:4] = 2  # 4 voxels, kept
+    array[0, 3] = (
+        3  # 1 voxel, dropped -- id 3 exceeds nothing survives above it
+    )
+    path = str(tmp_path / "labels.zarr")
+    root = _write_labels(path, array, chunks=(2, 2))
+
+    n_kept, n_removed = filter_labels_by_size(path, "labels", min_voxels=2)
+
+    assert (n_kept, n_removed) == (2, 1)
+    out = np.asarray(root["labels"])
+    assert set(np.unique(out).tolist()) == {0, 1, 2}
+    assert out[0, 3] == 0

{patchworks-2.6.8 → patchworks-2.6.9}/workflow/config/config_cilia.yaml

@@ -23,6 +23,11 @@ overlap: [8, 30, 30]
 method: "custom"
 # dilate: 2       # optional: pixels to grow labels by after segmentation
 # dilate_gpu: true # optional: dilate via cupy instead of scipy, needs a GPU
+# min_volume: 5.0 # optional: drop objects smaller than this many µm³.
+#                 # Runs once on the whole merged image (not per tile, where
+#                 # an object crossing a tile boundary would look smaller
+#                 # than it really is) and needs image.zarr to carry a pixel
+#                 # size -- see common.yaml/convert.
 label_name: "cilia_labels"
 custom:
   module: "patchworks.plugins.dog"

{patchworks-2.6.8 → patchworks-2.6.9}/workflow/scripts/_pw.py

@@ -268,6 +268,17 @@ def validate_config(cfg) -> None:
                 "which segments a single channel"
             )
 
+    min_volume = cfg.get("min_volume")
+    if min_volume is not None and (
+        isinstance(min_volume, bool)
+        or not isinstance(min_volume, (int, float))
+        or min_volume <= 0
+    ):
+        problems.append(
+            "min_volume must be null or a positive number of micrometers³ "
+            f"(e.g. 5.0); got {min_volume!r}"
+        )
+
     method = cfg.get("method", "cellpose")
     if method not in KNOWN_METHODS:
         listed = ", ".join(f'"{m}"' for m in KNOWN_METHODS)

{patchworks-2.6.8 → patchworks-2.6.9}/workflow/scripts/merge.py

@@ -18,7 +18,11 @@ from patchworks import (
     safe_worker_count,
 )
 from patchworks._chunks import _get_available_memory
-from patchworks.plugins.ome_zarr import register_labels
+from patchworks._volume_filter import (
+    filter_labels_by_size,
+    min_voxels_for_volume,
+)
+from patchworks.plugins.ome_zarr import read_pixel_size, register_labels
 
 from _pw import load_tiles_json, stage_path, start_log
 
@@ -96,6 +100,31 @@ _, n_objects = merge_tile_labels(
     return_count=True,
     label_counts=label_counts,
 )
+
+# Global, exact volume filter -- runs once on the fully merged array so an
+# object's size is never judged from just the fragment one tile happened to
+# see. Runs before the pyramid so every level reflects the filtered result.
+min_volume = cfg.get("min_volume")
+if min_volume:
+    voxel_size = read_pixel_size(image_store)
+    if not voxel_size:
+        raise RuntimeError(
+            f"min_volume filtering needs calibration in {image_store}, "
+            "which has none -- set min_volume: null, or make sure the "
+            "source carries a pixel size at conversion time"
+        )
+    min_voxels = min_voxels_for_volume(min_volume, voxel_size)
+    n_objects, n_removed = filter_labels_by_size(
+        label_group,
+        "0",
+        min_voxels,
+        relabel=cfg.get("sequential_labels", True),
+    )
+    print(
+        f"[patchworks] volume filter: dropped {n_removed} object(s) under "
+        f"{min_volume} µm³ ({min_voxels} voxels), {n_objects} remain"
+    )
+
 group = register_labels(
     image_store,
     label_name,