patchworks 0.11.18__tar.gz → 0.11.20__tar.gz

{patchworks-0.11.18 → patchworks-0.11.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 0.11.18
+Version: 0.11.20
 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,6 +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[all]>=0.7.1; extra == 'all'
 Requires-Dist: numpy<2.5; extra == 'all'
 Requires-Dist: nvidia-ml-py; extra == 'all'
@@ -74,6 +75,7 @@ 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[all]>=0.7.1; extra == 'napari'
 Requires-Dist: numpy<2.5; extra == 'napari'
 Provides-Extra: workflow

{patchworks-0.11.18 → patchworks-0.11.20}/docs/guide/snakemake.md

@@ -236,6 +236,12 @@ snakemake --workflow-profile profile/slurm --configfile config/config_nuclei.yam
 snakemake --workflow-profile profile/slurm --configfile config/config_cyto.yaml
 ```
 
+!!! tip "One command for several segmentations + relations"
+    `config/multi.yaml` lists any number of segmentation configs plus which
+    pairs to relate afterward; `pixi run multi` (or `multi-slurm`) runs them
+    in order and writes a CSV per pair — see *One command: multiple
+    segmentations + relations* below for the config format.
+
 Both land side by side in the same store:
 
 ```text
@@ -281,6 +287,43 @@ with open("nuclei_to_cell.csv", "w", newline="") as f:
         w.writerow([nucleus_id, m["match"], m["overlap_voxels"], m["overlap_fraction"]])
 ```
 
+### One command: multiple segmentations + relations
+
+`scripts/run_multi.py` (wired up as `pixi run multi`) sequences the above
+manually: run every segmentation config listed, then compute + save every
+configured relation — one command instead of juggling several `snakemake`
+calls and a separate Python step.
+
+```yaml
+# config/multi.yaml
+segmentations:
+  - config/config_nuclei.yaml
+  - config/config_cyto.yaml
+
+relations:
+  - a: nuclei_labels
+    b: cyto_labels
+    output: nuclei_to_cyto.csv # written into work_dir
+```
+
+```bash
+pixi run multi-dry    # dry-run every segmentation config (skips relations)
+pixi run multi        # run locally
+pixi run multi-slurm  # submit every segmentation to SLURM
+```
+
+Every listed segmentation config must share the same `work_dir` (so
+`label_relations` has one `image.zarr` to read both label groups from) — the
+script checks this and errors out otherwise. `relations` is optional; omit it
+to just chain segmentations without a relation step.
+
+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 +
+membrane you'd add `nuclei_labels -> cyto_labels`, `nuclei_labels ->
+membrane_labels`, and `cyto_labels -> membrane_labels` as three separate
+entries under `relations`.
+
 ## Measurements (fast, whole-volume regionprops)
 
 `skimage.measure.regionprops` needs the full labelled + intensity array in

{patchworks-0.11.18 → patchworks-0.11.20}/pyproject.toml

@@ -67,12 +67,16 @@ 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
+#   (area/centroid/intensity stats) for huge Labels layers, straight off
+#   their backing dask/zarr arrays — the "Measure" dock widget.
 napari = [
     "napari[all]>=0.7.1",
     "numpy<2.5",
     "ipykernel<7",
     "lxml-html-clean",
     "glasbey",
+    "napari-dask-ndmeasure>=0.1.0",
 ]
 # workflow runs the Snakemake pipeline (per-tile SLURM jobs across GPUs).
 workflow = ["snakemake>=8", "snakemake-executor-plugin-slurm"]

{patchworks-0.11.18 → patchworks-0.11.20}/src/patchworks/_relations.py

@@ -14,7 +14,9 @@ import numpy as np
 logger = logging.getLogger(__name__)
 
 
-def _as_dask(source: Union["da.Array", str, Path], component: str) -> "da.Array":
+def _as_dask(
+    source: Union["da.Array", str, Path], component: str
+) -> "da.Array":
     if isinstance(source, (str, Path)):
         return da.from_zarr(str(source), component=component)
     return source
@@ -96,7 +98,9 @@ def label_relations(
 
     def _one(flat_idx: int) -> np.ndarray:
         idx = np.unravel_index(flat_idx, n_blocks)
-        return _chunk_pairs(np.asarray(a.blocks[idx]), np.asarray(b.blocks[idx]))
+        return _chunk_pairs(
+            np.asarray(a.blocks[idx]), np.asarray(b.blocks[idx])
+        )
 
     with ThreadPoolExecutor(max_workers=nw) as ex:
         parts = list(ex.map(_one, range(total)))
@@ -130,7 +134,9 @@ def label_relations(
             best[a_id] = (b_id, count)
 
     logger.info(
-        "label_relations: %d a-labels matched across %d chunks", len(best), total
+        "label_relations: %d a-labels matched across %d chunks",
+        len(best),
+        total,
     )
     return {
         a_id: {

{patchworks-0.11.18 → patchworks-0.11.20}/src/patchworks/plugins/napari.py

@@ -299,7 +299,9 @@ def view_in_napari(
     img = _resolve_image(image, channel)
     img_ndim = img[0].ndim if isinstance(img, list) else img.ndim
     img_scale, img_units = (
-        _pyramid_calibration(image, img_ndim) if _is_zarr(image) else (None, None)
+        _pyramid_calibration(image, img_ndim)
+        if _is_zarr(image)
+        else (None, None)
     )
     viewer = napari.Viewer()
     viewer.add_image(

{patchworks-0.11.18 → patchworks-0.11.20}/workflow/README.md

@@ -86,6 +86,15 @@ the one converted `image.zarr` and land side by side in
 for the two-config recipe and `patchworks.label_relations()` for mapping one
 segmentation onto the other (e.g. nucleus → containing cell).
 
+One command instead of juggling several manual runs: list your configs (and
+which label pairs to relate) in `config/multi.yaml`, then:
+
+```bash
+pixi run multi-dry    # dry-run every segmentation config
+pixi run multi        # run locally
+pixi run multi-slurm  # submit every segmentation to SLURM
+```
+
 ## Output
 
 `<work_dir>/image.zarr` — the image plus `labels/<label_name>/` (multi-scale,

patchworks-0.11.20/workflow/config/config_cyto.yaml

@@ -0,0 +1,33 @@
+# Example segmentation config: cytoplasm/membrane channel.
+# Paired with config_nuclei.yaml via config/multi.yaml — see
+# docs/guide/snakemake.md "Running two segmentations". Same work_dir as
+# config_nuclei.yaml, and the same tile_shape so patchworks.label_relations()
+# can compare the two label arrays chunk-for-chunk.
+
+input: "/path/to/scan.ims"
+work_dir: "/path/to/results"
+
+reuse_pyramid: false
+convert_chunks: null
+shard: false
+
+channel: 0 # cytoplasm/membrane channel
+level: 0
+tile_shape: [16, 1024, 1024] # keep identical to config_nuclei.yaml
+gpu_memory_gb: null
+overlap: 30
+skip_empty: true
+empty_threshold: null
+
+method: "cellpose"
+label_name: "cyto_labels"
+cellpose:
+  model: "cyto3"
+  diameter: 30
+  do_3D: true
+  gpu: true
+
+pyramid_levels: 5
+pyramid_downscale: 2
+sequential_labels: true
+merge_workers: null

patchworks-0.11.20/workflow/config/config_nuclei.yaml

@@ -0,0 +1,33 @@
+# Example segmentation config: nuclei channel.
+# Paired with config_cyto.yaml via config/multi.yaml — see
+# docs/guide/snakemake.md "Running two segmentations". Both configs share
+# work_dir (and thus image.zarr) with config_cyto.yaml, but keep tile_shape
+# identical across the two so patchworks.label_relations() can compare them.
+
+input: "/path/to/scan.ims"
+work_dir: "/path/to/results"
+
+reuse_pyramid: false
+convert_chunks: null
+shard: false
+
+channel: 1 # nuclear stain channel
+level: 0
+tile_shape: [16, 1024, 1024] # keep identical to config_cyto.yaml
+gpu_memory_gb: null
+overlap: 30
+skip_empty: true
+empty_threshold: null
+
+method: "cellpose"
+label_name: "nuclei_labels"
+cellpose:
+  model: "nuclei"
+  diameter: 15
+  do_3D: true
+  gpu: true
+
+pyramid_levels: 5
+pyramid_downscale: 2
+sequential_labels: true
+merge_workers: null

patchworks-0.11.20/workflow/config/multi.yaml

@@ -0,0 +1,21 @@
+# 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.
+#
+# 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
+# comparable — see docs/guide/snakemake.md "Running two segmentations".
+#
+# Both lists are plain lists: 3+ segmentations work the same way — add more
+# entries to `segmentations`, then list whichever pairs you want related in
+# `relations` (there's no automatic "chain"; list every pair explicitly, e.g.
+# nuclei->cyto, nuclei->membrane, cyto->membrane).
+
+segmentations:
+- config/config_nuclei.yaml
+- config/config_cyto.yaml
+
+relations:
+- a: nuclei_labels
+  b: cyto_labels
+  output: nuclei_to_cyto.csv

{patchworks-0.11.18 → patchworks-0.11.20}/workflow/pixi.toml

@@ -1,8 +1,11 @@
 # pixi environment for the patchworks Snakemake workflow.
 #   pixi install
-#   pixi run dry      # dry-run (plan only)
-#   pixi run go       # run locally
-#   pixi run slurm    # submit to SLURM (edit profile/slurm/config.yaml first)
+#   pixi run dry          # dry-run (plan only)
+#   pixi run go           # run locally
+#   pixi run slurm        # submit to SLURM (edit profile/slurm/config.yaml first)
+#   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
 #
 # 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.
@@ -38,3 +41,11 @@ cellpose4 = { features = ["cp4"], solve-group = "cp4" }
 dry = "snakemake -s Snakefile --configfile config/config.yaml --rerun-triggers mtime -n -p"
 go = "snakemake -s Snakefile --configfile config/config.yaml --rerun-triggers mtime --cores 8"
 slurm = "snakemake --workflow-profile profile/slurm --configfile config/config.yaml"
+
+# Run every segmentation config listed in config/multi.yaml (in order), then
+# relate their labels by voxel overlap (patchworks.label_relations) and write
+# a CSV per configured pair — see config/multi.yaml and
+# docs/guide/snakemake.md "Running two segmentations".
+multi-dry = "python scripts/run_multi.py --config config/multi.yaml -n"
+multi = "python scripts/run_multi.py --config config/multi.yaml"
+multi-slurm = "python scripts/run_multi.py --config config/multi.yaml --profile profile/slurm"

{patchworks-0.11.18 → patchworks-0.11.20}/workflow/scripts/merge.py

@@ -25,7 +25,9 @@ merged_store = str(Path(work_dir) / label_name / "_merged.zarr")
 # whatever cpus_per_task the "merge" rule was actually allocated in the SLURM
 # profile. Read the real allocation (SLURM_CPUS_PER_TASK) so the job uses all
 # the cores it's paying for; merge_workers: in config.yaml can still override.
-default_workers = int(os.environ.get("SLURM_CPUS_PER_TASK", os.cpu_count() or 4))
+default_workers = int(
+    os.environ.get("SLURM_CPUS_PER_TASK", os.cpu_count() or 4)
+)
 merged = merge_tile_labels(
     stage_path(work_dir, label_name),
     write_to=merged_store,

patchworks-0.11.20/workflow/scripts/run_multi.py

@@ -0,0 +1,160 @@
+"""Run several segmentation configs, then relate their labels by overlap.
+
+Usage:
+    python scripts/run_multi.py --config config/multi.yaml
+    python scripts/run_multi.py --config config/multi.yaml --profile profile/slurm
+    python scripts/run_multi.py --config config/multi.yaml -n   # dry-run only
+
+See config/multi.yaml and docs/guide/snakemake.md "Running two segmentations"
+for the config format. Each listed segmentation config is run as an ordinary
+`snakemake --configfile ...` invocation (this script is a thin sequencer, not
+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.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def _load_yaml(path: Path) -> dict:
+    return yaml.safe_load(path.read_text())
+
+
+def _run_snakemake(
+    configfile: Path,
+    *,
+    workflow_dir: Path,
+    profile: str | None,
+    cores: int,
+    dry_run: bool,
+) -> None:
+    cmd = [
+        "snakemake",
+        "-s",
+        str(workflow_dir / "Snakefile"),
+        "--configfile",
+        str(configfile),
+    ]
+    if profile:
+        cmd += ["--workflow-profile", profile]
+    else:
+        cmd += ["--cores", str(cores), "--rerun-triggers", "mtime"]
+    if dry_run:
+        cmd += ["-n", "-p"]
+    print(f"[run_multi] $ {' '.join(cmd)}", flush=True)
+    subprocess.run(cmd, check=True, cwd=workflow_dir)
+
+
+def _resolve(workflow_dir: Path, path_str: str) -> Path:
+    path = Path(path_str)
+    return path if path.is_absolute() else workflow_dir / path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--config", required=True, help="multi-segmentation config YAML"
+    )
+    parser.add_argument(
+        "--profile",
+        default=None,
+        help="Snakemake --workflow-profile (e.g. profile/slurm); omit to run locally",
+    )
+    parser.add_argument(
+        "--cores",
+        type=int,
+        default=8,
+        help="local run: --cores (ignored with --profile)",
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="pass -n -p to every Snakemake run; skips relations",
+    )
+    args = parser.parse_args()
+
+    workflow_dir = Path(__file__).resolve().parent.parent
+    multi_cfg_path = _resolve(workflow_dir, args.config)
+    multi_cfg = _load_yaml(multi_cfg_path)
+
+    seg_config_paths = [
+        _resolve(workflow_dir, c) for c in multi_cfg["segmentations"]
+    ]
+    for cfg_path in seg_config_paths:
+        _run_snakemake(
+            cfg_path,
+            workflow_dir=workflow_dir,
+            profile=args.profile,
+            cores=args.cores,
+            dry_run=args.dry_run,
+        )
+
+    relations = multi_cfg.get("relations", [])
+    if args.dry_run or not relations:
+        return
+
+    seg_cfgs = [_load_yaml(p) for p in seg_config_paths]
+    work_dirs = {cfg["work_dir"] for cfg in seg_cfgs}
+    if len(work_dirs) != 1:
+        print(
+            f"[run_multi] ERROR: segmentation configs use different work_dir "
+            f"({sorted(work_dirs)}); label_relations needs one shared "
+            "image.zarr to compare against.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    work_dir = work_dirs.pop()
+    image_store = f"{work_dir}/image.zarr"
+
+    import dask.array as da
+
+    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"
+        )
+        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(
+                    [
+                        a_id,
+                        m["match"],
+                        m["overlap_voxels"],
+                        m["overlap_fraction"],
+                    ]
+                )
+        print(f"[run_multi] wrote {out_path} ({len(table)} rows)", flush=True)
+
+
+if __name__ == "__main__":
+    main()