patchworks 2.0.0__tar.gz → 2.1.1__tar.gz

{patchworks-2.0.0 → patchworks-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 2.0.0
+Version: 2.1.1
 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.0.0 → patchworks-2.1.1}/docs/api/plugins/ome_zarr.md

@@ -25,6 +25,10 @@ resolution, matching anisotropic microscopy stacks.
 
 ::: patchworks.plugins.ome_zarr.register_labels
 
+## read_pixel_size
+
+::: patchworks.plugins.ome_zarr.read_pixel_size
+
 ## NGFF metadata layout
 
 NGFF 0.4 is defined over zarr v2 and puts its keys at the top level; 0.5 is

{patchworks-2.0.0 → patchworks-2.1.1}/docs/examples/dog.md

@@ -65,18 +65,36 @@ Requires `cupy` (matching your CUDA version, e.g. `pip install cupy-cuda12x`)
 
 ## With deconvolution first
 
+Let the voxel sizes come from the image rather than retyping them — the
+lateral ones from X/Y, the axial ones from Z:
+
 ```python
+from patchworks.plugins.ome_zarr import read_pixel_size
+
 fn = dog_label_fn(
     low_sigma=1.0, high_sigma=3.0, threshold=0.02,
-    decon_kwargs=dict(
-        psf=psf, dxpsf=xy_scale, dxdata=xy_scale,
-        dzpsf=z_scale, dzdata=z_scale,
-        wavelength=525, na=1.4, nimm=1.515,
-    ),
+    decon_kwargs=dict(psf=psf, wavelength=525, na=1.4, nimm=1.515),
+    voxel_size=read_pixel_size(IMAGE),   # -> dxdata/dzdata/dxpsf/dzpsf
 )
 result = tile_process(IMAGE, fn, tile_shape=(1, 1024, 1024), overlap=32)
 ```
 
+Anything you set in `decon_kwargs` yourself wins, so a PSF sampled
+differently from the data keeps its own sizes:
+
+```python
+decon_kwargs=dict(psf=psf, dxpsf=0.05, dzpsf=0.1, wavelength=525, ...)
+```
+
+!!! warning "A wrong voxel size does not fail loudly"
+    Deconvolution given the wrong sampling still runs and still returns an
+    image — just a subtly wrong one. That is the reason to derive these from
+    the store's own calibration instead of keeping a second copy in a config
+    that can drift.
+
+    `read_pixel_size` returns `{}` for an uncalibrated store; then nothing is
+    filled in and you must supply the sizes yourself.
+
 !!! note "Deconvolution always needs a GPU"
     `pycudadecon` is CUDA-only, independent of `dog_label_fn`'s own `use_gpu`
     flag (which only picks the backend for the blur/label steps). A SLURM job
@@ -146,15 +164,27 @@ custom:
     threshold: 0.02
     decon_kwargs:
       psf: "/path/to/psf.tif"
-      dxpsf: 0.1
-      dxdata: 0.1
-      dzpsf: 0.2
-      dzdata: 0.2
       wavelength: 525
       na: 1.4
       nimm: 1.515
 ```
 
+No voxel sizes: the workflow reads `image.zarr`'s own calibration and fills
+in `dxdata`/`dxpsf` from X/Y and `dzdata`/`dzpsf` from Z. Set any of them in
+`decon_kwargs` to override — for instance a PSF sampled finer than the data:
+
+```yaml
+      dxpsf: 0.05
+      dzpsf: 0.1
+```
+
+!!! tip "This works for your own methods too"
+    The injection is not DoG-specific. Any `custom` function that declares a
+    `voxel_size` parameter receives `{"z": .., "y": .., "x": ..}` from the
+    store, so a method needing physical units never has to keep a second copy
+    of the calibration in its config. If the store is uncalibrated the
+    workflow says so and passes nothing.
+
 Run it exactly like a Cellpose config:
 
 ```bash

{patchworks-2.0.0 → patchworks-2.1.1}/docs/guide/custom_segmentation.md

@@ -118,6 +118,22 @@ def segment(tile: np.ndarray, prob_thresh: float = 0.5) -> np.ndarray:
 
 Using a GPU? Just let your framework see it — nothing extra needed.
 
