patchworks 2.6.7__tar.gz → 2.6.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 2.6.7
+Version: 2.6.8
 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.7 → patchworks-2.6.8}/docs/guide/ome_zarr_napari.md

@@ -229,6 +229,20 @@ just one channel instead: `view_in_napari("scan.zarr", channel=0)`.
     napari ships in `patchworks[all]`, or install just it with
     `pip install "patchworks[napari]"`.
 
+!!! tip "From the cluster workflow"
+    `workflow/pixi.toml` has a separate `viewer` environment (napari's Qt/GUI
+    dependencies are kept out of the default headless workflow env on
+    purpose):
+
+    ```bash
+    pixi install -e viewer
+    pixi run -e viewer napari /path/to/work_dir/image.zarr
+    ```
+
+    This wraps `view_in_napari` with its `labels=` argument left at the
+    default, so every label group in the store loads automatically — needs a
+    display (`ssh -X`, or a remote-desktop/VNC session).
+
 !!! tip "Measuring all the objects"
     Once labels are loaded, use
     [napari-chunked-regionprops](https://github.com/imcf/napari-chunked-regionprops)'s

{patchworks-2.6.7 → patchworks-2.6.8}/src/patchworks/plugins/cellpose.py

@@ -75,6 +75,40 @@ def _require_cellpose():
         )
 
 
