Merge branch dev: SLURM job naming and docs anchor fixes

Gives every SLURM job a recognisable name in the queue via the executor
plugin jobname prefix, set per config by run_multi so a three-way run shows
pw-convert then pw-nuclei_labels / pw-cyto_labels / pw-cilia_labels rather
than three indistinguishable UUIDs.

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

Author: lguerard

docs/guide/label_relations.md

@@ -24,7 +24,7 @@ table[2]
 `table` only contains matched `a` labels (nuclei with at least one
 overlapping voxel in `cells`) — unmatched labels and full per-`b` coverage
 need a bit more bookkeeping (the [cluster workflow's `run_multi.py`
-script](snakemake.md#one-command-multiple-segmentations--relations) does
+script](snakemake.md#one-command-multiple-segmentations-relations) does
 this for you and writes it as a two-sheet workbook).
 
 Save it as a table yourself:
@@ -41,4 +41,4 @@ with open("nuclei_to_cell.csv", "w", newline="") as f:
 
 On the cluster, producing the two label stores in the first place is a
 matter of running the workflow twice against the same `work_dir` — see
-[Running two segmentations](snakemake.md#running-two-segmentations-eg-nuclei--cytoplasm).
+[Running two segmentations](snakemake.md#running-two-segmentations-eg-nuclei-cytoplasm).

docs/guide/measurements.md

@@ -10,7 +10,7 @@ is built for this — its "Measure" dock widget computes area/centroid/intensity
 stats directly off a Labels layer's dask/zarr-backed array, out-of-core, and
 scales with chunk count rather than object count. It's the best fit for
 measuring *every* object in a store this size, not just a cropped region —
-see [View image + labels in napari](ome_zarr_napari.md#view-image--labels-in-napari).
+see [View image + labels in napari](ome_zarr_napari.md#view-image-labels-in-napari).
 Bundled in `patchworks[napari]`.
 
 For interactively inspecting individual cells by clicking in the viewer (not

docs/guide/snakemake.md

@@ -187,6 +187,27 @@ Snakemake submits `convert`, then `prepare`, then **one `segment` job per
 batch of `tiles_per_job` non-empty tiles** (up to `jobs:` at once → that many
 GPUs in parallel), then `merge`. Raise `jobs:` to use more GPUs.
 
+!!! tip "Recognisable job names in `squeue`"
+    The SLURM executor names every job after its run UUID and **rejects** a
+    `--job-name` in `slurm_extra`, so by default `squeue` shows nothing you
+    can identify. A prefix is the supported lever, and it goes first in the
+    name (`<prefix>_<uuid>`) — the part a queue listing truncates to:
+
+    ```yaml
+    slurm-jobname-prefix: patchworks    # already in the shipped profile
+    ```
+
+    `run_multi` overrides it per config, so a three-way run shows
+    `pw-convert`, then `pw-nuclei_labels` / `pw-cyto_labels` /
+    `pw-cilia_labels` — telling the concurrent runs apart at a glance:
+
+    ```bash
+    squeue -u $USER -o '%.18i %.24j %.8T %.10M'
+    ```
+
+    Alphanumerics, underscores and hyphens only, 50 characters max; an
+    invalid prefix fails the run, so `label_name` is sanitised before use.
+
 !!! tip "Sizing memory"
     Every step now sizes its own worker counts from what SLURM actually
     granted (`SLURM_CPUS_PER_TASK`, `SLURM_MEM_PER_*`, the cgroup limit)

tests/test_run_multi.py

@@ -0,0 +1,38 @@
+"""Tests for the multi-config driver's SLURM-facing behaviour."""
+
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(
+    0, str(Path(__file__).resolve().parents[1] / "workflow" / "scripts")
+)
+
+from run_multi import slurm_jobname_prefix  # noqa: E402
+
+# The SLURM executor's own rule (snakemake_executor_plugin_slurm): it raises a
+# WorkflowError and aborts the whole run if the prefix does not match.
+_EXECUTOR_RULE = re.compile(r"^[A-Za-z0-9_-]{1,50}$")
+
+
+def test_jobname_prefix_satisfies_the_executor():
+    """Whatever a label_name contains, the prefix must stay submittable.
+
+    The executor names jobs after a UUID and refuses a --job-name override, so
+    this prefix is the only thing that makes squeue readable -- and an invalid
+    one fails the run rather than degrading.
+    """
+    for label in ("nuclei_labels", "cyto_labels", "convert", "a"):
+        assert _EXECUTOR_RULE.match(slurm_jobname_prefix(label))
+
+    # Characters a label might plausibly pick up are sanitised, not passed on.
+    assert _EXECUTOR_RULE.match(slurm_jobname_prefix("cilia/v2 (test)"))
+    assert _EXECUTOR_RULE.match(slurm_jobname_prefix("run 1: nuclei"))
+    # And an over-long label is truncated to the executor's 50-char limit.
+    assert _EXECUTOR_RULE.match(slurm_jobname_prefix("x" * 200))
+
+
+def test_jobname_prefix_keeps_the_label_readable():
+    """The label must lead, since that is what a queue listing truncates to."""
+    assert slurm_jobname_prefix("nuclei_labels") == "pw-nuclei_labels"
+    assert slurm_jobname_prefix("convert") == "pw-convert"

workflow/profile/slurm/config.yaml

@@ -5,6 +5,14 @@
 # Edit the partitions / account / GPU request for your cluster.
 
 executor: slurm
+# The SLURM executor names every job after its run UUID and rejects a
+# --job-name in slurm_extra, so `squeue` shows nothing recognisable without
+# this. The prefix goes first in the name (<prefix>_<uuid>), which is the part
+# that survives truncation in a queue listing.
+# Alphanumerics, underscores and hyphens only; 50 characters max.
+# run_multi overrides this per config, so a three-way run shows pw-convert,
+# then pw-nuclei_labels / pw-cyto_labels / pw-cilia_labels.
+slurm-jobname-prefix: patchworks
 # Max concurrent SLURM jobs Snakemake will have in flight at once. This is a
 # submission-side cap, not a cluster limit — raising it just lets more
 # "segment" tiles queue/run together; scicore's scheduler still enforces your

workflow/scripts/run_multi.py

@@ -26,6 +26,7 @@
 from __future__ import annotations
 
 import argparse
+import re
 import subprocess
 import sys
 from pathlib import Path
@@ -47,6 +48,7 @@ def _snakemake_cmd(
     state_dir: Path | None = None,
     targets: list[str] | None = None,
     extra: list[str] | None = None,
+    jobname_prefix: str | None = None,
 ) -> list[str]:
     """Build one snakemake invocation.
 
@@ -66,6 +68,9 @@ def _snakemake_cmd(
         cmd += ["--directory", str(state_dir.resolve())]
     if profile:
         cmd += ["--workflow-profile", str((workflow_dir / profile).resolve())]
+        if jobname_prefix:
+            # A SLURM-executor setting, so only valid alongside the profile.
+            cmd += ["--slurm-jobname-prefix", jobname_prefix]
     else:
         cmd += ["--cores", str(cores), "--rerun-triggers", "mtime"]
     if dry_run:
@@ -79,6 +84,29 @@ def _snakemake_cmd(
     return cmd
 
 
+def slurm_jobname_prefix(label: str) -> str:
+    """Sanitise *label* into a SLURM job-name prefix the executor accepts.
+
+    The SLURM executor names every job after its run UUID and refuses a
+    ``--job-name`` in ``slurm_extra``, so a prefix is the only way to get
+    something recognisable into ``squeue``. It becomes ``<prefix>_<uuid>``,
+    which puts the readable part first -- the part that survives truncation
+    in a queue listing.
+
+    The executor requires alphanumerics, underscores and hyphens only, at
+    most 50 characters, and rejects the whole run otherwise.
+
+    Examples
+    --------
+    >>> slurm_jobname_prefix("nuclei_labels")
+    'pw-nuclei_labels'
+    >>> slurm_jobname_prefix("cilia/v2 (test)")
+    'pw-cilia-v2--test-'
+    """
+    safe = re.sub(r"[^A-Za-z0-9_-]", "-", label)
+    return f"pw-{safe}"[:50]
+
+
 def _run(cmd: list[str], workflow_dir: Path) -> int:
     print(f"[run_multi] $ {' '.join(cmd)}", flush=True)
     return subprocess.run(cmd, cwd=workflow_dir).returncode
@@ -235,6 +263,7 @@ def main() -> None:
             dry_run=args.dry_run,
             state_dir=Path(work_dir) / ".snakemake_convert",
             targets=[f"{image_store}/zarr.json"],
+            jobname_prefix=slurm_jobname_prefix("convert"),
         ),
         workflow_dir,
     )
@@ -287,6 +316,8 @@ def main() -> None:
             cores=args.cores,
             dry_run=args.dry_run,
             state_dir=Path(cfg["work_dir"]) / cfg["label_name"] / ".snakemake",
+            # Names the config in squeue, so concurrent runs are tellable apart.
+            jobname_prefix=slurm_jobname_prefix(cfg["label_name"]),
         )
         print(f"[run_multi] $ {' '.join(cmd)}", flush=True)
         procs.append((cfg_path.name, subprocess.Popen(cmd, cwd=workflow_dir)))