+!!! tip "Ask for the voxel size instead of configuring it"
+    Declare a `voxel_size` parameter and the workflow passes the image's own
+    NGFF calibration, `{"z": .., "y": .., "x": ..}` in micrometers:
+
+    ```python
+    def segment(tile, *, voxel_size=None, min_diameter_um=5.0):
+        min_px = min_diameter_um / voxel_size["x"]   # µm -> pixels
+        ...
+    ```
+
+    That keeps physical parameters tied to the image rather than duplicated
+    in a config that can drift away from it. Setting `voxel_size` in
+    `custom.kwargs` overrides it; an uncalibrated store passes nothing and
+    logs a warning. This is how the DoG plugin gets its deconvolution voxel
+    sizes.
+
 !!! tip "You do not need to modify patchworks"
     `method: "custom"` imports any `(tile) -> labels` callable, so a new
     method is a module of your own and a config block — nothing in the

{patchworks-2.0.0 → patchworks-2.1.1}/docs/guide/snakemake.md

@@ -346,6 +346,19 @@ the GPU partition stays busy instead of idling through every config's
 `prepare` and multi-hour `merge` in turn. A config that fails does **not**
 abort the others; you get a per-config status and a non-zero exit.
 
+!!! tip "After a killed run"
+    Snakemake only releases its lock on a clean exit, so a run that was killed
+    (Ctrl-C, an SSH drop, an OOM) leaves the directory locked. Each phase has
+    its own state directory, so releasing them by hand means reconstructing
+    several paths — use the flag instead:
+
+    ```bash
+    pixi run multi -- --unlock     # then re-run normally
+    ```
+
+    Running the orchestrator under `tmux` avoids most of these in the first
+    place: it survives a dropped connection.
+
 !!! warning "`jobs:` is per config"
     The profile's `jobs:` caps one Snakemake process. Running three configs
     concurrently can therefore have 3× that many jobs in flight — lower it if
@@ -450,6 +463,8 @@ prologue. The simplest path is a single shared env that the compute nodes see.
 | Symptom | Fix |
 |---------|-----|
 | `snakemake: command not found` | use `python -m snakemake` |
+| `Directory cannot be locked` | a previous run was killed instead of exiting cleanly. For a multi-run: `pixi run multi -- --unlock` (it covers every state directory, including the conversion one). For a single config: add `--unlock --directory <the same one you ran with>` |
+| `BioImage does not support the image: '.../*tif'` | a glob input needs `sequence_pattern` — see [A folder of single-plane TIFFs](ome_zarr_napari.md#a-folder-of-single-plane-tiffs) |
 | Segment jobs pend forever | wrong `slurm_partition`/GPU request; on scicore use `gres: "gpu:1"` |
 | Segment dies, `Network is unreachable` | offline GPU nodes — the `fetch_model` localrule caches the model on the submit host first; if it still fails, your submit host has no network either (pre-download manually) |
 | `cellpose is not installed` in a job | the job's env lacks `patchworks[cellpose]` |

{patchworks-2.0.0 → patchworks-2.1.1}/src/patchworks/_distributed.py

@@ -12,6 +12,7 @@ it into that store. Stitch the result with
 from __future__ import annotations
 
 import itertools
+import logging
 from pathlib import Path
 from typing import Callable, Sequence, Union
 
@@ -21,10 +22,16 @@ import zarr
 from ._io import zarr_compressor_kwargs
 from ._relabel import relabel_sequential_array
 
+logger = logging.getLogger(__name__)
+
 Overlap = Union[int, Sequence[int]]
 
 
-def normalize_overlap(overlap: Overlap, ndim: int) -> tuple[int, ...]:
+def normalize_overlap(
+    overlap: Overlap,
+    ndim: int,
+    tile_shape: "Sequence[int] | None" = None,
+) -> tuple[int, ...]:
     """Expand an overlap spec to one halo width per axis.
 
     A scalar applies the same halo to every axis (the historical behaviour).
@@ -33,12 +40,21 @@ def normalize_overlap(overlap: Overlap, ndim: int) -> tuple[int, ...]:
     ``76 x 1084 x 1084`` to keep ``16 x 1024 x 1024`` -- 5.3x more voxels than
     it uses, nearly all of it in z.
 
+    With *tile_shape*, an axis only one voxel thick gets **no** halo. There is
+    no context to gather along an axis the tile does not span, and a 2-D
+    method handed the extra planes would read them as channels. This is the
+    ``tile_shape: "auto"`` + ``do_3D: false`` case, where tiles come out one
+    plane thick: a z-overlap of 4 would otherwise read 9 planes per tile to
+    keep 1.
+
     Parameters
     ----------
     overlap : int or sequence of int
         Halo width, shared or per-axis.
     ndim : int
         Number of axes the halo is applied to.
+    tile_shape : sequence of int, optional
+        Tile extent per axis. Used to drop halos an axis has no room for.
 
     Returns
     -------
@@ -55,6 +71,21 @@ def normalize_overlap(overlap: Overlap, ndim: int) -> tuple[int, ...]:
             )
     if any(o < 0 for o in values):
         raise ValueError(f"overlap must be non-negative, got {values}")
+
+    if tile_shape is not None:
+        clipped = tuple(
+            0 if int(t) <= 1 else o for o, t in zip(values, tile_shape)
+        )
+        if clipped != values:
+            dropped = [
+                i for i, (a, b) in enumerate(zip(values, clipped)) if a != b
+            ]
+            logger.info(
+                "dropping the halo on axis %s: the tile is 1 voxel thick "
+                "there, so there is no context to read.",
+                dropped,
+            )
+        values = clipped
     return values
 
 
@@ -173,7 +204,7 @@ def stage_tile(
     """
     shape = image.shape
     sl = spatial_tiles(shape, tile_shape)[index]
-    halo = normalize_overlap(overlap, len(sl))
+    halo = normalize_overlap(overlap, len(sl), tile_shape=tile_shape)
     expanded, trims = [], []
     for s, dim, ov in zip(sl, shape, halo):
         lo = max(0, s.start - ov)

{patchworks-2.0.0 → patchworks-2.1.1}/src/patchworks/plugins/dog.py

@@ -34,6 +34,7 @@ docs/guide/custom_segmentation.md), use the
 
 from __future__ import annotations
 
