patchworks 1.1.0__tar.gz → 1.2.0__tar.gz

{patchworks-1.1.0 → patchworks-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 1.1.0
+Version: 1.2.0
 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-dask-ndmeasure>=0.1.0; extra == 'all'
+Requires-Dist: napari-chunked-regionprops>=0.1.0; 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'
@@ -64,6 +64,8 @@ Requires-Dist: tqdm; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: dog
+Requires-Dist: pycudadecon; extra == 'dog'
 Provides-Extra: gpu
 Requires-Dist: nvidia-ml-py; extra == 'gpu'
 Provides-Extra: imaris
@@ -75,10 +77,11 @@ Provides-Extra: napari
 Requires-Dist: glasbey; extra == 'napari'
 Requires-Dist: ipykernel<7; extra == 'napari'
 Requires-Dist: lxml-html-clean; extra == 'napari'
-Requires-Dist: napari-dask-ndmeasure>=0.1.0; extra == 'napari'
+Requires-Dist: napari-chunked-regionprops>=0.1.0; extra == 'napari'
 Requires-Dist: napari[all]>=0.7.1; extra == 'napari'
 Requires-Dist: numpy<2.5; extra == 'napari'
 Provides-Extra: workflow
+Requires-Dist: openpyxl; extra == 'workflow'
 Requires-Dist: snakemake-executor-plugin-slurm; extra == 'workflow'
 Requires-Dist: snakemake>=8; extra == 'workflow'
 Description-Content-Type: text/markdown

{patchworks-1.1.0 → patchworks-1.2.0}/cliff.toml

@@ -11,8 +11,9 @@ body = """
 {% if github.contributors | length > 0 %}
 ### 👥 Contributors
 
-{% for contributor in github.contributors | sort(attribute="username") %}\
-* @{{ contributor.username }}
+{% for contributor in github.contributors %}\
+{% if contributor.username %}* @{{ contributor.username }}
+{% endif %}\
 {% endfor %}
 {% endif %}\
 """

patchworks-1.2.0/docs/api/plugins/dog.md

@@ -0,0 +1,3 @@
+# Difference-of-Gaussians (dog) plugin
+
+::: patchworks.plugins.dog.dog_label_fn

patchworks-1.2.0/docs/examples/dog.md

@@ -0,0 +1,110 @@
+# Difference of Gaussians (blobs, threads, cilia, …)
+
+A lightweight blob/thread detector for structures Cellpose isn't shaped for
+(cilia, spots, fibres): blur twice at different sigmas, subtract, threshold,
+label the connected components. CPU (scipy) by default, GPU (cupy) optional.
+Optionally deconvolve each tile first with
+[pycudadecon](https://github.com/tlambert03/pycudadecon).
+
+## Installation
+
+`dog_label_fn` itself only needs patchworks' core deps (scipy). The
+deconvolution step needs pycudadecon:
+
+```bash
+pip install "patchworks[dog]"
+```
+
+GPU blur/label (`use_gpu=True`) needs `cupy` too, matching your CUDA version
+(e.g. `pip install cupy-cuda12x`) — not bundled in the `dog` extra since it's
+CUDA-version-specific.
+
+## Code
+
+```python
+import numpy as np
+from patchworks import tile_process
+from patchworks.plugins.dog import dog_label_fn
+
+IMAGE = "image.zarr"
+OUTPUT = "labels_dog.zarr"
+
+fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02)
+
+tile_process(
+    IMAGE,
+    fn,
+    channel=1,
+    tile_shape=(1, 1024, 1024),
+    overlap=8,  # just needs to cover one object + high_sigma
+    write_to=OUTPUT,
+    progress=True,
+)
+```
+
+## Picking `low_sigma` / `high_sigma` / `threshold`
+
+`dog = blur(low_sigma) - blur(high_sigma)`. `low_sigma` should be about the
+object's radius (denoises without erasing it); `high_sigma` a few times
+larger (models the background to subtract out). `threshold` is applied
+directly to the DoG image — start near the DoG's typical peak value on a
+known-positive region and adjust from there; there's no auto (Otsu-style)
+option, since the DoG image isn't bimodal the way a raw intensity image is.
+
+## GPU
+
+```python
+fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02, use_gpu=True)
+```
+
+Requires `cupy` (matching your CUDA version, e.g. `pip install cupy-cuda12x`)
+— not a patchworks dependency, install it separately.
+
+## With deconvolution first
+
+```python
+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,
+    ),
+)
+result = tile_process(IMAGE, fn, tile_shape=(1, 1024, 1024), overlap=32)
+```
+
+!!! 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
+    running this needs a GPU allocated. Widen `overlap` past the PSF support
+    so edge tiles keep enough context (a plain intensity/threshold halo is
+    too thin).
+
+## Using it in the Snakemake workflow
+
+No dedicated wiring needed — `patchworks.plugins.dog` exposes a `segment(tile, **kwargs)`
+adapter for the documented [`"custom"` method](../guide/snakemake.md#custom-segmentation-function):
+
+```yaml
+method: "custom"
+label_name: "cilia_labels"
+custom:
+  module: "patchworks.plugins.dog"
+  function: "segment"
+  kwargs:
+    low_sigma: 1.0
+    high_sigma: 3.0
+    threshold: 0.02
+```
+
+See `workflow/config/config_cilia.yaml` for a full example, including
+deconvolution.
+
+## Relating cilia to their cell
+
+Segment the cell body with Cellpose and the cilia with `dog_label_fn` as two
+separate `tile_process` runs (same image, same `tile_shape`), then use
+[`label_relations`](../guide/snakemake.md#relating-labels-across-segmentations)
+to map each cilium to the cell it belongs to — see
+`workflow/config/multi.yaml` for the same thing wired up as a cluster job.

patchworks-1.2.0/docs/examples/dog.py

@@ -0,0 +1,24 @@
+"""Difference-of-Gaussians blob/thread segmentation (e.g. cilia).
+
+Blur twice at different sigmas, subtract, threshold, label the connected
+components. CPU (scipy) by default.
+"""
+
+from patchworks import tile_process
+from patchworks.plugins.dog import dog_label_fn
+
+IMAGE = "image.zarr"
+OUTPUT = "labels_dog.zarr"
+CHANNEL = 1
+
+fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02)
+
+tile_process(
+    IMAGE,
+    fn,
+    channel=CHANNEL,
+    tile_shape=(1, 1024, 1024),
+    overlap=8,
+    write_to=OUTPUT,
+    progress=True,
+)

{patchworks-1.1.0 → patchworks-1.2.0}/docs/guide/snakemake.md

@@ -303,7 +303,7 @@ segmentations:
 relations:
   - a: nuclei_labels
     b: cyto_labels
-    output: nuclei_to_cyto.csv # written into work_dir
+    output: nuclei_to_cyto.xlsx # written into work_dir
 ```
 
 ```bash
@@ -317,6 +317,19 @@ Every listed segmentation config must share the same `work_dir` (so
 script checks this and errors out otherwise. `relations` is optional; omit it
 to just chain segmentations without a relation step.
 
+Each `output:` is an Excel workbook (`openpyxl`, part of the `workflow`
+extra) with two sheets:
+
+| Sheet | One row per | Columns |
+| --- | --- | --- |
+| `<a>` | every non-background `a` label, **including unmatched ones** | `<a>_id`, `<b>_id` (blank if unmatched), `overlap_voxels`, `overlap_fraction` (0 if unmatched) |
+| `<b>` | every non-background `b` label, **including ones with zero matches** | `<b>_id`, `<a>_count`, `total_overlap_voxels` |
+
+Unlike calling `label_relations()` directly (which only returns matched `a`
+labels — see below), the workbook always covers every object in both
+segmentations, so counts (e.g. "how many nuclei have no matching cell",
+"how many cells have zero cilia") aren't silently dropped.
+
 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 +
@@ -324,6 +337,14 @@ membrane you'd add `nuclei_labels -> cyto_labels`, `nuclei_labels ->
 membrane_labels`, and `cyto_labels -> membrane_labels` as three separate
 entries under `relations`.
 
+The shipped `config/multi.yaml` is actually a three-way example: nuclei +
+cytoplasm (Cellpose) plus cilia (`method: "custom"` ->
+[`patchworks.plugins.dog`](../examples/dog.md), deconvolution + a
+difference-of-Gaussians detector), related both ways (`cilia_labels ->
+cyto_labels` and `cilia_labels -> nuclei_labels`) so you can use whichever
+fits a given dataset. See `config/config_cilia.yaml`. Its deconvolution step
+needs `pip install "patchworks[dog]"` in the segment jobs' environment.
+
 ## Measurements (fast, whole-volume regionprops)
 
 `skimage.measure.regionprops` needs the full labelled + intensity array in

{patchworks-1.1.0 → patchworks-1.2.0}/mkdocs.yml

@@ -48,6 +48,7 @@ nav:
   - Cellpose 2-D: examples/cellpose_2d.md
   - Cellpose 3-D: examples/cellpose_3d.md
   - StarDist: examples/stardist.md
+  - Difference of Gaussians: examples/dog.md
   - Custom function: examples/custom.md
   - Standalone merge: examples/standalone_merge.md
 - API Reference:
@@ -59,6 +60,7 @@ nav:
   - Cluster helpers: api/cluster.md
   - Plugins:
     - Cellpose: api/plugins/cellpose.md
+    - Difference of Gaussians: api/plugins/dog.md
     - OME-ZARR conversion: api/plugins/ome_zarr.md
     - napari viewer: api/plugins/napari.md
 

{patchworks-1.1.0 → patchworks-1.2.0}/pyproject.toml

@@ -43,6 +43,11 @@ io = ["psutil", "tqdm"]
 cellpose = ["cellpose>=3.0"]
 cellpose3 = ["cellpose>=3.0,<4"]
 cellpose4 = ["cellpose>=4"]
+# dog enables the deconvolution step in patchworks.plugins.dog (method:
+# "custom" -> segment). cupy, for that plugin's use_gpu=True blur/label
+# path, isn't included here — it's CUDA-version-specific (e.g.
+# cupy-cuda12x), install it separately to match your CUDA version.
+dog = ["pycudadecon"]
 gpu = ["nvidia-ml-py"]
 # bioio enables converting any image format (CZI, LIF, ND2, OME-TIFF, …) to
 # OME-ZARR. Ships the common native readers (faster than going through Java)
@@ -67,19 +72,23 @@ imaris = ["imaris-ims-file-reader"]
 # - 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-dask-ndmeasure: out-of-core regionprops-style measurements
+# - napari-chunked-regionprops: out-of-core regionprops-style measurements
 #   (area/centroid/intensity stats) for huge Labels layers, straight off
-#   their backing dask/zarr arrays — the "Measure" dock widget.
+#   their backing dask/zarr arrays — the "Measure" dock widget. Formerly
+#   napari-dask-ndmeasure; renamed when its engine dropped dask_image.ndmeasure
+#   for a chunk-local map/merge that scales with chunk count, not object count.
 napari = [
     "napari[all]>=0.7.1",
     "numpy<2.5",
     "ipykernel<7",
     "lxml-html-clean",
     "glasbey",
-    "napari-dask-ndmeasure>=0.1.0",
+    "napari-chunked-regionprops>=0.1.0",
 ]
 # workflow runs the Snakemake pipeline (per-tile SLURM jobs across GPUs).
-workflow = ["snakemake>=8", "snakemake-executor-plugin-slurm"]
+# openpyxl -> scripts/run_multi.py writes label_relations() output as an
+# Excel workbook (per-object + per-container sheets), not a plain CSV.
+workflow = ["snakemake>=8", "snakemake-executor-plugin-slurm", "openpyxl"]
 dev = ["pytest", "pytest-cov", "scikit-image", "psutil", "tqdm"]
 docs = ["mkdocs-material>=9.0", "mkdocstrings[python]>=0.24"]
 all = [

patchworks-1.2.0/src/patchworks/plugins/dog.py

@@ -0,0 +1,202 @@
+"""Difference-of-Gaussians plugin for patchworks.
+
+Optional deconvolution (pycudadecon) followed by a DoG blob/spot detector:
+threshold the difference of two Gaussian blurs and label connected
+components. CPU (scipy) or GPU (cupy) backed.
+
+Usage
+-----
+>>> from patchworks.plugins.dog import dog_label_fn
+>>> from patchworks import tile_process
+>>>
+>>> fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02)
+>>> result = tile_process("image.zarr", fn, tile_shape=(1, 2048, 2048),
+...                       overlap=8, write_to="labels.zarr", progress=True)
+
+With deconvolution first (widen ``overlap`` to cover the PSF support):
+
+>>> 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=wavelength, na=numerical_aperture,
+...                        nimm=refractive_index),
+... )
+>>> result = tile_process("image.zarr", fn, tile_shape=(1, 2048, 2048), overlap=32)
+
+For the Snakemake workflow's ``method: "custom"`` (see
+docs/guide/snakemake.md "Custom segmentation function"), use the
+:func:`segment` adapter instead of the factory directly:
+
+>>> # custom: {module: "patchworks.plugins.dog", function: "segment",
+>>> #          kwargs: {low_sigma: 1.0, high_sigma: 3.0, threshold: 0.02}}
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any, Callable
+
+import numpy as np
+
+
+def _require_cupy():
+    """Raise an actionable ImportError if cupy is not installed.
+
+    Returns
+    -------
+    None
+    """
+    try:
+        import cupy  # noqa: F401
+        import cupyx.scipy.ndimage  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(
+            "cupy is not installed. Install a build matching your CUDA "
+            "version (e.g. pip install cupy-cuda12x), or use use_gpu=False "
+            "for the CPU (scipy) path."
+        ) from exc
+
+
+def _require_pycudadecon():
+    """Raise an actionable ImportError if pycudadecon is not installed.
+
+    Returns
+    -------
+    None
+    """
+    try:
+        import pycudadecon  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(
+            "pycudadecon is not installed. Install it with:\n"
+            "    pip install pycudadecon\n"
+            "or drop decon_kwargs to skip deconvolution."
+        ) from exc
+
+
+def dog_label_fn(
+    low_sigma: float | tuple[float, ...],
+    high_sigma: float | tuple[float, ...],
+    threshold: float,
+    *,
+    use_gpu: bool = False,
+    decon_kwargs: dict[str, Any] | None = None,
+) -> Callable[[np.ndarray], np.ndarray]:
+    """Return a ready-to-use DoG labeler for ``tile_process``.
+
+    Parameters
+    ----------
+    low_sigma, high_sigma:
+        Gaussian sigmas (pixels) for the narrow/wide blur.
+        ``dog = blur(low_sigma) - blur(high_sigma)``.
+    threshold:
+        Binary threshold applied to the DoG image (``dog > threshold``).
+    use_gpu:
+        Run gaussian_filter + label on GPU via cupy/cupyx instead of scipy.
+        Independent of ``decon_kwargs`` — pycudadecon always needs a CUDA
+        GPU regardless of this flag (it takes/returns plain NumPy), and this
+        flag only picks the backend for the blur/label steps that follow.
+    decon_kwargs:
+        If given, each tile is first deconvolved via
+        ``pycudadecon.decon(block, **decon_kwargs)`` before the DoG step.
+        ``None`` (default) skips deconvolution. pycudadecon is CUDA-only, so
+        a SLURM job running this needs a GPU allocated regardless of
+        ``use_gpu`` above. Widen ``tile_process``'s ``overlap`` to cover the
+        PSF support when deconvolving, so edge tiles don't get truncated
+        context.
+
+    Returns
+    -------
+    Callable[[ndarray], ndarray]
+        Picklable function ready for ``tile_process``.
+    """
+    if use_gpu:
+        _require_cupy()
+    if decon_kwargs is not None:
+        _require_pycudadecon()
+    cfg = {
+        "low_sigma": low_sigma,
+        "high_sigma": high_sigma,
+        "threshold": threshold,
+        "use_gpu": use_gpu,
+        "decon_kwargs": decon_kwargs,
+    }
+    return partial(_run, dog_dict=cfg)
+
+
+def _run(block: np.ndarray, dog_dict: dict[str, Any]) -> np.ndarray:
+    """Deconvolve (optional), then DoG-threshold-label one tile.
+
+    Parameters
+    ----------
+    block : np.ndarray
+        One image tile.
+    dog_dict : dict
+        Configuration from :func:`dog_label_fn`.
+
+    Returns
+    -------
+    np.ndarray
+        Integer (``int32``) label array of the same shape.
+    """
+    img = block.astype("float32")
+
+    decon_kwargs = dog_dict["decon_kwargs"]
+    if decon_kwargs is not None:
+        # ponytail: re-inits the GPU/OTF context on every tile via the
+        # one-shot decon() API. Ceiling: per-tile setup cost dominates on
+        # many small tiles. Upgrade: cache a pycudadecon.RLContext per
+        # worker process (see cellpose.py's _model_cache) if that shows up
+        # in the per-tile timing that tile_process logs.
+        from pycudadecon import decon
+
+        img = decon(images=img, **decon_kwargs)
+
+    use_gpu = dog_dict["use_gpu"]
+    if use_gpu:
+        import cupy as cp
+        from cupyx.scipy.ndimage import gaussian_filter, label
+
+        img = cp.asarray(img)
+    else:
+        from scipy.ndimage import gaussian_filter, label
+
+    low_blur = gaussian_filter(img, sigma=dog_dict["low_sigma"])
+    high_blur = gaussian_filter(img, sigma=dog_dict["high_sigma"])
+    dog_image = low_blur - high_blur
+    mask = dog_image > dog_dict["threshold"]
+    labels, _ = label(mask)
+    labels = labels.astype("int32")
+
+    return cp.asnumpy(labels) if use_gpu else labels
+
+
+def segment(tile: np.ndarray, **kwargs: Any) -> np.ndarray:
+    """``dog_label_fn`` as a direct-call function for ``method: "custom"``.
+
+    Snakemake's ``custom`` method (see docs/guide/snakemake.md) calls
+    ``segment(tile, **kwargs)`` directly rather than building a factory
+    first. This adapts :func:`dog_label_fn` to that contract, so this
+    plugin needs no dedicated wiring in the workflow's ``build_fn`` —
+    ``method: "custom"`` with ``module: "patchworks.plugins.dog"`` already
+    covers it.
+
+    Parameters
+    ----------
+    tile : np.ndarray
+        One image tile.
+    **kwargs : Any
+        Forwarded to :func:`dog_label_fn` (``low_sigma``, ``high_sigma``,
+        ``threshold``, ``use_gpu``, ``decon_kwargs``).
+
+    Returns
+    -------
+    np.ndarray
+        Integer (``int32``) label array of the same shape.
+    """
+    return dog_label_fn(**kwargs)(tile)
+
+
+# Keep the lower-level name available for advanced users
+run_dog_label = _run

{patchworks-1.1.0 → patchworks-1.2.0}/src/patchworks/plugins/napari.py

@@ -187,8 +187,8 @@ def _label_hint(path: Union[str, Path]) -> dict[str, Any]:
     during the merge) — the exact id set is then ``range(1, n_objects +
     1)`` by construction, with no scan needed. Passed through as a Labels
     layer's ``metadata`` so a downstream consumer (e.g.
-    napari-dask-ndmeasure) can use it instead of re-deriving the id set
-    from the array itself.
+    napari-chunked-regionprops) can use it instead of re-deriving the id
+    set from the array itself.
 
     Parameters
     ----------

{patchworks-1.1.0 → patchworks-1.2.0}/src/patchworks/plugins/ome_zarr.py

@@ -1083,8 +1083,8 @@ def register_labels(
         ``sequential_labels=True``, which means ``ids == range(1, n_objects
         + 1)`` by construction). When given, written into the label group's
         attrs as ``n_objects``/``sequential_labels`` so a downstream reader
-        (e.g. napari-dask-ndmeasure) can use the known id set instead of
-        re-deriving it with a full-volume scan of its own.
+        (e.g. napari-chunked-regionprops) can use the known id set instead
+        of re-deriving it with a full-volume scan of its own.
 
     Returns
     -------

patchworks-1.2.0/tests/test_dog.py

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

patchworks-1.2.0/workflow/config/config_cilia.yaml

@@ -0,0 +1,50 @@
+# Example segmentation config: cilia channel, via method: "custom" ->
+# patchworks.plugins.dog.segment (deconvolution + difference-of-Gaussians).
+# Cilia are thin/small structures a cell-body model like Cellpose isn't
+# shaped for. Paired with config_cyto.yaml / config_nuclei.yaml via
+# config/multi.yaml to relate cilia -> containing cell / nucleus. Same
+# work_dir and tile_shape as those two so patchworks.label_relations() can
+# compare the label arrays chunk-for-chunk.
+#
+# pycudadecon is CUDA-only, so this segment job needs a GPU too — same
+# profile/slurm as the Cellpose configs already covers it.
+
+input: "/path/to/scan.ims"
+work_dir: "/path/to/results"
+
+reuse_pyramid: false
+convert_chunks: null
+shard: false
+
+channel: 2 # cilia marker channel
+level: 0
+tile_shape: [16, 1024, 1024] # keep identical to config_cyto.yaml/config_nuclei.yaml
+gpu_memory_gb: null
+overlap: 30 # cover the PSF support (decon) + the DoG's high_sigma
+skip_empty: true
+empty_threshold: null
+
+method: "custom"
+label_name: "cilia_labels"
+custom:
+  module: "patchworks.plugins.dog"
+  function: "segment"
+  kwargs:
+    low_sigma: 1.0
+    high_sigma: 3.0
+    threshold: 0.02
+    # 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
+      wavelength: 525
+      na: 1.4
+      nimm: 1.515
+
+pyramid_levels: 5
+pyramid_downscale: 2
+sequential_labels: true
+merge_workers: null

{patchworks-1.1.0 → patchworks-1.2.0}/workflow/config/multi.yaml

@@ -1,6 +1,8 @@
 # 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.
+# voxel overlap (patchworks.label_relations) and writes an Excel workbook per
+# pair (two sheets: one row per a-object incl. unmatched ones, one row per
+# b-object incl. ones with zero matches — see docs/guide/snakemake.md).
 #
 # 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
@@ -14,8 +16,15 @@
 segmentations:
 - config/config_nuclei.yaml
 - config/config_cyto.yaml
+- config/config_cilia.yaml
 
 relations:
 - a: nuclei_labels
   b: cyto_labels
-  output: nuclei_to_cyto.csv
+  output: nuclei_to_cyto.xlsx
+- a: cilia_labels
+  b: cyto_labels
+  output: cilia_to_cell.xlsx
+- a: cilia_labels
+  b: nuclei_labels
+  output: cilia_to_nucleus.xlsx

{patchworks-1.1.0 → patchworks-1.2.0}/workflow/pixi.toml

@@ -19,8 +19,10 @@ platforms = ["linux-64"]
 python = "3.12.*"
 
 # Default env uses patchworks[cellpose] (>=3.0, resolves to latest compatible).
+# "dog" -> pycudadecon, for config_cilia.yaml's deconvolution step (part of
+# the shipped config/multi.yaml example).
 [pypi-dependencies]
-patchworks = { version = "*", extras = ["workflow", "cellpose", "imaris", "bioio"] }
+patchworks = { version = "*", extras = ["workflow", "cellpose", "imaris", "bioio", "dog"] }
 
 # Cellpose-version-pinned features for explicit environments below.
 [feature.cp3.pypi-dependencies]

{patchworks-1.1.0 → patchworks-1.2.0}/workflow/scripts/run_multi.py

@@ -12,13 +12,15 @@ 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.
+patchworks.label_relations and written as an Excel workbook in work_dir,
+with two sheets: one row per a-object (unmatched ones included, with an
+empty b-id and zeros) and one row per b-object (a-object count + total
+overlap, including b-objects with zero matches).
 """
 
 from __future__ import annotations
 
 import argparse
-import csv
 import subprocess
 import sys
 from pathlib import Path
@@ -121,31 +123,51 @@ def main() -> None:
     image_store = f"{work_dir}/image.zarr"
 
     import dask.array as da
+    import openpyxl
 
     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"
+            "output", f"{a_name}_to_{b_name}.xlsx"
         )
         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(
+        # label_relations() only returns a-objects that touch a b-object.
+        # Pull the full id sets so unmatched a-objects (zero overlap) and
+        # b-objects with no matches at all still get a row -- otherwise
+        # they'd silently vanish instead of counting as zero.
+        a_ids = sorted(int(x) for x in da.unique(a[a > 0]).compute())
+        b_ids = sorted(int(x) for x in da.unique(b[b > 0]).compute())
+
+        per_b = {b_id: {"count": 0, "overlap_voxels": 0} for b_id in b_ids}
+        for m in table.values():
+            agg = per_b.get(m["match"])
+            if agg is not None:
+                agg["count"] += 1
+                agg["overlap_voxels"] += m["overlap_voxels"]
+
+        wb = openpyxl.Workbook()
+        ws_a = wb.active
+        ws_a.title = a_name[:31]  # Excel sheet-name length limit
+        ws_a.append(
+            [
+                f"{a_name}_id",
+                f"{b_name}_id",
+                "overlap_voxels",
+                "overlap_fraction",
+            ]
+        )
+        for a_id in a_ids:
+            m = table.get(a_id)
+            if m is None:
+                ws_a.append([a_id, None, 0, 0])  # no overlap -- still counted
+            else:
+                ws_a.append(
                     [
                         a_id,
                         m["match"],
@@ -153,7 +175,19 @@ def main() -> None:
                         m["overlap_fraction"],
                     ]
                 )
-        print(f"[run_multi] wrote {out_path} ({len(table)} rows)", flush=True)
+
+        ws_b = wb.create_sheet(title=b_name[:31])
+        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"]])
+
+        wb.save(out_path)
+        print(
+            f"[run_multi] wrote {out_path} "
+            f"({len(a_ids)} {a_name}, {len(b_ids)} {b_name})",
+            flush=True,
+        )
 
 
 if __name__ == "__main__":