patchworks 2.6.11__tar.gz → 2.6.12__tar.gz

{patchworks-2.6.11 → patchworks-2.6.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 2.6.11
+Version: 2.6.12
 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

{patchworks-2.6.11 → patchworks-2.6.12}/docs/guide/snakemake.md

@@ -112,15 +112,60 @@ sequential_labels: true        # renumber labels to a contiguous 1..N
     [Filtering by size after merge](merging.md#filtering-by-size-after-merge)
     for the equivalent direct-API call.
 
+!!! warning "`model:` names are version-specific — check which Cellpose you have"
+    Cellpose 3 and 4 have **disjoint** model names: v3 has `cyto3`,
+    `nuclei`, …; v4 replaced them all with the `cpsam` family (`cpsam`,
+    `cpsam_v2`, `cpdino`, …). Neither version *raises* on a name it doesn't
+    know — v4 logs a warning and quietly loads its default (`cpsam_v2`)
+    instead. A `cyto3` left in a config against a v4 install therefore
+    segments every tile with a model you did not choose, and the only
+    evidence is one line in the job log.
+
+    patchworks now rejects an unavailable name in `prepare`, on the cheap
+    CPU job, rather than letting it through. Check what you have with
+    `python -c "import cellpose; print(cellpose.version)"`, then either pick
+    a name that install offers, point `model:` at a custom-trained model's
+    path, or install the version you want — the workflow ships `cellpose3`
+    and `cellpose4` pixi environments (`pixi install -e cellpose3`) for
+    exactly this.
+
 !!! tip "3-D anisotropy is derived automatically"
     Cellpose's `do_3D` assumes isotropic voxels unless told otherwise —
     without an `anisotropy`, a real (anisotropic) dataset gets objects
-    fragmented or distorted across z. `segment` now derives it from
+    fragmented or distorted across z. `segment` derives it from
     `image.zarr`'s own calibration (`z` voxel size ÷ lateral voxel size)
     whenever `do_3D: true` and `cellpose.anisotropy` isn't set explicitly, so
     there's usually nothing to configure. Set `anisotropy:` yourself in the
     `cellpose:` block to override it.
 
+    Note it is not just a hint to the model: Cellpose *resizes* the tile to
+    `z × anisotropy` planes before the net runs. `tile_shape: "auto"`
+    budgets for that resized tile, so a 2.2× anisotropy buys a
+    correspondingly smaller tile rather than an out-of-memory job.
+
+!!! warning "The physically-correct anisotropy is not always the best one"
+    Upsampling z by the true ratio can produce **ring artifacts** and costs
+    runtime proportional to the ratio. A contributor on
+    [cellpose#1408](https://github.com/MouseLand/cellpose/pull/1408) reports
+    that `anisotropy: 1` avoids the rings entirely and is much faster, at
+    the cost of boundaries being off by a few pixels in the top/bottom
+    z-planes, where a cell's cross-section changes fastest — and recommends
+    pairing it with light z-only flow smoothing:
+
+    ```yaml
+    cellpose:
+      do_3D: true
+      anisotropy: 1          # overrides the derived value
+      flow3D_smooth: [1, 0, 0]   # z, y, x -- smooth z only
+    ```
+
+    This is a genuine trade-off, not a strictly better setting, and it is
+    worth testing both on your own data rather than taking either on faith.
+    Reach for it especially if 3-D results look ringed or fragmented along
+    z: that is the symptom this addresses. `flow3D_smooth` accepts a scalar
+    on older Cellpose and a `[z, y, x]` list from the version that merged
+    that PR onward.
+
 !!! tip "Tile size vs runtime"
     `tile_shape: "auto"` sizes each tile to your GPU's VRAM. Smaller tiles =
     more (faster) jobs; very large 3-D tiles are slow. Keep `do_3D: false` (2-D

{patchworks-2.6.11 → patchworks-2.6.12}/src/patchworks/_chunks.py

@@ -380,6 +380,7 @@ def auto_tile_shape_cellpose(
     model_memory_bytes: int = 2 * 1024**3,
     cellpose_memory_factor: int = 20,
     n_channels: int = 1,
+    anisotropy: float | None = None,
     verbose: bool = False,
 ) -> tuple[int, ...]:
     """Cellpose-optimised tile shape.
@@ -426,6 +427,13 @@ def auto_tile_shape_cellpose(
         Channels each tile carries (default 1). Above 1 the per-voxel cost
         scales with it, so the tile shrinks accordingly -- e.g. the workflow's
         ``nuclei_channel`` hands Cellpose a cyto+nuclei pair.
+    anisotropy:
+        The ``anisotropy`` Cellpose will be given (``do_3D`` only). It is not
+        merely a hint to the model: Cellpose resizes the tile to
+        ``z * anisotropy`` planes before the net runs, so a 2.2x anisotropy
+        costs 2.2x the z it was handed. Budgeting against the unscaled ``z``
+        under-counts by exactly that factor. ``None`` (the default) assumes
+        isotropic, i.e. no resize.
     verbose:
         Log the chosen shape and memory estimates.
 
@@ -477,7 +485,12 @@ def auto_tile_shape_cellpose(
             chunk_spatial = [1, min(y, tile_side), min(x, tile_side)]
     else:
         z, y, x = shape[-3], shape[-2], shape[-1]
-        max_pixels_per_slice = max(1, (max_raw_bytes // 3) // (z * itemsize))
+        # Cellpose resizes z by `anisotropy` before the net runs, so the tile
+        # it actually holds is that much deeper than the one handed to it.
+        effective_z = z * max(1.0, anisotropy or 1.0)
+        max_pixels_per_slice = max(
+            1, int((max_raw_bytes // 3) // (effective_z * itemsize))
+        )
         tile_side = max(min_tile, int(max_pixels_per_slice**0.5))
         chunk_spatial = [z, min(y, tile_side), min(x, tile_side)]
 

{patchworks-2.6.11 → patchworks-2.6.12}/src/patchworks/plugins/cellpose.py

@@ -253,6 +253,26 @@ def _make_config(
     }
 
 
+def available_models() -> list[str]:
+    """Pretrained model names the installed Cellpose actually accepts.
+
+    The name set changed completely between major versions -- v3 ships
+    ``cyto3``/``nuclei``/… , v4 replaced them with ``cpsam``-family names --
+    and neither version raises on an unknown one. v4 falls back to its
+    default model with only a log line, so a v3 name in a v4 environment
+    segments everything with the wrong model and nothing fails. Checking the
+    name against this list turns that into a config error instead.
+
+    Returns
+    -------
+    list of str
+        Model names, or an empty list when Cellpose isn't installed or
+        doesn't publish them (in which case no name can be rejected).
+    """
+    names = getattr(_cellpose_models, "MODEL_NAMES", None)
+    return list(names) if names else []
+
+
 def _get_model(cellpose_dict: dict[str, Any]) -> Any:
     """Return a worker-local cached Cellpose model.
 
@@ -272,8 +292,14 @@ def _get_model(cellpose_dict: dict[str, Any]) -> Any:
         gpu = cellpose_dict.get("gpu", False)
         model_type = cellpose_dict["model"]
         if _CELLPOSE_V4:
+            # v4 renamed this: `model_type=` is accepted but explicitly
+            # ignored ("not used in v4.0.1+"), leaving pretrained_model at
+            # its "cpsam_v2" default -- so passing the configured name there
+            # silently segmented *every* config with the same default model,
+            # whatever `model:` said, with only a logger warning to show for
+            # it. `available_models()` rejects an unusable name up front.
             _model_cache[key] = _cellpose_models.CellposeModel(
-                model_type=model_type, gpu=gpu
+                pretrained_model=model_type, gpu=gpu
             )
         else:
             _model_cache[key] = _cellpose_models.Cellpose(

{patchworks-2.6.11 → patchworks-2.6.12}/tests/test_allocation.py

@@ -117,3 +117,32 @@ def test_gpu_tile_sizing_is_bounded_by_the_host_allocation(monkeypatch):
         "the 1 GiB host grant must shrink the tile below what the same "
         "24 GiB GPU would otherwise allow"
     )
+
+
+def test_auto_tile_shape_cellpose_budgets_for_the_anisotropy_resize():
+    """Cellpose resizes a do_3D tile to z * anisotropy planes before the net
+
+    runs, so budgeting against the unscaled z hands the GPU a tile that is
+    `anisotropy` times bigger than the estimate. Auto-deriving anisotropy
+    turned that from dormant into live, so the sizer has to know about it.
+    """
+    from patchworks import auto_tile_shape_cellpose
+
+    kwargs = dict(
+        shape=(64, 4096, 4096),
+        dtype="uint16",
+        do_3D=True,
+        use_gpu=True,
+        gpu_memory=8 * 1024**3,
+        available_memory=64 * 1024**3,
+    )
+    isotropic = auto_tile_shape_cellpose(**kwargs)
+    anisotropic = auto_tile_shape_cellpose(**kwargs, anisotropy=2.215)
+
+    # z is pinned to the full extent either way; the cost is paid in y/x.
+    assert anisotropic[0] == isotropic[0]
+    assert anisotropic[1] < isotropic[1]
+    assert anisotropic[2] < isotropic[2]
+    # An anisotropy at or below 1 cannot *grow* the budget.
+    assert auto_tile_shape_cellpose(**kwargs, anisotropy=1.0) == isotropic
+    assert auto_tile_shape_cellpose(**kwargs, anisotropy=0.5) == isotropic

{patchworks-2.6.11 → patchworks-2.6.12}/tests/test_cellpose.py

@@ -47,3 +47,27 @@ def test_cellpose_fn_declares_a_voxel_size_parameter():
     # model.eval() argument, not a patchworks-specific one) -- only the raw
     # calibration is a named parameter.
     assert "anisotropy" not in params
+
+
+def test_available_models_is_a_list():
+    """Empty when Cellpose isn't installed -- then no name can be rejected."""
+    from patchworks.plugins.cellpose import available_models
+
+    assert isinstance(available_models(), list)
+
+
+def test_v4_gets_the_model_name_as_pretrained_model():
+    """v4 accepts `model_type=` and then ignores it ("not used in v4.0.1+"),
+
+    leaving pretrained_model at its default -- so passing the configured name
+    there segmented every config with the same default model whatever
+    `model:` said. The name has to reach `pretrained_model=` on v4.
+    """
+    import inspect
+
+    from patchworks.plugins import cellpose as cp
+
+    src = inspect.getsource(cp._get_model)
+    v4_branch = src.split("if _CELLPOSE_V4:")[1].split("else:")[0]
+    assert "pretrained_model=model_type" in v4_branch
+    assert "model_type=model_type" not in v4_branch

{patchworks-2.6.11 → patchworks-2.6.12}/tests/test_pw.py

@@ -121,3 +121,44 @@ def test_validate_config_rejects_max_volume_at_or_below_min_volume():
         validate_config(
             {"method": "threshold", "min_volume": 500.0, "max_volume": 5.0}
         )
+
+
+def test_validate_config_rejects_a_model_the_install_does_not_have(
+    monkeypatch,
+):
+    """Cellpose does not raise on an unknown model name -- it logs and loads
+
+    its default. A v3 name against a v4 install therefore segments every
+    tile with a model nobody chose, silently. That has to fail in prepare.
+    """
+    import pytest
+    from _pw import validate_config
+
+    import patchworks.plugins.cellpose as cp
+
+    monkeypatch.setattr(cp, "available_models", lambda: ["cpsam", "cpsam_v2"])
+    with pytest.raises(ValueError, match="cyto3"):
+        validate_config({"method": "cellpose", "cellpose": {"model": "cyto3"}})
+
+
+def test_validate_config_accepts_a_model_the_install_has(monkeypatch):
+    from _pw import validate_config
+
+    import patchworks.plugins.cellpose as cp
+
+    monkeypatch.setattr(cp, "available_models", lambda: ["cpsam", "cpsam_v2"])
+    validate_config({"method": "cellpose", "cellpose": {"model": "cpsam"}})
+
+
+def test_validate_config_leaves_a_custom_model_path_alone(
+    monkeypatch, tmp_path
+):
+    """A path is a custom-trained model; no name list can vouch for it."""
+    from _pw import validate_config
+
+    import patchworks.plugins.cellpose as cp
+
+    monkeypatch.setattr(cp, "available_models", lambda: ["cpsam"])
+    custom = tmp_path / "my_model.pth"
+    custom.write_text("")
+    validate_config({"method": "cellpose", "cellpose": {"model": str(custom)}})

{patchworks-2.6.11 → patchworks-2.6.12}/workflow/scripts/_pw.py

@@ -322,29 +322,61 @@ def validate_config(cfg) -> None:
 
 def _cellpose_problems(cp: dict) -> list[str]:
     """Unknown keys in the ``cellpose:`` block, checked against model.eval."""
+    problems = _cellpose_model_problems(cp)
     known = ("model", "diameter", "do_3D", "gpu")
     extra = {k: v for k, v in cp.items() if k not in known}
     if not extra:
-        return []
+        return problems
     try:
         from patchworks.plugins.cellpose import _get_model
     except ImportError:
-        return []
+        return problems
     try:
         model = _get_model({"model": cp.get("model", "cyto3"), "gpu": False})
     except Exception:
         # Weights unavailable here (fetch_model runs separately); skip rather
         # than fail a config that may be perfectly fine.
-        return []
+        return problems
     unknown = _unknown_kwargs(
         model.eval, extra, skip=("channels", "channel_axis")
     )
     if unknown:
-        return [
+        problems.append(
             f"unknown cellpose: key(s) {unknown} -- these are forwarded to "
             "model.eval(), which does not accept them"
-        ]
-    return []
+        )
+    return problems
+
+
+def _cellpose_model_problems(cp: dict) -> list[str]:
+    """Reject a model name the installed Cellpose would silently substitute.
+
+    Cellpose 4 renamed the pretrained models outright, and does not raise on
+    an unknown name -- it logs and loads its default instead. A v3 name
+    (``cyto3``) left in a config against a v4 install therefore segments
+    every tile with the wrong model, silently. A path is left alone: that is
+    a custom-trained model, which no name list can vouch for.
+    """
+    name = cp.get("model", "cyto3")
+    if not isinstance(name, str) or Path(name).exists():
+        return []
+    try:
+        from patchworks.plugins.cellpose import available_models
+    except ImportError:
+        return []
+    names = available_models()
+    if not names or name in names:
+        return []
+    listed = ", ".join(f'"{n}"' for n in names)
+    return [
+        f"cellpose.model {name!r} is not available in the installed Cellpose "
+        f"(it offers {listed}). Cellpose would fall back to its default "
+        "model and log a warning rather than fail, so every tile would be "
+        "segmented with a model you did not choose. Pick one of the above, "
+        "give a path to a custom-trained model, or install the Cellpose "
+        'major version that has it (the workflow ships "cellpose3" and '
+        '"cellpose4" pixi environments).'
+    ]
 
 
 def _custom_problems(spec) -> list[str]:

{patchworks-2.6.11 → patchworks-2.6.12}/workflow/scripts/prepare_tiles.py

@@ -50,6 +50,17 @@ if ts == "auto":
     n_channels = 2 if cfg.get("nuclei_channel") is not None else 1
     if method == "cellpose":
         cp = cfg["cellpose"]
+        # The same anisotropy segment will derive (or was given). Cellpose
+        # resizes the tile to z * anisotropy planes, so the sizer has to
+        # budget for the resized tile, not the one it hands over.
+        anisotropy = cp.get("anisotropy")
+        if anisotropy is None and cp.get("do_3D", False):
+            from patchworks.plugins.cellpose import cellpose_anisotropy
+            from patchworks.plugins.ome_zarr import read_pixel_size
+
+            anisotropy = cellpose_anisotropy(
+                read_pixel_size(str(Path(work_dir) / "image.zarr"))
+            )
         sizer = partial(
             auto_tile_shape_cellpose,
             do_3D=cp.get("do_3D", False),
@@ -57,6 +68,7 @@ if ts == "auto":
             diameter=cp.get("diameter"),
             gpu_memory=gpu_bytes,
             n_channels=n_channels,
+            anisotropy=anisotropy,
         )
     else:
         # cfg["cellpose"] used to be read unconditionally here, so a DoG or