patchworks 3.1.0__tar.gz → 3.3.0__tar.gz

{patchworks-3.1.0 → patchworks-3.3.0}/.github/workflows/test.yml

@@ -32,11 +32,9 @@ jobs:
         run: pytest -q --doctest-modules src
 
   other-platforms:
-    # Not yet verified on macOS or Windows (no CI ran there before), so this
-    # job reports without failing the build; promote it into the matrix
-    # above once it is green.
+    # Green on macOS and Windows since 2026-10-07: a failure there now fails
+    # the build like any other.
     runs-on: ${{ matrix.os }}
-    continue-on-error: true
     strategy:
       fail-fast: false
       matrix:

{patchworks-3.1.0 → patchworks-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 3.1.0
+Version: 3.3.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
@@ -52,6 +52,8 @@ Requires-Dist: bioio-lif; extra == 'bioio'
 Requires-Dist: bioio-nd2; extra == 'bioio'
 Requires-Dist: bioio-ome-tiff; extra == 'bioio'
 Requires-Dist: bioio-tifffile; extra == 'bioio'
+Provides-Extra: careamics
+Requires-Dist: careamics>=0.3; extra == 'careamics'
 Provides-Extra: cellpose
 Requires-Dist: cellpose>=3.0; extra == 'cellpose'
 Provides-Extra: cellpose3
@@ -99,7 +101,8 @@ Requires-Dist: pandas>=2.0; extra == 'review'
 Provides-Extra: workflow
 Requires-Dist: openpyxl; extra == 'workflow'
 Requires-Dist: pandas>=2.0; extra == 'workflow'
-Requires-Dist: snakemake-executor-plugin-slurm; extra == 'workflow'
+Requires-Dist: scikit-image; extra == 'workflow'
+Requires-Dist: snakemake-executor-plugin-slurm>=2.2; extra == 'workflow'
 Requires-Dist: snakemake>=8; extra == 'workflow'
 Description-Content-Type: text/markdown
 
@@ -154,6 +157,7 @@ pip install "patchworks[cellpose]"  # Cellpose plugin (>=3.0, v3 or v4)
 pip install "patchworks[cellpose3]" # Cellpose plugin, pinned to v3.x
 pip install "patchworks[cellpose4]" # Cellpose plugin, pinned to v4+
 pip install "patchworks[dog]"       # deconvolution + DoG plugin (pycudadecon)
+pip install "patchworks[careamics]" # Noise2Void denoising before segmenting
 pip install "patchworks[bioio]"     # convert any image format to OME-ZARR
 pip install "patchworks[imaris]"    # convert Imaris .ims files to OME-ZARR
 pip install "patchworks[napari]"    # interactive napari viewer plugin
@@ -457,6 +461,13 @@ Optional:
 - `cellpose` — Cellpose plugin, v3 or v4 (`patchworks[cellpose]`);
   pin with `[cellpose3]` or `[cellpose4]`
 - `pycudadecon` — deconvolution step of the `dog` plugin (`patchworks[dog]`)
+- `careamics` — denoise tiles before segmenting them (Noise2Void),
+  `patchworks[careamics]`
+- `plant-seg` — PlantSeg plugin (boundary U-Net + GASP/multicut), from
+  conda-forge only (`conda install -c conda-forge plant-seg`, or the
+  workflow's `pixi install -e plantseg`). The nuclei-seeded watershed plugin
+  needs only scikit-image. See the
+  [membrane cells guide](https://imcf.one/patchworks/guide/membrane_cells/).
 - `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
   (`patchworks[bioio]`)
 - `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)

{patchworks-3.1.0 → patchworks-3.3.0}/README.md

@@ -49,6 +49,7 @@ pip install "patchworks[cellpose]"  # Cellpose plugin (>=3.0, v3 or v4)
 pip install "patchworks[cellpose3]" # Cellpose plugin, pinned to v3.x
 pip install "patchworks[cellpose4]" # Cellpose plugin, pinned to v4+
 pip install "patchworks[dog]"       # deconvolution + DoG plugin (pycudadecon)
+pip install "patchworks[careamics]" # Noise2Void denoising before segmenting
 pip install "patchworks[bioio]"     # convert any image format to OME-ZARR
 pip install "patchworks[imaris]"    # convert Imaris .ims files to OME-ZARR
 pip install "patchworks[napari]"    # interactive napari viewer plugin
@@ -352,6 +353,13 @@ Optional:
 - `cellpose` — Cellpose plugin, v3 or v4 (`patchworks[cellpose]`);
   pin with `[cellpose3]` or `[cellpose4]`
 - `pycudadecon` — deconvolution step of the `dog` plugin (`patchworks[dog]`)
+- `careamics` — denoise tiles before segmenting them (Noise2Void),
+  `patchworks[careamics]`
+- `plant-seg` — PlantSeg plugin (boundary U-Net + GASP/multicut), from
+  conda-forge only (`conda install -c conda-forge plant-seg`, or the
+  workflow's `pixi install -e plantseg`). The nuclei-seeded watershed plugin
+  needs only scikit-image. See the
+  [membrane cells guide](https://imcf.one/patchworks/guide/membrane_cells/).
 - `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
   (`patchworks[bioio]`)
 - `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)

patchworks-3.3.0/docs/api/plugins/careamics.md

@@ -0,0 +1,11 @@
+# CAREamics denoising plugin
+
+See [Denoising first](../../guide/membrane_cells.md#denoising-first-careamics).
+
+::: patchworks.plugins.careamics.denoise_fn
+
+::: patchworks.plugins.careamics.denoise
+
+::: patchworks.plugins.careamics.train_n2v
+
+::: patchworks.plugins.careamics.training_crops

patchworks-3.3.0/docs/api/plugins/plantseg.md

@@ -0,0 +1,11 @@
+# PlantSeg plugin
+
+See [Cells from a membrane stain](../../guide/membrane_cells.md#plantseg).
+
+::: patchworks.plugins.plantseg.plantseg_fn
+
+::: patchworks.plugins.plantseg.fetch_model
+
+::: patchworks.plugins.plantseg.available_models
+
+::: patchworks.plugins.plantseg.rescale_factors

patchworks-3.3.0/docs/api/plugins/watershed.md

@@ -0,0 +1,11 @@
+# Nuclei-seeded watershed plugin
+
+See [Cells from a membrane stain](../../guide/membrane_cells.md).
+
+::: patchworks.plugins.watershed.watershed_fn
+
+::: patchworks.plugins.watershed.nuclei_seeds
+
+::: patchworks.plugins.watershed.foreground_mask
+
+::: patchworks.plugins.watershed.seeded_watershed

{patchworks-3.1.0 → patchworks-3.3.0}/docs/examples/dog.md

@@ -54,6 +54,24 @@ 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.
 
+## Thin, oblique objects: `connectivity`
+
+The thresholded voxels are joined into objects across shared **faces** by
+default. A cilium lying obliquely is a staircase of voxels touching only
+along edges or at corners, and comes out as a row of fragments.
+`connectivity=2` also joins voxels sharing an edge, `connectivity=3` (3-D)
+also a corner:
+
+```python
+fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02, connectivity=3)
+```
+
+The merge has to join tiles the same way, or objects crossing a tile
+boundary diagonally are split there: the workflow does this by itself; with
+the API, pass the same value to `merge_tile_labels(..., connectivity=3)`.
+The merged result is then exactly that of labelling the whole image at once,
+whatever the tile size.
+
 ## GPU
 
 ```python

{patchworks-3.1.0 → patchworks-3.3.0}/docs/guide/cli.md

@@ -25,8 +25,18 @@ patchworks tables scan.zarr --relate nuclei:cells
 
 # Look at the likely mistakes one by one and fix them (napari)
 patchworks review scan.zarr --expect cells:nuclei=1
+
+# Bring a store written by an older patchworks up to the OME-Zarr spec
+patchworks fix-metadata scan.zarr
 ```
 
+`patchworks fix-metadata` changes metadata only, in place: it gives every
+OME-Zarr 0.5 array its `dimension_names` (required by 0.5; versions before
+this one wrote none, which strict readers such as `ome-zarr-models` refuse),
+and drops surplus coarse levels from a label image with more pyramid levels
+than its image (the spec requires the same number). Running it twice
+changes nothing the second time.
+
 `patchworks review` without a window: `--summary` (counts and error
 estimate), `--export DIR --format csv|xlsx|parquet` (corrected tables),
 `--workbooks DIR` (relation workbooks), `--write-labels NAME` (a label image
@@ -46,7 +56,16 @@ gives a child touching no parent the nearest one. See
 | `custom` | any importable function | `--fn module:function`, `--fn-kwargs '{"k": 1}'` |
 
 Cellpose's anisotropy and the DoG plugin's voxel size are read from the
-store's own calibration, at the level being segmented.
+store's own calibration, at the level being segmented -- as is `voxel_size`
+for a custom function that takes one, such as the PlantSeg and watershed
+plugins: `--method custom --fn patchworks.plugins.plantseg:segment
+--fn-kwargs '{"segmentation": "gasp"}' --stitch iou` (`iou`: these fill
+space, so neighbouring cells touch at every seam).
+
+`--denoise MODEL` denoises every tile with a CAREamics model before any
+method segments it; `patchworks denoise-train STORE --channel 0 --out
+n2v.ckpt` trains one (Noise2Void, no ground truth). See
+[Cells from a membrane stain](membrane_cells.md).
 
 Tiling and stitching take the same options as
 [`tile_process`](../api/tile_process.md): `--tile-shape` (`z,y,x`, `auto` or

{patchworks-3.1.0 → patchworks-3.3.0}/docs/guide/custom_segmentation.md

@@ -29,6 +29,14 @@ That is the whole interface. Anything that turns an image tile into a label
 image works: classic image processing, StarDist, a trained model, an external
 binary you shell out to, …
 
+Ready-made ones ship with patchworks: `patchworks.plugins.dog` (spots,
+cilia), and for cells from a membrane stain `patchworks.plugins.watershed`
+(nuclei-seeded watershed) and `patchworks.plugins.plantseg` (PlantSeg) --
+see [Cells from a membrane stain](membrane_cells.md). With
+`nuclei_channel` set, the tile is `(2, z, y, x)`: `[channel,
+nuclei_channel]` on the first axis. Any method can also run on
+[denoised tiles](membrane_cells.md#denoising-first-careamics).
+
 ## Minimal example (no GPU, no deps beyond scikit-image)
 
 ```python

patchworks-3.3.0/docs/guide/membrane_cells.md

@@ -0,0 +1,283 @@
+# Cells from a membrane stain
+
+Epithelia, organoids and tissues are often imaged with a **membrane** (or
+cortex) marker plus a **nuclear** dye. Cellpose struggles there in a
+recognisable way: Cellpose 4 (`cpsam`) reads every channel it is given
+without a "cytoplasm" or "nucleus" role, so with a bright nuclear channel
+next to a faint membrane it segments the **nuclei**; and on the membrane
+alone, a wall that is faint in places merges two cells. Patchworks ships
+three plugins for this case, plus an optional denoising step in front of any
+method.
+
+| | Needs | Cells come from | Best when |
+| --- | --- | --- | --- |
+| [Nuclei-seeded watershed](#nuclei-seeded-watershed) | scikit-image | the membrane, flooded from the nuclei | every cell has one nucleus; start here |
+| [PlantSeg](#plantseg) | `plant-seg` (conda-forge) | a boundary U-Net, then GASP / multicut | the membrane is uneven or noisy |
+| [PlantSeg + nuclei](#plantseg) | same | the U-Net's boundaries and the nuclei | both of the above |
+| Cellpose, membrane only | cellpose | Cellpose | `nuclei_channel: null`, `do_3D: true` |
+| [Denoising first](#denoising-first-careamics) | `careamics` | any of these, on denoised tiles | noisy acquisitions |
+
+All of them are ordinary [custom functions](custom_segmentation.md): one
+config block, the same tiling, merge, tables and review as any other run.
+
+## Nuclei-seeded watershed
+
+The nuclei are the easy part of the image: bright, compact, separated. They
+say how many cells there are and where; flooding the membrane image from
+them grows each nucleus out to its cell's walls. A cell can then not be
+split (one seed each) or merged with its neighbour (two seeds never join),
+even across a gap in the wall.
+
+```yaml
+channel: 0              # membrane
+nuclei_channel: 1       # stacked onto each tile as [membrane, nuclei]
+method: "custom"
+label_name: "cyto_labels"
+stitch: "iou"           # required: see below
+custom:
+  module: "patchworks.plugins.watershed"
+  kwargs:
+    nuclei_min_size: 200    # voxels: specks smaller than a nucleus
+    foreground: "otsu"      # stop at the tissue edge
+    # max_radius_um: 15     # or: no further than this from the nucleus
+    # nuclei_threshold: 800 # intensity, if Otsu misses dim nuclei
+```
+
+`stitch: "iou"` is required with this plugin and with PlantSeg, and
+`prepare` refuses the config without it. They give every voxel to some
+cell, so neighbouring cells touch at every tile seam, and the default
+`"touch"` stitching would join each such pair: on a test grid of 12 cells
+cut by six tiles, 5 came out. `"iou"` joins two pieces only where both tiles
+agree on their overlap, and gives the 12. (From the command line, pass
+`--stitch iou` yourself: nothing checks it there.)
+
+Two nuclei touching each other give one seed, so one cell for two: raise
+`nuclei_threshold` if that happens -- or grow the cells from nuclei you have
+already segmented, with `seed_labels` instead of `nuclei_channel` (see
+[the example below](#how-seed_labels-works)). Each tile's halo (`overlap`) must hold a
+whole cell, as for any method.
+
+## PlantSeg
+
+[PlantSeg](https://github.com/kreshuklab/plant-seg) predicts cell
+boundaries with a 3-D U-Net trained on membrane stains, then partitions the
+boundary map into cells (supervoxels by a distance-transform watershed,
+merged by GASP, mutex watershed or multicut). A wall the U-Net sees at all
+gets closed by the partitioning, where Cellpose would merge across it.
+
+PlantSeg is on conda-forge only, so it has its own pixi environment:
+
+```bash
+export CONDA_OVERRIDE_CUDA=12.0   # login node without a GPU: see below
+pixi install -e plantseg
+pixi run -e plantseg plantseg-fetch generic_confocal_3D_unet   # once, with internet
+pixi run -e plantseg multi-slurm
+```
+
+```yaml
+method: "custom"
+stitch: "iou"                           # required, as for the watershed
+custom:
+  module: "patchworks.plugins.plantseg"
+  kwargs:
+    model: "generic_confocal_3D_unet"   # or generic_light_sheet_3D_unet, ...
+    segmentation: "gasp"                # gasp | mutex_ws | multicut | dt_watershed
+    beta: 0.6                           # lower merges more, higher splits more
+    foreground: "otsu"                  # a boundary U-Net puts cells everywhere
+```
+
+With `nuclei_channel` set, two more `segmentation` modes use the nuclei:
+
+- `"nuclei_watershed"` -- the U-Net's boundary map flooded from the nuclei:
+  the watershed above, on a much cleaner boundary image.
+- `"lifted_multicut"` -- PlantSeg's lifted multicut: supervoxels in one
+  nucleus pulled together, in different nuclei pushed apart.
+
+Each tile is resampled to the voxel size the model was trained at (from the
+image's own calibration, `rescale: true`), which matters more than any other
+setting for a pretrained U-Net; the prediction is resampled back.
+
+## Example: Cellpose nuclei + PlantSeg cells in one run
+
+The workflow ships this pairing ready to edit: Cellpose segments the nuclei,
+then PlantSeg grows the cells from **exactly those nuclei** -- one cell per
+nucleus Cellpose found -- and the two are related. Three files, next to
+`config/multi.yaml`:
+
+```yaml
+# config/multi_plantseg.yaml
+common: config/common.yaml           # input, work_dir, tile_shape, level: shared
+
+segmentations:
+- config/config_nuclei.yaml          # Cellpose "nuclei" model on channel 1
+- config/config_cyto_plantseg.yaml   # PlantSeg on channel 0, seeded by nuclei_labels
+
+relations:
+- a: nuclei_labels
+  b: cyto_labels
+  output: nuclei_to_cyto.xlsx
+
+review:                              # a sanity check: one nucleus per cell
+  expect:
+    cyto_labels:
+      nuclei_labels: 1
+```
+
+```yaml
+# config/config_nuclei.yaml (unchanged)
+channel: 1
+overlap: [4, 30, 30]
+method: "cellpose"
+label_name: "nuclei_labels"
+cellpose:
+  model: "nuclei"
+  diameter: 15
+  do_3D: true
+  gpu: true
+```
+
+```yaml
+# config/config_cyto_plantseg.yaml
+channel: 0                  # membrane
+seed_labels: "nuclei_labels" # each tile becomes [membrane, nuclei labels]
+overlap: [4, 40, 40]        # the halo must hold a whole cell
+stitch: "iou"               # cells touch at every seam: join on agreement only
+method: "custom"
+label_name: "cyto_labels"
+custom:
+  module: "patchworks.plugins.plantseg"
+  function: "segment"
+  kwargs:
+    model: "generic_confocal_3D_unet"   # generic_light_sheet_3D_unet for light-sheet
+    segmentation: "nuclei_watershed"    # U-Net boundaries flooded from the nuclei
+    foreground: "otsu"                  # keep the tissue only
+    # max_radius_um: 15
+```
+
+Set `input` and `work_dir` in `config/common.yaml`, then, from `workflow/`:
+
+```bash
+pixi install -e plantseg
+pixi run -e plantseg plantseg-fetch generic_confocal_3D_unet   # once, with internet
+pixi run -e plantseg multi-plantseg-dry                        # check the plan
+pixi run -e plantseg multi-plantseg-slurm                      # submit
+```
+
+Your own multi config with a PlantSeg segmentation in it runs the same
+way, from the same environment:
+
+```bash
+pixi run -e plantseg multi-slurm --config /path/to/my_multi.yaml
+```
+
+!!! note "`Virtual package '__cuda' does not match` on a login node"
+
+    The `plantseg` environment holds a CUDA build of PyTorch, and pixi
+    refuses to install or run an environment needing CUDA on a machine with
+    no GPU driver -- a login node. Only the GPU jobs need CUDA, and they
+    start the environment's Python directly, without pixi. Tell pixi on the
+    login node that a driver is there:
+
+    ```bash
+    export CONDA_OVERRIDE_CUDA=12.0   # any 12.x; put it in ~/.bashrc
+    ```
+
+    It must be set for every `pixi run -e plantseg ...` there, not only for
+    the install. Check the GPU nodes' driver supports CUDA 12 (`nvidia-smi`
+    in a GPU job prints "CUDA Version: 12.x" or later).
+
+The `-e plantseg` matters: every job runs in the environment the command
+was started from, and the default one has no PlantSeg. `run_multi` checks
+this before converting anything and says which environment to use (as it
+does for `denoise:`, which needs `-e careamics`).
+
+The `plantseg` environment is the default one plus PlantSeg and cupy, so
+the Cellpose run comes from it too, as does a cilia config with the DoG
+plugin's `use_gpu: true` (cupy) and deconvolution. Afterwards, `nuclei_to_cyto.xlsx` gives
+each nucleus its cell, and `pixi run -e viewer review <work_dir>/image.zarr`
+lists any cell not holding exactly one nucleus.
+
+### How `seed_labels` works
+
+- **Order.** `run_multi` starts the cells' config only once the config
+  producing `nuclei_labels` has finished; everything else listed (cilia,
+  say) runs alongside. If the nuclei fail, the cells are skipped, not run
+  without seeds. Two configs seeding each other are refused up front. A
+  dry run (`-n`) waits for nothing.
+- **Tiles.** The nuclei label image is stacked onto the membrane as each
+  tile's second channel, halo included, so neighbouring tiles see the same
+  nuclei and a cell crossing a seam is grown from the same nucleus on both
+  sides. Both runs must use the same `level`, which `run_multi` already
+  enforces; the plugin is told `seeds: "labels"` automatically.
+- **Seeds as given.** Two touching nuclei that Cellpose split stay two
+  cells; a dim nucleus Cellpose found still gets its cell. Cellpose's
+  mistakes carry over the same way: a nucleus split in two makes two
+  cells. Correcting the nuclei first (`patchworks review`, then
+  `--write-labels nuclei_labels` and `seed_labels: nuclei_labels_reviewed`)
+  gives the cells the corrected nuclei.
+- **On its own**, outside `run_multi`, the cells' config needs
+  `labels/nuclei_labels` already in `image.zarr`: `prepare` checks, and
+  stops with a message rather than segmenting without seeds.
+- **Re-segmenting the nuclei** does not re-run the cells by itself: delete
+  `<work_dir>/cyto_labels` and `image.zarr/labels/cyto_labels` to grow them
+  again from the new nuclei.
+
+`nuclei_channel: 1` instead of `seed_labels` makes the plugin find the
+nuclei itself, in the nuclear stain (Otsu per tile, `nuclei_*` options),
+independently of Cellpose -- both segmentations then run at the same time.
+
+Without PlantSeg, the same works with the plain
+[nuclei-seeded watershed](#nuclei-seeded-watershed): set `module:
+"patchworks.plugins.watershed"` with only the `foreground` and
+`max_radius_um` keys, and use the default environment (`pixi run
+multi-slurm` with this pair listed in `config/multi.yaml`).
+
+## Cellpose: membrane only, in 3-D
+
+If you stay with Cellpose on such images:
+
+- Give it **only the membrane** (`nuclei_channel: null`): `cpsam` then has
+  nothing brighter to lock onto.
+- `do_3D: true` combines the three orthogonal views, so a wall faint in one
+  plane is found in the others. `stitch_threshold` instead joins
+  independent 2-D masks across z and fixes nothing in the masks
+  themselves. A GPU (`gpu: true`) only changes the speed.
+
+## Denoising first (CAREamics)
+
+Noise breaks segmentations: a wall lost in the noise merges two cells.
+[Noise2Void](https://careamics.github.io) learns to remove the noise from
+the image itself (no clean ground truth, no annotation), so a model trained
+once on a few crops of the store denoises every tile before any method sees
+it.
+
+```bash
+pixi install -e careamics
+# on a GPU node: the brightest crops of the channel, ~30 epochs
+pixi run -e careamics denoise-train <work_dir>/image.zarr --channel 0 --out n2v_membrane.ckpt
+pixi run -e careamics denoise-train <work_dir>/image.zarr --channel 1 --out n2v_nuclei.ckpt
+```
+
+then, in the segmentation config, with any `method`:
+
+```yaml
+denoise:
+  model: "/path/to/n2v_membrane.ckpt"      # .ckpt, or a BioImage.IO .zip
+  nuclei_model: "/path/to/n2v_nuclei.ckpt" # optional, for nuclei_channel
+  # tile_size: [16, 256, 256]              # CAREamics' tiling inside a tile (VRAM)
+```
+
+and run from the `careamics` environment (`plantseg-careamics` for both).
+The model paths are checked during `prepare`; the denoised image is not
+stored, only used for segmenting. From the command line, `patchworks segment
+... --denoise n2v_membrane.ckpt` does the same.
+
+Look at a denoised tile before a full run:
+
+```python
+from patchworks import load_ome_zarr
+from patchworks.plugins.careamics import denoise
+
+tile = load_ome_zarr("image.zarr", channel=0)[20:44, 1000:1512, 1000:1512]
+clean = denoise(tile.compute(), model="n2v_membrane.ckpt")
+```

{patchworks-3.1.0 → patchworks-3.3.0}/docs/guide/review.md

@@ -223,9 +223,13 @@ image.zarr/labels/cilia_labels/
 So it travels with the labels, including in a zip bundle, and it is
 replaced whenever the labels are. A table computed from older labels is
 recognised and ignored, never shown against the wrong segmentation.
-Measuring costs one read of the labels, after the merge. Add intensity
-columns with `table_channels: [0, 2]`, or turn tables off with
-`object_table: false` (see the [workflow config](snakemake.md)).
+The table costs no extra read of the labels: each segment job measures
+its tiles' objects as it writes them, and the merge adds those sums up per
+merged object (an object cut by tile boundaries gets exactly the values it
+would have measured whole). Intensity columns (`table_channels: [0, 2]`)
+need the image, so with them the merged labels are measured once instead.
+Turn tables off with `object_table: false` (see the
+[workflow config](snakemake.md)).
 
 For a store that has none, for example a run made before tables existed,
 or labels from elsewhere:

{patchworks-3.1.0 → patchworks-3.3.0}/docs/guide/snakemake.md

@@ -363,8 +363,12 @@ shard_labels: false            # true → also reshard label level 0 after the
     one blob). Set either, both, or neither (`null`, the default, disables
     each). Both run once on the **fully merged** image — not per tile, where
     an object crossing a tile boundary would look smaller or larger than it
-    really is. Runs after `merge` and before the pyramid is built, so every
-    pyramid level reflects the filtered result, and needs `image.zarr` to
+    really is. The sizes come from what the segment jobs measured per tile,
+    added up per merged object, and the filter is applied in the merge's
+    own relabelling pass, so it costs no pass of its own over the image
+    (runs whose tiles were segmented by an older version filter the merged
+    labels in a separate pass instead). Every pyramid level reflects the
+    filtered result. It needs `image.zarr` to
     carry a pixel size (the same calibration deconvolution's voxel sizes and
     Cellpose's `anisotropy` are derived from — see the tip below); an
     uncalibrated store raises rather than silently skipping the filter. See
@@ -650,6 +654,14 @@ running the workflow **twice with two configs against the same `work_dir`**
 never collides: each run gets its own private subdirectory, and both reuse
 the *same* already-converted `image.zarr` (conversion never re-runs).
 
+`labels.done` is what makes Snakemake call a segmentation finished, while
+the labels themselves are in `image.zarr/labels/<label_name>`. Deleting only
+the latter leaves the run "done" with nothing re-making it: `run_multi`
+refuses that up front and names the `work_dir/<label_name>` folder to remove
+for a fresh segmentation. It also refuses a relation naming a label image
+that no listed config makes and the store does not hold, and skips (with a
+message) a relation whose labels are still missing once everything has run.
+
 Most of what those configs contain is identical — the input, the `work_dir`,
 the tiling, everything `convert` reads. Put it in **one** shared file and let
 each config carry only what actually differs. Snakemake merges several
@@ -696,6 +708,14 @@ cellpose:
 usually improves cytoplasm segmentation. Both indices are 0-based, like
 `channel`.
 
+!!! tip "Cellpose 4 and a bright nuclear channel"
+
+    `cpsam` gives the two channels no roles, so next to a faint membrane it
+    may segment the nuclei instead of the cells. Give it the membrane alone
+    (`nuclei_channel: null`), or use the nuclei the other way round: as
+    seeds, with the nuclei-seeded watershed or PlantSeg plugins. See
+    [Cells from a membrane stain](membrane_cells.md).
+
 Only the `segment` step reads it. The pair is stacked on a leading axis that
 is *carried* into each tile rather than tiled, so the tile geometry, the
 occupancy map and the staged labels are byte-for-byte what a single-channel
@@ -802,9 +822,10 @@ results/image.zarr/labels/cyto_labels/
     rule, so it doesn't get a `log:` directive for free. Standalone (or
     under plain `multi`), it writes to `<work_dir>/logs/relate.log`
     (override with `relate.py --log`), the same tee-to-file-and-stdout
-    behaviour as the other steps. Under `multi-slurm`, where each pair is
-    its own concurrent job, `run_multi.py` points each one at its own file
-    instead — `<work_dir>/logs/relate/<a>_to_<b>.log` — so concurrent pairs
+    behaviour as the other steps. Under `multi-slurm`, where each parent's
+    relations are one concurrent job, `run_multi.py` points each job at its
+    own file instead — `<work_dir>/logs/relate/to_<parent>.log`, or
+    `<a>_to_<b>.log` for a parent with a single child — so concurrent jobs
     don't interleave into one log; check there instead of scrolling back
     through `srun`'s live output.
 
@@ -833,6 +854,11 @@ relations:
     output: nuclei_to_cyto.xlsx # written into work_dir
 ```
 
+A second example, `config/multi_plantseg.yaml`, pairs Cellpose nuclei with
+PlantSeg cells seeded from the nuclei (`pixi run -e plantseg
+multi-plantseg-slurm`); see [Cells from a membrane
+stain](membrane_cells.md#example-cellpose-nuclei-plantseg-cells-in-one-run).
+
 `common:` is optional — leave it out and each config must be self-contained,
 as before. With it, changing the input path or turning on `shard` is a
 one-line edit in one file instead of the same edit repeated per config.
@@ -843,6 +869,19 @@ pixi run multi        # run locally
 pixi run multi-slurm  # submit every segmentation to SLURM
 ```
 
+They read `config/multi.yaml` unless given another with `--config`:
+
+```bash
+pixi run multi-slurm --config /data/run42/multi.yaml
+pixi run multi-dry --config my_multi.yaml   # relative to where you run pixi
+```
+
+A relative `--config` is looked for in the directory you run `pixi` from,
+then in `workflow/`. The `common:` and `segmentations:` paths inside it are
+looked for next to the multi config first, then in `workflow/` -- so a run's
+configs can live together in a folder of their own, beside the data, while
+the shipped `config/multi.yaml` keeps working as it is.
+
 Before anything is submitted, the script checks that every listed config
 shares one `work_dir` (so `label_relations` has a single `image.zarr` to read
 both label groups from), that `tile_shape` and `level` are identical (so the
@@ -880,7 +919,7 @@ abort the others; you get a per-config status and a non-zero exit.
     # config/multi.yaml
     relate:
       qos: "1day"
-      time: 720        # minutes, per pair; must stay under that QOS's MaxWall
+      time: 720        # minutes, per job (one per parent); under the QOS's MaxWall
     ```
 
     A `--relate-*` flag overrides the block for that one key; anything the
@@ -889,18 +928,23 @@ abort the others; you get a per-config status and a non-zero exit.
     default you meant to replace. Under plain `multi` (no `--profile`), relations
     still run locally, in-process, one after another, as before.
 
-    Each pair logs its shape, chunk count and object count before it starts,
-    then a progress line roughly once a minute (`label_relations: 412/3,600
-    (11%) after 7m, ~55m left`), so a long relation is distinguishable from a
-    hung one in `logs/relate/<a>_to_<b>.log`.
-
-    Because every pair gets its own job, one running long no longer starves
-    the others out of a shared time budget, and a pair that gets killed no
-    longer takes an already-finished sibling's workbook down with it.
-    `relate.py` also skips a pair whose `.xlsx` is already newer than both
-    labels' merge marker, so **re-running the exact same `multi-slurm`
-    command only recomputes what's still missing or stale** — delete a
-    specific `.xlsx` yourself to force just that one to recompute.
+    The relations are grouped by parent: one job reads each parent label
+    image once for all its children (e.g. nuclei, cilia and the other cell
+    segmentation against `cyto_labels`), and only the chunks some child has
+    labels in. Each job logs its images' shape, chunking and object counts
+    before it starts, then a progress line roughly once a minute
+    (`label_relations: 412/3,600 (11%) after 7m, ~55m left`), so a long
+    relation is distinguishable from a hung one in `logs/relate/`.
+
+    Because each parent gets its own job, one running long does not starve
+    the others out of a shared time budget. `relate.py` skips a pair whose
+    workbook (the `.xlsx`, or the two `.csv` files a sheet too long for
+    Excel is written as) is already newer than both labels' merge marker,
+    and rewrites a missing workbook from the object tables when they
+    already hold the relation for the current labels, so **re-running the
+    exact same `multi-slurm` command only recomputes what's still missing
+    or stale** — delete a specific workbook to force just that one. The
+    bundle is likewise left alone when nothing in the store changed.
 
 !!! tip "After a killed run"
     Snakemake only releases its lock on a clean exit, so a run that was killed
@@ -1075,6 +1119,11 @@ pixi run go           # run locally (8 cores)
 pixi run slurm        # submit to SLURM (edit profile/slurm/config.yaml first)
 ```
 
+Optional environments add methods: `-e plantseg` (PlantSeg, from
+conda-forge), `-e careamics` (the `denoise:` step and `pixi run denoise-train`),
+`-e plantseg-careamics` for both -- see
+[Cells from a membrane stain](membrane_cells.md).
+
 `pixi run …` activates the env, so the rule scripts execute in that env — do
 **not** pass `--use-conda`. On a cluster, keep the `workflow/` directory on a
 shared filesystem the compute nodes can read: the SLURM executor re-launches