refactor(workflow): ♻️ keep the method list in one place

The validator repeated the dispatcher's list of built-in methods, so adding
one meant editing two places that could silently disagree. Both now read
KNOWN_METHODS.

Also adds the missing test for relabel_sequential_zarr: the merge folds the
sequential renumbering into its own LUT now, so nothing internal exercised
that function any more, even though it stays public API for label stores
written by other pipelines.

Documents that a new segmentation method needs no change to patchworks at
all -- method: "custom" imports any (tile) -> labels callable and inherits
the empty-tile skipping, per-job batching, boundary stitching and pyramid --
and that custom.kwargs are checked against the target's signature in
`prepare`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: lguerard

docs/guide/custom_segmentation.md

@@ -118,6 +118,18 @@ 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 "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
+    package changes. It then inherits everything the pipeline does: empty
+    tiles are skipped, tiles are batched per job, labels are stitched across
+    boundaries and renumbered, and the result is written as a calibrated
+    pyramid.
+
+    (The `KNOWN_METHODS` list in `workflow/scripts/_pw.py` is only for
+    *built-in* shortcuts like `"cellpose"`. Adding to it is for methods that
+    ship with patchworks, not for your own.)
+
 ## Test it before you submit
 
 Run your function on one real tile first — it catches shape/dtype bugs in
@@ -148,6 +160,9 @@ custom:
   module: "my_seg"        # import name
   function: "segment"     # default is "segment"
   kwargs:                 # optional — forwarded as segment(tile, **kwargs)
+  #                         checked against your function's signature during
+  #                         `prepare`, so a typo fails on a cheap CPU job
+  #                         rather than in the first GPU job hours later
     sigma: 1.5
 ```
 

tests/test_core.py

@@ -290,6 +290,36 @@ def test_relabel_sequential_array():
     assert np.all(uniq == np.arange(1, len(uniq) + 1))
 
 
+def test_relabel_sequential_zarr(tmp_path):
+    """The standalone zarr relabeller stays correct on its own.
+
+    The merge folds this into its LUT now, so nothing internal exercises it —
+    but it is public API for label stores written by other pipelines.
+    """
+    import zarr
+
+    from patchworks import relabel_sequential_zarr
+
+    store = str(tmp_path / "labels.zarr")
+    root = zarr.open_group(store, mode="w")
+    root.create_array(name="labels", shape=(4, 8), chunks=(4, 4), dtype="i4")
+    data = np.zeros((4, 8), dtype="int32")
+    data[0, :3] = 500  # gappy ids spanning both chunks
+    data[1, 5:] = 7
+    data[3, 2] = 100000
+    root["labels"][:] = data
+
+    n = relabel_sequential_zarr(store, "labels")
+    out = np.asarray(zarr.open_group(store, mode="r")["labels"])
+
+    assert n == 3, f"three distinct objects, got {n}"
+    assert set(np.unique(out).tolist()) == {0, 1, 2, 3}, "must be contiguous"
+    # Same voxels keep the same id; background stays background.
+    assert len(set(out[0, :3].tolist())) == 1
+    assert len(set(out[1, 5:].tolist())) == 1
+    assert out[2, 0] == 0
+
+
 def test_estimate_empty_tiles():
     import dask.array as da
 

workflow/scripts/_pw.py

@@ -15,6 +15,12 @@
 
 from patchworks import load_ome_zarr
 
+# Segmentation methods `_build_method_fn` can dispatch. Adding one means
+# teaching that function to build it and adding the name here; the validator
+# reads this list so the two cannot drift apart. Most new methods need
+# neither: `method: "custom"` already imports any `(tile) -> labels` callable.
+KNOWN_METHODS = ("cellpose", "threshold", "custom")
+
 
 class _Tee:
     """Write to several streams at once (e.g. the SLURM log and a file)."""
@@ -181,11 +187,9 @@ def validate_config(cfg) -> None:
         problems.append(f"tile_shape must be positive integers; got {ts!r}")
 
     method = cfg.get("method", "cellpose")
-    if method not in ("cellpose", "threshold", "custom"):
-        problems.append(
-            f'method must be "cellpose", "threshold" or "custom"; got '
-            f"{method!r}"
-        )
+    if method not in KNOWN_METHODS:
+        listed = ", ".join(f'"{m}"' for m in KNOWN_METHODS)
+        problems.append(f"method must be one of {listed}; got {method!r}")
 
     if method == "cellpose":
         cp = cfg.get("cellpose")
@@ -297,7 +301,7 @@ def _build_method_fn(cfg):
     callable
         ``(ndarray) -> ndarray`` returning integer labels.
     """
-    method = cfg.get("method", "cellpose")
+    method = cfg.get("method", "cellpose")  # see KNOWN_METHODS
     if method == "custom":
         # Import a user-provided function, e.g.
         #   custom: {module: my_seg, function: segment, kwargs: {...}}