+def cellpose_anisotropy(voxel_size: dict[str, float]) -> float | None:
+    """Cellpose's ``anisotropy`` (z voxel size / lateral voxel size) from a calibration.
+
+    ``do_3D`` assumes isotropic voxels unless told otherwise: without this,
+    Cellpose builds its 3-D flow-field consensus across z-planes it thinks
+    are spaced the same as the xy pixels, which for real data rarely holds
+    and fragments or distorts objects across z. Getting this wrong does not
+    fail loudly -- it just produces a subtly (or not so subtly) wrong
+    segmentation, which is why deriving it beats retyping it.
+
+    Parameters
+    ----------
+    voxel_size : dict
+        Image calibration, e.g. from
+        :func:`patchworks.plugins.ome_zarr.read_pixel_size`. Needs ``z`` and
+        ``x`` (or ``y``) for the lateral size.
+
+    Returns
+    -------
+    float or None
+        ``z / lateral``, or None if the calibration lacks what is needed.
+
+    Examples
+    --------
+    >>> cellpose_anisotropy({"z": 0.24, "y": 0.10833, "x": 0.10833})
+    2.215452783162559
+    """
+    lateral = voxel_size.get("x") or voxel_size.get("y")
+    z = voxel_size.get("z")
+    if not lateral or not z:
+        return None
+    return z / lateral
+
+
 def cellpose_fn(
     model: str = "cyto3",
     *,
@@ -83,6 +117,7 @@ def cellpose_fn(
     do_3D: bool = False,
     channels: list[int] | None = None,
     channel_axis: int | None = None,
+    voxel_size: dict[str, float] | None = None,
     **cellpose_kwargs: Any,
 ) -> Callable[[np.ndarray], np.ndarray]:
     """Return a ready-to-use Cellpose function for ``tile_process``.
@@ -107,6 +142,15 @@ def cellpose_fn(
     channel_axis:
         *Cellpose 4 only.* Index of the channel axis in the input array.
         ``None`` → greyscale input.
+    voxel_size:
+        Physical voxel size as ``{"z": .., "y": .., "x": ..}``. When
+        ``do_3D`` is set and ``anisotropy`` is not already in
+        ``cellpose_kwargs``, it is derived from this via
+        :func:`cellpose_anisotropy` -- an explicit ``anisotropy=`` always
+        wins. 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.
     **cellpose_kwargs:
         Extra kwargs forwarded to ``model.eval()``
         (e.g. ``flow_threshold``, ``cellprob_threshold``, ``anisotropy``).
@@ -128,15 +172,31 @@ def cellpose_fn(
     >>> fn = cellpose_fn("nuclei", diameter=15)
     >>> result = tile_process("image.zarr", fn, channel=1)
 
-    3-D with anisotropy:
+    3-D with an explicit anisotropy:
 
     >>> fn = cellpose_fn("cyto3", gpu=True, do_3D=True, anisotropy=3.0, diameter=20)
     >>> from functools import partial
     >>> from patchworks import auto_tile_shape_cellpose, tile_process
     >>> tile_fn = partial(auto_tile_shape_cellpose, do_3D=True, use_gpu=True, diameter=20)
     >>> result = tile_process("image.zarr", fn, tile_shape=tile_fn, overlap=10)
+
+    3-D with anisotropy derived from the image's own calibration:
+
+    >>> fn = cellpose_fn("cyto3", gpu=True, do_3D=True, diameter=20,
+    ...                  voxel_size={"z": 0.24, "y": 0.10833, "x": 0.10833})
     """
     _require_cellpose()
+    if do_3D and voxel_size and "anisotropy" not in cellpose_kwargs:
+        anisotropy = cellpose_anisotropy(voxel_size)
+        if anisotropy is not None:
+            logger.info(
+                "anisotropy derived from image calibration: %.4g "
+                "(z=%.4g, lateral=%.4g)",
+                anisotropy,
+                voxel_size.get("z"),
+                voxel_size.get("x") or voxel_size.get("y"),
+            )
+            cellpose_kwargs = {**cellpose_kwargs, "anisotropy": anisotropy}
     cfg = _make_config(
         model, gpu, channels, channel_axis, diameter, do_3D, **cellpose_kwargs
     )

patchworks-2.6.8/tests/test_cellpose.py

@@ -0,0 +1,49 @@
+"""Tests for the cellpose plugin's anisotropy handling.
+
+cellpose itself is not a test dependency (heavy, GPU-oriented), and
+cellpose_fn() calls _require_cellpose() as its very first line, so it can't
+be exercised end-to-end here. cellpose_anisotropy() is a pure function with
+no cellpose import at all, and is where the actual math lives -- that's
+what's covered directly. The wiring that fills cellpose_fn's voxel_size
+parameter in from the image's calibration (workflow/scripts/_pw.py's
+_with_voxel_size) is covered in tests/test_pw.py.
+"""
+
+import inspect
+
+
+def test_cellpose_anisotropy_from_calibration():
+    from patchworks.plugins.cellpose import cellpose_anisotropy
+
+    calibration = {"z": 0.24, "y": 0.10833, "x": 0.10833}
+    assert cellpose_anisotropy(calibration) == 0.24 / 0.10833
+
+
+def test_cellpose_anisotropy_falls_back_to_y_when_x_is_missing():
+    from patchworks.plugins.cellpose import cellpose_anisotropy
+
+    assert cellpose_anisotropy({"z": 0.2, "y": 0.1}) == 2.0
+
+
+def test_cellpose_anisotropy_missing_calibration_returns_none():
+    from patchworks.plugins.cellpose import cellpose_anisotropy
+
+    assert cellpose_anisotropy({}) is None
+    assert cellpose_anisotropy({"z": 0.2}) is None  # no lateral size at all
+    assert cellpose_anisotropy({"x": 0.1}) is None  # no z size
+
+
+def test_cellpose_fn_declares_a_voxel_size_parameter():
+    """workflow/scripts/_pw.py's _with_voxel_size() finds this by signature
+
+    inspection to decide whether to fill it in -- if this parameter were
+    ever renamed, that wiring would silently stop working rather than error.
+    """
+    from patchworks.plugins.cellpose import cellpose_fn
+
+    params = inspect.signature(cellpose_fn).parameters
+    assert "voxel_size" in params
+    # anisotropy itself goes through **cellpose_kwargs (it's a cellpose
+    # model.eval() argument, not a patchworks-specific one) -- only the raw
+    # calibration is a named parameter.
+    assert "anisotropy" not in params

patchworks-2.6.8/tests/test_pw.py

@@ -0,0 +1,57 @@
+"""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

{patchworks-2.6.7 → patchworks-2.6.8}/tests/test_run_multi.py

@@ -188,6 +188,32 @@ def test_relate_script_has_the_real_bookkeeping():
     assert "openpyxl" in src
 
 
+def test_view_script_loads_every_label_by_default():
+    """view.py must not override labels=, or auto-load stops working.
+
+    view_in_napari's labels=None default is what auto-loads every label
+    group under <image>/labels/<name>/ as its own layer -- passing an
+    explicit labels= here would silently drop that and show only one.
+    """
+    src = (_workflow_dir() / "scripts" / "view.py").read_text()
+    assert "from patchworks.plugins.napari import view_in_napari" in src
+    assert "labels=" not in src
+
+
+def test_viewer_is_a_separate_opt_in_pixi_environment():
+    """napari's Qt/GUI deps must stay out of the default headless env.
+
+    Adding them to the default `[pypi-dependencies]` would pull heavy GUI
+    dependencies into every SLURM job's environment for a feature only used
+    interactively.
+    """
+    src = (_workflow_dir() / "pixi.toml").read_text()
+    default_deps = src.split("[pypi-dependencies]")[1].split("[feature")[0]
+    assert "napari" not in default_deps
+    assert 'viewer = { features = ["viewer"] }' in src
+    assert 'extras = ["napari"]' in src
+
+
 def test_relate_writes_its_own_log():
     """relate.py runs via srun, not a Snakemake rule -- nothing else wires up
 

{patchworks-2.6.7 → patchworks-2.6.8}/workflow/pixi.toml

@@ -6,6 +6,9 @@
 #   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
+#   pixi install -e viewer && pixi run -e viewer napari <image.zarr>
+#                          # open a store in napari, every label auto-loaded
+#                          # (needs a display -- ssh -X or remote-desktop/VNC)
 #
 # 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.
@@ -31,11 +34,21 @@ cellpose = ">=3.0,<4"
 [feature.cp4.pypi-dependencies]
 cellpose = ">=4"
 
-# Named environments: pixi install -e cellpose3 / -e cellpose4
+# napari pulls in a lot of Qt/GUI dependencies that don't belong in the
+# default headless SLURM environment, so it's a separate opt-in feature --
+# pixi install -e viewer, not part of the default `pixi install`.
+[feature.viewer.pypi-dependencies]
+patchworks = { version = "*", extras = ["napari"] }
+
+[feature.viewer.tasks]
+napari = "python scripts/view.py"
+
+# Named environments: pixi install -e cellpose3 / -e cellpose4 / -e viewer
 # The base patchworks[cellpose] (>=3.0) is further constrained by each feature.
 [environments]
 cellpose3 = { features = ["cp3"], solve-group = "cp3" }
 cellpose4 = { features = ["cp4"], solve-group = "cp4" }
+viewer = { features = ["viewer"] }
 
 [tasks]
 # --rerun-triggers mtime: don't redo finished steps (e.g. the conversion) just

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

@@ -425,6 +425,12 @@ def _build_method_fn(cfg):
             # Cellpose where they are. setdefault so an explicit
             # cellpose.channel_axis in the config still wins.
             extra.setdefault("channel_axis", 0)
+        # do_3D without anisotropy assumes isotropic voxels, which fragments
+        # objects across z for any real (anisotropic) calibration -- fill it
+        # in from the image's own calibration the same way a custom
+        # function's voxel_size gets filled in, unless the config already
+        # set anisotropy explicitly.
+        extra = _with_voxel_size(cellpose_fn, extra, cfg)
         return cellpose_fn(
             cp.get("model", "cyto3"),
             gpu=cp.get("gpu", True),

{patchworks-2.6.7 → patchworks-2.6.8}/workflow/scripts/relate.py

@@ -155,9 +155,7 @@ def run_relations(
                 )
 
         ws_b = wb.create_sheet(title=b_name[:31])
-        ws_b.append(
-            [f"{b_name}_id", f"{a_name}_count", "total_overlap_voxels"]
-        )
+        ws_b.append([f"{b_name}_id", f"{a_name}_count", "total_overlap_voxels"])
         for b_id in b_ids:
             agg = per_b[b_id]
             ws_b.append([b_id, agg["count"], agg["overlap_voxels"]])

{patchworks-2.6.7 → patchworks-2.6.8}/workflow/scripts/run_multi.py

@@ -356,7 +356,9 @@ def _resolve_shared_tile_shape(
                 gpu_memory=gpu_bytes,
                 n_channels=n_channels,
             )
-        candidates.append(tuple(int(x) for x in sizer(image.shape, image.dtype)))
+        candidates.append(
+            tuple(int(x) for x in sizer(image.shape, image.dtype))
+        )
 
     tile_shape = min(candidates, key=lambda t: int(np.prod(t)))
     print(

patchworks-2.6.8/workflow/scripts/view.py

@@ -0,0 +1,47 @@
+"""Open an OME-ZARR store in napari, auto-loading every label group.
+
+Usage:
+    pixi run -e viewer napari /path/to/image.zarr
+    pixi run -e viewer napari /path/to/image.zarr --channel 1
+
+Needs the `viewer` pixi environment (`pixi install -e viewer`) -- napari's
+Qt/GUI dependencies live there, not in the default headless workflow env --
+and a display: an X11-forwarded SSH session (`ssh -X`) or a remote-desktop/
+VNC session. It cannot open over a plain headless SSH session.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from patchworks.plugins.napari import view_in_napari
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "image", help="OME-ZARR store to open, e.g. work_dir/image.zarr"
+    )
+    parser.add_argument(
+        "--channel",
+        type=int,
+        default=None,
+        help="show only this channel (default: every channel)",
+    )
+    parser.add_argument(
+        "--no-glasbey",
+        action="store_true",
+        help="use napari's default label colours instead of glasbey",
+    )
+    args = parser.parse_args()
+
+    # Leaving the labels argument at its default auto-loads every label
+    # group under <image>/labels/<name>/ as its own Labels layer -- exactly
+    # what's wanted here, so there is nothing further to wire up.
+    view_in_napari(
+        args.image, channel=args.channel, glasbey=not args.no_glasbey
+    )
+
+
+if __name__ == "__main__":
+    main()