+import logging
 from functools import partial
 from typing import Any, Callable
 
@@ -41,6 +42,8 @@ import numpy as np
 
 from .._gpu import free_gpu_caches, retry_on_oom
 
+logger = logging.getLogger(__name__)
+
 
 def _require_cupy():
     """Raise an actionable ImportError if cupy is not installed.
@@ -77,6 +80,64 @@ def _require_pycudadecon():
         ) from exc
 
 
+def decon_voxel_kwargs(
+    voxel_size: dict[str, float], psf_voxel_size: dict[str, float] | None = None
+) -> dict[str, float]:
+    """pycudadecon's voxel-size arguments, derived from a calibration.
+
+    ``dxdata``/``dzdata`` describe the **image**, so they come straight from
+    its calibration. ``dxpsf``/``dzpsf`` describe the **PSF file**, which is
+    only the same when the PSF was acquired on the same system at the same
+    sampling -- pass *psf_voxel_size* when it was not.
+
+    Getting these wrong does not fail loudly: deconvolution just returns a
+    subtly wrong result, which is why deriving them beats retyping them.
+
+    Parameters
+    ----------
+    voxel_size : dict
+        Image calibration, e.g. from
+        :func:`patchworks.plugins.ome_zarr.read_pixel_size`. Needs ``x`` (or
+        ``y``) for the lateral size and ``z`` for the axial one.
+    psf_voxel_size : dict, optional
+        The PSF's own calibration. Defaults to *voxel_size*.
+
+    Returns
+    -------
+    dict
+        ``dxdata``/``dzdata``/``dxpsf``/``dzpsf``, omitting any the
+        calibration cannot supply.
+
+    Examples
+    --------
+    >>> decon_voxel_kwargs({"z": 0.2, "y": 0.1, "x": 0.1})
+    {'dxdata': 0.1, 'dzdata': 0.2, 'dxpsf': 0.1, 'dzpsf': 0.2}
+    """
+
+    def _lateral(cal):
+        x, y = cal.get("x"), cal.get("y")
+        if x and y and abs(x - y) > 1e-9 * max(x, y):
+            logger.warning(
+                "anisotropic lateral calibration (x=%s, y=%s); pycudadecon "
+                "takes a single lateral size, using x.",
+                x,
+                y,
+            )
+        return x or y
+
+    psf_cal = psf_voxel_size if psf_voxel_size is not None else voxel_size
+    out: dict[str, float] = {}
+    for key, value in (
+        ("dxdata", _lateral(voxel_size)),
+        ("dzdata", voxel_size.get("z")),
+        ("dxpsf", _lateral(psf_cal)),
+        ("dzpsf", psf_cal.get("z")),
+    ):
+        if value:
+            out[key] = float(value)
+    return out
+
+
 def dog_label_fn(
     low_sigma: float | tuple[float, ...],
     high_sigma: float | tuple[float, ...],
@@ -84,6 +145,7 @@ def dog_label_fn(
     *,
     use_gpu: bool = False,
     decon_kwargs: dict[str, Any] | None = None,
+    voxel_size: dict[str, float] | None = None,
 ) -> Callable[[np.ndarray], np.ndarray]:
     """Return a ready-to-use DoG labeler for ``tile_process``.
 
@@ -108,6 +170,15 @@ def dog_label_fn(
         PSF support when deconvolving, so edge tiles don't get truncated
         context.
 
+        ``dxdata``/``dzdata``/``dxpsf``/``dzpsf`` are filled in from
+        *voxel_size* when you leave them out, so the voxel sizes cannot drift
+        away from the image they describe. Anything you set explicitly wins.
+    voxel_size:
+        Physical voxel size as ``{"z": .., "y": .., "x": ..}``. The Snakemake
+        workflow passes the image's own calibration automatically; from the
+        API, :func:`patchworks.plugins.ome_zarr.read_pixel_size` reads it from
+        a store.
+
     Returns
     -------
     Callable[[ndarray], ndarray]
@@ -117,6 +188,19 @@ def dog_label_fn(
         _require_cupy()
     if decon_kwargs is not None:
         _require_pycudadecon()
+        if voxel_size:
+            # Derived values fill gaps only -- an explicit dxpsf for a PSF
+            # sampled differently from the data must not be overwritten.
+            derived = decon_voxel_kwargs(voxel_size)
+            missing = {
+                k: v for k, v in derived.items() if k not in decon_kwargs
+            }
+            if missing:
+                logger.info(
+                    "decon voxel sizes taken from the image calibration: %s",
+                    missing,
+                )
+                decon_kwargs = {**decon_kwargs, **missing}
     cfg = {
         "low_sigma": low_sigma,
         "high_sigma": high_sigma,

{patchworks-2.0.0 → patchworks-2.1.1}/src/patchworks/plugins/ome_zarr.py

@@ -45,6 +45,7 @@ Usage
 
 from __future__ import annotations
 
+import glob
 import logging
 import math
 from concurrent.futures import ThreadPoolExecutor
@@ -743,6 +744,35 @@ def _write_multiscales(
     write_ngff_attrs(zarr.open_group(group_path, mode="a"), multiscales=[entry])
 
 
+def read_pixel_size(store: Union[str, Path]) -> PixelSize:
+    """Physical voxel size recorded in an OME-ZARR's level-0 metadata.
+
+    The calibration the conversion carried over from the source file, as
+    ``{"z": .., "y": .., "x": ..}`` in micrometers. Axes left at scale 1.0
+    (uncalibrated) are omitted, so an empty dict means the store carries no
+    usable calibration.
+
+    Use this instead of retyping voxel sizes into a config: a deconvolution
+    told the wrong voxel size produces a plausible-looking but wrong result.
+
+    Parameters
+    ----------
+    store : str or Path
+        Path of the OME-ZARR group.
+
+    Returns
+    -------
+    dict
+        ``{axis: size}`` for calibrated spatial axes.
+
+    Examples
+    --------
+    >>> read_pixel_size("scan.zarr")  # doctest: +SKIP
+    {'z': 0.2, 'y': 0.1, 'x': 0.1}
+    """
+    return _read_zarr_calibration(store, "")
+
+
 def _read_zarr_calibration(store: Union[str, Path], axes: str) -> PixelSize:
     """Read level-0 spatial scale from an existing OME-ZARR, if any.
 
@@ -1172,6 +1202,21 @@ def _to_dask(
     if sequence_pattern is not None:
         arr, detected, ps = _open_tiff_sequence(path, sequence_pattern)
         return arr, axes or detected, ps
+    if any(ch in path for ch in "*?[") or (
+        not Path(path).exists() and glob.glob(path)
+    ):
+        # Without sequence_pattern this would be handed to bioio, which reads
+        # single files and reports only that it cannot handle the "format" --
+        # pointing at the glob rather than the missing setting.
+        raise ValueError(
+            f"{path!r} looks like a glob over several files, but "
+            "sequence_pattern is not set, so there is no way to tell which "
+            "part of each filename is Z, C or T.\n"
+            "Set it to a regex with named groups, e.g.\n"
+            "    sequence_pattern: '_Z(?P<Z>\\d+)_C(?P<C>\\d+)_V\\d+'\n"
+            "for files like sample_Z001_C0_V0.tif. Pass a single file "
+            "instead if you did not mean a sequence."
+        )
     if path.endswith(".zarr"):
         arr = load_ome_zarr(source, channel=None)
         ax = axes or _default_axes(arr.ndim)

{patchworks-2.0.0 → patchworks-2.1.1}/tests/test_distributed.py

@@ -41,6 +41,53 @@ def test_normalize_overlap_scalar_and_per_axis():
         normalize_overlap([-1, 0, 0], 3)
 
 
+def test_no_halo_on_a_one_voxel_thick_axis():
+    """A 1-plane tile must get no halo on that axis.
+
+    `tile_shape: "auto"` with `do_3D: false` produces z=1 tiles, so a z-overlap
+    of 4 would read 9 planes to keep 1 (9x) -- and hand a 2-D method a stack it
+    would read as channels.
+    """
+    assert normalize_overlap([4, 30, 30], 3, tile_shape=(1, 8000, 8000)) == (
+        0,
+        30,
+        30,
+    )
+    # A tile with room keeps its halo.
+    assert normalize_overlap([4, 30, 30], 3, tile_shape=(16, 1024, 1024)) == (
+        4,
+        30,
+        30,
+    )
+    # Without a tile_shape nothing is clipped (the historical behaviour).
+    assert normalize_overlap([4, 30, 30], 3) == (4, 30, 30)
+
+
+def test_single_plane_tiles_segment_without_a_z_halo(tmp_path):
+    """End to end: z=1 tiles must not pull neighbouring planes into the tile."""
+    img = np.zeros((4, 32), "uint16")
+    img[1, 4:10] = 500  # only plane 1 has signal
+    tile = (1, 16)
+
+    stage = str(tmp_path / "stage.zarr")
+    create_stage(stage, img.shape, tile)
+    seen = []
+
+    def _recording(block):
+        seen.append(block.shape)
+        return _fn(block)
+
+    for i in range(len(spatial_tiles(img.shape, tile))):
+        stage_tile(img, _recording, stage, i, tile_shape=tile, overlap=[3, 2])
+
+    assert all(s[0] == 1 for s in seen), (
+        f"a z=1 tile was handed multiple planes: {seen}"
+    )
+    written = np.asarray(zarr.open_group(stage, mode="r")["staged"])
+    assert (written[0] == 0).all(), "plane 0 has no signal and must stay empty"
+    assert (written[1, 4:10] > 0).all()
+
+
 def test_auto_overlap_anisotropy_shrinks_z():
     """A 20x coarser z step needs 20x fewer planes for the same distance."""
     assert auto_overlap(30) == 30  # unchanged without voxel_size

patchworks-2.1.1/tests/test_dog.py

@@ -0,0 +1,109 @@
+"""Self-contained tests for the dog plugin. No frameworks, no fixtures."""
+
+import numpy as np
+
+
+def _make_blob_image(shape=(1, 64, 64)):
+    img = np.zeros(shape, dtype="float32")
+    img[0, 28:36, 28:36] = 1.0
+    return img
+
+
+def test_dog_label_fn_cpu_finds_blob():
+    from patchworks.plugins.dog import dog_label_fn
+
+    fn = dog_label_fn(low_sigma=1.0, high_sigma=4.0, threshold=0.01)
+    labels = fn(_make_blob_image())
+
+    assert labels.shape == (1, 64, 64)
+    assert labels.dtype == np.int32
+    assert labels.max() >= 1  # the blob was detected
+    assert labels[0, 0, 0] == 0  # background stays unlabeled
+
+
+def test_segment_adapter_matches_factory():
+    # method: "custom" calls segment(tile, **kwargs) directly — must match
+    # dog_label_fn(**kwargs)(tile) exactly.
+    from patchworks.plugins.dog import dog_label_fn, segment
+
+    kwargs = dict(low_sigma=1.0, high_sigma=4.0, threshold=0.01)
+    img = _make_blob_image()
+
+    via_adapter = segment(img, **kwargs)
+    via_factory = dog_label_fn(**kwargs)(img)
+
+    np.testing.assert_array_equal(via_adapter, via_factory)
+
+
+def test_dog_label_fn_with_tile_process():
+    import dask.array as da
+
+    from patchworks import tile_process
+    from patchworks.plugins.dog import dog_label_fn
+
+    arr = da.from_array(_make_blob_image((1, 64, 64)), chunks=(1, 64, 64))
+    fn = dog_label_fn(low_sigma=1.0, high_sigma=4.0, threshold=0.01)
+    result = tile_process(arr, fn, overlap=4).compute()
+
+    assert result.shape == (1, 64, 64)
+    assert result.max() >= 1
+
+
+def test_decon_voxel_kwargs_from_calibration():
+    """Voxel sizes come from the image, not from retyped config values.
+
+    A deconvolution told the wrong voxel size does not fail -- it returns a
+    subtly wrong result -- so deriving them is the point.
+    """
+    from patchworks.plugins.dog import decon_voxel_kwargs
+
+    assert decon_voxel_kwargs({"z": 0.2, "y": 0.1, "x": 0.1}) == {
+        "dxdata": 0.1,
+        "dzdata": 0.2,
+        "dxpsf": 0.1,
+        "dzpsf": 0.2,
+    }
+    # A PSF sampled differently from the data keeps its own sizes.
+    assert decon_voxel_kwargs(
+        {"z": 0.2, "y": 0.1, "x": 0.1}, {"z": 0.1, "y": 0.05, "x": 0.05}
+    ) == {"dxdata": 0.1, "dzdata": 0.2, "dxpsf": 0.05, "dzpsf": 0.1}
+    # An uncalibrated axis is simply omitted rather than guessed.
+    assert decon_voxel_kwargs({"y": 0.1, "x": 0.1}) == {
+        "dxdata": 0.1,
+        "dxpsf": 0.1,
+    }
+    assert decon_voxel_kwargs({}) == {}
+
+
+def test_explicit_decon_kwargs_win_over_the_calibration(monkeypatch):
+    """Anything set by hand must survive; only gaps are filled."""
+    import sys
+    import types
+
+    from patchworks.plugins import dog
+
+    captured = {}
+
+    def _decon(images, **kwargs):
+        captured.update(kwargs)
+        return images
+
+    monkeypatch.setitem(
+        sys.modules, "pycudadecon", types.SimpleNamespace(decon=_decon)
+    )
+    monkeypatch.setattr(dog, "_require_pycudadecon", lambda: None)
+
+    fn = dog.dog_label_fn(
+        low_sigma=1.0,
+        high_sigma=3.0,
+        threshold=0.5,
+        # dxpsf set by hand: the PSF was sampled finer than the data
+        decon_kwargs={"psf": "psf.tif", "dxpsf": 0.05},
+        voxel_size={"z": 0.2, "y": 0.1, "x": 0.1},
+    )
+    fn(np.zeros((4, 8, 8), "uint16"))
+
+    assert captured["dxpsf"] == 0.05, "an explicit value must not be replaced"
+    assert captured["dxdata"] == 0.1  # filled from the calibration
+    assert captured["dzdata"] == 0.2
+    assert captured["dzpsf"] == 0.2

{patchworks-2.0.0 → patchworks-2.1.1}/tests/test_ome_zarr.py

@@ -399,3 +399,19 @@ def test_sharding(tmp_path):
     assert (
         getattr(_zarr.open_array(f"{out3}/0", mode="r"), "shards", None) is None
     )
+
+
+def test_glob_without_sequence_pattern_says_so(tmp_path):
+    """A glob input must name the missing setting, not blame the format.
+
+    Without sequence_pattern the glob fell through to bioio, which reads one
+    file and could only report "does not support the image" -- pointing at the
+    path instead of at the config key that was missing.
+    """
+    with pytest.raises(ValueError, match="sequence_pattern is not set"):
+        to_ome_zarr(str(tmp_path / "*.tif"), tmp_path / "out.zarr")
+
+    # A real single file must still reach the normal readers.
+    with pytest.raises(Exception) as exc:
+        to_ome_zarr(str(tmp_path / "scan.ims"), tmp_path / "o2.zarr")
+    assert "sequence_pattern" not in str(exc.value)

{patchworks-2.0.0 → patchworks-2.1.1}/workflow/config/config_cilia.yaml

@@ -47,10 +47,14 @@ custom:
     # use_gpu: true          # optional: also run the blur/label step on GPU
     decon_kwargs:
       psf: "/path/to/psf.tif"
-      dxpsf: 0.1
-      dxdata: 0.1
-      dzpsf: 0.2
-      dzdata: 0.2
+      # dxdata/dzdata (and dxpsf/dzpsf) are filled from image.zarr's own
+      # calibration -- the lateral size from X/Y, the axial one from Z -- so
+      # they cannot drift away from the image they describe. A wrong voxel
+      # size does not fail loudly; it just deconvolves incorrectly.
+      # Set any of them here only to override, e.g. when the PSF was sampled
+      # differently from the data:
+      #   dxpsf: 0.05
+      #   dzpsf: 0.1
       wavelength: 525
       na: 1.4
       nimm: 1.515

{patchworks-2.0.0 → patchworks-2.1.1}/workflow/scripts/_pw.py

@@ -131,6 +131,46 @@ def load_tiles_json(path):
     return json.loads(Path(path).read_text())
 
 
+def _with_voxel_size(fn, kwargs, cfg):
+    """Pass the image's calibration to a function that asks for it.
+
+    A method that needs physical units -- a deconvolution's voxel sizes, a
+    diameter in micrometers -- should not have them retyped into the config
+    where they can drift away from the image. Any custom function that
+    declares a ``voxel_size`` parameter gets ``{"z": .., "y": .., "x": ..}``
+    from the store's own NGFF calibration, unless the config sets it.
+
+    Returns *kwargs* unchanged when the function does not take it, the config
+    already supplied it, or the store carries no calibration.
+    """
+    import inspect
+
+    if "voxel_size" in kwargs:
+        return kwargs
+    # A **kwargs passthrough names its real target (see dog.segment).
+    target = getattr(fn, "patchworks_kwargs_target", fn)
+    try:
+        params = inspect.signature(target).parameters
+    except (TypeError, ValueError):
+        return kwargs
+    if "voxel_size" not in params:
+        return kwargs
+
+    from patchworks.plugins.ome_zarr import read_pixel_size
+
+    store = str(Path(cfg["work_dir"]) / "image.zarr")
+    calibration = read_pixel_size(store)
+    if not calibration:
+        logging.getLogger(__name__).warning(
+            "%s takes voxel_size but %s carries no calibration; set the "
+            "physical sizes in the config instead.",
+            getattr(target, "__name__", target),
+            store,
+        )
+        return kwargs
+    return {**kwargs, "voxel_size": calibration}
+
+
 def _unknown_kwargs(fn, provided, *, skip=()) -> list[str]:
     """Keys in *provided* that *fn* would reject, ignoring *skip*.
 
@@ -314,7 +354,8 @@ def _build_method_fn(cfg):
             importlib.import_module(spec["module"]),
             spec.get("function", "segment"),
         )
-        kwargs = spec.get("kwargs") or {}
+        kwargs = dict(spec.get("kwargs") or {})
+        kwargs = _with_voxel_size(fn, kwargs, cfg)
         return partial(fn, **kwargs) if kwargs else fn
 
     if method == "threshold":

{patchworks-2.0.0 → patchworks-2.1.1}/workflow/scripts/prepare_tiles.py

@@ -85,7 +85,9 @@ if len(tile_shape) >= 3:
 # A halo wider than the tile itself is not boundary context -- it means every
 # tile re-reads and re-segments its neighbours. Catch it here rather than
 # paying 5x the GPU time for results that get trimmed away.
-overlap = normalize_overlap(cfg.get("overlap", 0), len(tile_shape))
+overlap = normalize_overlap(
+    cfg.get("overlap", 0), len(tile_shape), tile_shape=tile_shape
+)
 for axis, (ov, extent) in enumerate(zip(overlap, tile_shape)):
     if ov >= extent:
         raise ValueError(
@@ -93,9 +95,13 @@ for axis, (ov, extent) in enumerate(zip(overlap, tile_shape)):
             f"would read past its neighbours. Use a per-axis overlap, e.g. "
             f"overlap: {list(max(1, t // 4) for t in tile_shape)}"
         )
-amplification = np.prod(
-    [(t + 2 * o) for t, o in zip(tile_shape, overlap)]
-) / np.prod(tile_shape)
+# Clip the halo to the image the way stage_tile does, or a tile that already
+# spans an axis reports a halo it will never actually read -- a tile covering
+# the whole image would claim 5x while reading exactly 1x.
+read = np.prod(
+    [min(t + 2 * o, s) for t, o, s in zip(tile_shape, overlap, image.shape)]
+)
+amplification = read / np.prod(tile_shape)
 print(f"[patchworks] halo read amplification: {amplification:.2f}x")
 
 tiles = spatial_tiles(image.shape, tile_shape)

{patchworks-2.0.0 → patchworks-2.1.1}/workflow/scripts/run_multi.py

@@ -46,6 +46,7 @@ def _snakemake_cmd(
     dry_run: bool,
     state_dir: Path | None = None,
     targets: list[str] | None = None,
+    extra: list[str] | None = None,
 ) -> list[str]:
     """Build one snakemake invocation.
 
@@ -69,6 +70,8 @@ def _snakemake_cmd(
         cmd += ["--cores", str(cores), "--rerun-triggers", "mtime"]
     if dry_run:
         cmd += ["-n", "-p"]
+    if extra:
+        cmd += extra
     if targets:
         # "--" ends option parsing: --rerun-triggers takes a variable number
         # of values and would otherwise swallow the target path.
@@ -114,6 +117,18 @@ def _validate_configs(paths: list[Path], cfgs: list[dict]) -> str:
                 f"share a chunk layout; got {_spread(key)}"
             )
 
+    for path, cfg in zip(paths, cfgs):
+        source = str(cfg.get("input", ""))
+        if any(ch in source for ch in "*?[") and not cfg.get(
+            "sequence_pattern"
+        ):
+            problems.append(
+                f"{path.name}: input {source!r} is a glob over several files "
+                "but sequence_pattern is unset, so nothing says which part of "
+                "each filename is Z/C/T. Set e.g. "
+                r"sequence_pattern: '_Z(?P<Z>\d+)_C(?P<C>\d+)_V\d+'"
+            )
+
     names = [cfg.get("label_name") for cfg in cfgs]
     duplicates = {n for n in names if names.count(n) > 1}
     if duplicates:
@@ -160,6 +175,15 @@ def main() -> None:
         action="store_true",
         help="pass -n -p to every Snakemake run; skips relations",
     )
+    parser.add_argument(
+        "--unlock",
+        action="store_true",
+        help=(
+            "release stale Snakemake locks in every state directory this "
+            "script manages, then exit. Needed after a run was killed or "
+            "died: the lock is only released on a clean exit."
+        ),
+    )
     args = parser.parse_args()
 
     workflow_dir = Path(__file__).resolve().parent.parent
@@ -173,6 +197,32 @@ def main() -> None:
     work_dir = _validate_configs(seg_config_paths, seg_cfgs)
     image_store = f"{work_dir}/image.zarr"
 
+    # Each phase gets its own Snakemake state directory (the lock lives in the
+    # working directory, not the config), so unlocking has to cover all of
+    # them -- and nobody should have to reconstruct these paths by hand.
+    state_dirs = [Path(work_dir) / ".snakemake_convert"] + [
+        Path(cfg["work_dir"]) / cfg["label_name"] / ".snakemake"
+        for cfg in seg_cfgs
+    ]
+    if args.unlock:
+        for state_dir in state_dirs:
+            if not state_dir.exists():
+                continue
+            _run(
+                _snakemake_cmd(
+                    seg_config_paths[0],
+                    workflow_dir=workflow_dir,
+                    profile=args.profile,
+                    cores=args.cores,
+                    dry_run=False,
+                    state_dir=state_dir,
+                    extra=["--unlock"],
+                ),
+                workflow_dir,
+            )
+        print("[run_multi] unlocked; re-run without --unlock", flush=True)
+        return
+
     # Phase A: convert exactly once. The three runs are about to go concurrent
     # and `convert` writes with overwrite=True, so letting them race on it
     # would have them clobbering one store. Ask for its marker explicitly.
@@ -189,7 +239,13 @@ def main() -> None:
         workflow_dir,
     )
     if rc != 0:
-        print("[run_multi] ERROR: conversion failed", file=sys.stderr)
+        print(
+            "[run_multi] ERROR: conversion failed.\n"
+            "  If the log says the directory cannot be locked, a previous run "
+            "was killed rather than exiting cleanly; release it with:\n"
+            f"      {Path(sys.argv[0]).name} --config {args.config} --unlock",
+            file=sys.stderr,
+        )
         sys.exit(rc)
 
     # Still phase A: build the occupancy map here too. Every config's `prepare`

patchworks-2.0.0/tests/test_dog.py

@@ -1,49 +0,0 @@
-"""Self-contained tests for the dog plugin. No frameworks, no fixtures."""
-
-import numpy as np
-
-
-def _make_blob_image(shape=(1, 64, 64)):
-    img = np.zeros(shape, dtype="float32")
-    img[0, 28:36, 28:36] = 1.0
-    return img
-
-
-def test_dog_label_fn_cpu_finds_blob():
-    from patchworks.plugins.dog import dog_label_fn
-
-    fn = dog_label_fn(low_sigma=1.0, high_sigma=4.0, threshold=0.01)
-    labels = fn(_make_blob_image())
-
-    assert labels.shape == (1, 64, 64)
-    assert labels.dtype == np.int32
-    assert labels.max() >= 1  # the blob was detected
-    assert labels[0, 0, 0] == 0  # background stays unlabeled
-
-
-def test_segment_adapter_matches_factory():
-    # method: "custom" calls segment(tile, **kwargs) directly — must match
-    # dog_label_fn(**kwargs)(tile) exactly.
-    from patchworks.plugins.dog import dog_label_fn, segment
-
-    kwargs = dict(low_sigma=1.0, high_sigma=4.0, threshold=0.01)
-    img = _make_blob_image()
-
-    via_adapter = segment(img, **kwargs)
-    via_factory = dog_label_fn(**kwargs)(img)
-
-    np.testing.assert_array_equal(via_adapter, via_factory)
-
-
-def test_dog_label_fn_with_tile_process():
-    import dask.array as da
-
-    from patchworks import tile_process
-    from patchworks.plugins.dog import dog_label_fn
-
-    arr = da.from_array(_make_blob_image((1, 64, 64)), chunks=(1, 64, 64))
-    fn = dog_label_fn(low_sigma=1.0, high_sigma=4.0, threshold=0.01)
-    result = tile_process(arr, fn, overlap=4).compute()
-
-    assert result.shape == (1, 64, 64)
-    assert result.max() >= 1