scikit-ops 0.1.0.dev0__py3-none-any.whl

skop/ops/threshold.py

@@ -0,0 +1,278 @@
+"""Global thresholding, via scikit-image.
+
+Every op here is the same shape: pick one number from the image's histogram,
+keep what lies above it. They differ only in how that number is chosen, and
+which choice is right is a property of the image rather than of the method --
+so they are variations on one call, sharing one module and one environment.
+
+A global threshold consumes no particular axis -- it is a histogram over
+whatever it is handed -- so none of these declare slots at all, and each works
+on a line, a plane or a whole volume. Whether one threshold for a stack or one
+per plane is the right answer depends on the experiment, so it is left to the
+caller: by default the stack arrives whole, and a caller wanting a threshold
+per plane iterates instead.
+
+Otsu is the default worth reaching for first. Beyond it:
+``li`` minimizes cross-entropy and copes well with a small foreground;
+``triangle`` and ``yen`` suit a skewed histogram with no clear valley;
+``isodata`` and ``mean`` are the cheap classical answers; ``minimum``
+insists on a genuinely bimodal histogram and raises when it cannot find one.
+``multiotsu`` is the odd one out -- it cuts into several classes rather than
+two, so it returns those classes rather than a foreground.
+
+Ported from src/imgops/implementations/skimagessegmenter.py.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import numpy as np
+
+from opspec.op import Axes, op
+from opspec.types import ImageOf, LabelsOf
+
+from ._util import to_gray
+
+#: What every op here takes: any number of axes, an RGB(A) axis collapsed.
+_Image = Annotated[ImageOf[np.ndarray], Axes(variadic=True)]
+
+
+def _mask(gray: np.ndarray, value: float, invert: bool, label_objects: bool):
+    """Turn one threshold into the mask, or labels, an op returns."""
+    from skimage import measure
+
+    mask = gray <= value if invert else gray > value
+    if label_objects:
+        return measure.label(mask).astype(np.uint16)
+    return mask.astype(np.uint16)
+
+
+@op(env="skimage")
+def otsu(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image by Otsu's method.
+
+    Chooses the threshold that minimizes the variance within the two classes
+    it creates, which is the same as maximizing the variance between them.
+    The standard first thing to try, and what it assumes -- two comparably
+    sized modes -- is also what it fails on.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_otsu(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def isodata(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image by the isodata (Ridler-Calvard) method.
+
+    Iterates until the threshold sits exactly halfway between the mean of
+    what falls below it and the mean of what falls above. Usually lands very
+    near Otsu, and is the method ImageJ's "Default" is descended from.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_isodata(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def li(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image by Li's minimum cross-entropy method.
+
+    Minimizes the information lost by replacing each class with its mean,
+    which does not require the two classes to be of similar size. The one to
+    try when Otsu swallows a sparse foreground.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_li(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def mean(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image at its mean intensity.
+
+    The simplest global threshold there is, and a reasonable baseline on an
+    image whose background is genuinely uniform.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_mean(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def minimum(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image at the valley between its two histogram peaks.
+
+    Smooths the histogram until exactly two maxima remain, then cuts at the
+    minimum between them. The most literal reading of "bimodal", and the
+    least forgiving: an image whose histogram will not smooth down to two
+    peaks raises rather than guessing.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_minimum(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def triangle(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image by the triangle method.
+
+    Draws a line from the histogram's peak to its far end and cuts where the
+    histogram is furthest from that line. Geometric rather than statistical,
+    which is why it holds up on the heavily skewed histogram of a mostly
+    empty fluorescence image.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_triangle(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def yen(
+    image: _Image,
+    invert: bool = False,
+    label_objects: bool = True,
+) -> LabelsOf[np.ndarray]:
+    """Threshold an image by Yen's maximum correlation criterion.
+
+    An entropy method like Li's, but maximizing a correlation between the two
+    classes rather than minimizing a divergence. Tends to cut higher than
+    Otsu, keeping less.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        invert: Whether to keep what falls below the threshold instead.
+        label_objects: Whether to label connected components, rather than
+            returning a plain binary mask.
+
+    Returns:
+        A label image, or a 0/1 mask when ``label_objects`` is off.
+    """
+    from skimage import filters
+
+    gray = to_gray(image)
+    return _mask(gray, filters.threshold_yen(gray), invert, label_objects)
+
+
+@op(env="skimage")
+def multiotsu(
+    image: _Image,
+    classes: int = 3,
+    label_objects: bool = False,
+) -> LabelsOf[np.ndarray]:
+    """Split an image into several intensity classes, by Otsu's criterion.
+
+    Otsu generalized: instead of one threshold there are ``classes - 1`` of
+    them, chosen together to minimize the variance within the classes they
+    make. Where the other ops here answer "foreground or not", this one
+    answers "which layer" -- background, dim, bright -- so it returns those
+    classes as a label image, numbered 0 upward by intensity.
+
+    Args:
+        image: Image to threshold. A trailing RGB(A) axis is collapsed.
+        classes: How many intensity classes to split into, at least 2.
+        label_objects: Whether to label the connected components of the
+            brightest class instead, discarding the rest. That makes this a
+            drop-in for the two-class ops, cutting nearer the bright end.
+
+    Returns:
+        A label image: one label per intensity class, or per object in the
+        brightest class when ``label_objects`` is on.
+    """
+    from skimage import filters, measure
+
+    if classes < 2:
+        raise ValueError(f"classes must be at least 2, got {classes}")
+
+    gray = to_gray(image)
+    thresholds = filters.threshold_multiotsu(gray, classes=classes)
+    if label_objects:
+        return measure.label(gray > thresholds[-1]).astype(np.uint16)
+    # Note: right=True so a pixel *at* a threshold falls below it, matching
+    # the strict `gray > value` the two-class ops here use.
+    return np.digitize(gray, bins=thresholds, right=True).astype(np.uint16)

skop/ops/toy.py

@@ -0,0 +1,114 @@
+"""Toy ops, used to exercise skop without dragging in a deep learning stack.
+
+Note the shape of an op module: imports at the top are limited to what the
+signatures need, so this module loads in a minimal environment. Anything an
+op needs only in order to *run* is imported inside the function body.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Annotated, NamedTuple
+
+import numpy as np
+
+from opspec.op import Axes, Out, op
+from opspec.runtime import cancel_requested, progress
+from opspec.types import ImageOf, LabelsOf, PointsOf
+
+
+@op(env="minimal")
+def add(a: int, b: int) -> int:
+    """Add two numbers. The smallest op there is."""
+    return a + b
+
+
+class ScaleResult(NamedTuple):
+    scaled: np.ndarray
+    total: float
+
+
+@op(env="minimal")
+def scale(
+    image: np.ndarray,
+    factor: Annotated[
+        float,
+        {"widget_type": "FloatSlider", "min": 0.0, "max": 10.0, "step": 0.1},
+    ] = 2.0,
+) -> ScaleResult:
+    """Scale an array, returning the result alongside its sum.
+
+    Exercises multi-output ops: the NamedTuple field names become the names
+    of the task's outputs.
+    """
+    scaled = image * factor
+    return ScaleResult(scaled=scaled, total=float(scaled.sum()))
+
+
+@op(env="minimal")
+def scale_into(
+    image: ImageOf[np.ndarray],
+    result: Out[ImageOf[np.ndarray]],
+    factor: float = 2.0,
+) -> None:
+    """Computer form: fill a buffer the caller allocated.
+
+    The caller owns ``result``, so nothing is sent back over the wire. Note
+    that ``Out`` and a role compose: nested Annotated flattens, so ``result``
+    is both an output buffer and an image.
+    """
+    np.multiply(image, factor, out=result, casting="unsafe")
+
+
+@op(env="minimal")
+def quadrants(
+    image: Annotated[ImageOf[np.ndarray], Axes("y", "x")],
+) -> LabelsOf[np.ndarray]:
+    """Label a plane's four quadrants, 1 through 4.
+
+    A strictly 2-D op, and the standing test case for adapting one: fed a
+    stack, every plane numbers its own objects from 1, so a correct
+    reassembly has to renumber them.
+    """
+    height, width = image.shape
+    labels = np.ones(image.shape, dtype=np.uint16)
+    labels[: height // 2, width // 2 :] = 2
+    labels[height // 2 :, : width // 2] = 3
+    labels[height // 2 :, width // 2 :] = 4
+    return labels
+
+
+@op(env="minimal")
+def slow_sum(image: np.ndarray, steps: int = 5) -> float:
+    """Sum an array slowly, reporting progress and honoring cancellation."""
+    total = 0.0
+    chunks = np.array_split(image.ravel(), steps)
+    for i, chunk in enumerate(chunks):
+        if cancel_requested():
+            break
+        progress(f"Summing chunk {i + 1} of {steps}", i, steps)
+        total += float(chunk.sum())
+        time.sleep(0.05)
+    return total
+
+
+@op(env="minimal")
+def probe() -> str:
+    """Report which interpreter is actually executing this op."""
+    import sys
+
+    return f"{sys.executable} | py={sys.version.split()[0]} | numpy={np.__version__}"
+
+
+class Findings(NamedTuple):
+    labels: LabelsOf[np.ndarray]
+    points: PointsOf[np.ndarray]
+
+
+@op(env="minimal")
+def find_nothing(image: ImageOf[np.ndarray]) -> Findings:
+    """Return an empty result, as a segmentation that finds nothing would."""
+    return Findings(
+        labels=np.zeros_like(image, dtype=np.uint16),
+        points=np.zeros((0, 3), dtype=np.int32),
+    )

skop/ops/train/__init__.py

@@ -0,0 +1,81 @@
+"""Training ops: input/truth pairs in, a model on disk out.
+
+Also what you want to know *before* training -- the receptive field of the
+architecture you are about to build. It sits here rather than in a category of
+its own because it takes the same architecture parameters the training op
+does, and a change to one is a change to both.
+
+Training ops differ from the rest of skop in two ways, both settled in
+design 0011. They take **paths, not arrays** -- a manifest of image files and
+the label files that pair with them, one list each, matched by position. And
+they **return a path**: a trained TensorFlow or torch model cannot cross the
+worker boundary, so the op writes it and hands back where.
+
+The caller resolves its own directory layout into those two lists. Nothing in
+here knows what a patch directory looks like, and nothing in here should.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .cellpose4 import train_cellpose4
+from .cellpose3 import train_cellpose3
+from .stardist2d import receptive_field_stardist2d, train_stardist2d
+
+__all__ = [
+    "train_cellpose4",
+    "train_cellpose3",
+    "train_stardist2d",
+    "receptive_field_stardist2d",
+    "extent",
+    "theoretical_receptive_field",
+]
+
+
+def extent(response) -> tuple[int, int]:
+    """The height and width, in pixels, that an impulse response covers.
+
+    Takes what a ``receptive_field_*`` op returns. Pure numpy, so it runs
+    wherever the caller is rather than in the op's environment.
+    """
+    reached = np.asarray(response) > 0
+    if not reached.any():
+        return (0, 0)
+    rows, cols = np.where(reached)
+    return (int(rows.max() - rows.min() + 1), int(cols.max() - cols.min() + 1))
+
+
+def theoretical_receptive_field(
+    unet_n_depth: int = 3,
+    grid_size_xy: int = 1,
+    unet_kernel_size: int = 3,
+    unet_pool: int = 2,
+    unet_n_conv_per_depth: int = 2,
+) -> int:
+    """What the architecture predicts, for comparison with the measurement.
+
+    Counted the usual way -- each convolution adds ``kernel - 1`` times the
+    current stride, each pooling multiplies the stride -- down through the
+    encoder, across the bottleneck and back up. ``grid`` multiplies the result
+    because StarDist pools the input to grid size before the U-Net, so the
+    whole network sees a coarser image.
+
+    An estimate, and the measurement is the authority: it counts the final
+    convolutions after the U-Net, which this does not, so it reads low.
+    Compare the two, and when they disagree believe the impulse.
+    """
+    k, pool = unet_kernel_size, unet_pool
+    r, stride = 1, 1
+    for _ in range(unet_n_depth):
+        for _ in range(unet_n_conv_per_depth):
+            r += (k - 1) * stride
+        r += (pool - 1) * stride
+        stride *= pool
+    for _ in range(unet_n_conv_per_depth):
+        r += (k - 1) * stride
+    for _ in range(unet_n_depth):
+        stride //= pool
+        for _ in range(unet_n_conv_per_depth):
+            r += (k - 1) * stride
+    return r * grid_size_xy

skop/ops/train/_util.py

@@ -0,0 +1,152 @@
+"""Shared by the two Cellpose trainers.
+
+Both wrap the same ``cellpose.train.train_seg`` in different versions of the
+package. Pure python, so either environment can import it.
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+import os
+import re
+
+from opspec.runtime import progress
+
+#: The line train_seg logs at the end of an epoch, in both versions:
+#: ``12, train_loss=0.4213, test_loss=0.5012, LR=0.000010, time 3.21s``
+_EPOCH_LINE = re.compile(r"^(\d+), train_loss=(\S+), test_loss=(\S+),")
+
+
+class relay_epochs:
+    """Turn Cellpose's epoch log line into ``progress()`` calls.
+
+    ``train_seg`` takes no callback, so its log is the only live signal. A
+    handler rather than a stream capture: Appose's protocol is on stdout.
+    Removed on exit, or the next run reports this one's epochs too.
+    """
+
+    def __init__(self, epochs: int):
+        self.epochs = epochs
+        self.history: list[tuple[int, float, float]] = []
+
+    def __enter__(self):
+        relay = self
+
+        class Handler(logging.Handler):
+            def emit(self, record):
+                match = _EPOCH_LINE.match(record.getMessage())
+                if match is None:
+                    return
+                epoch = int(match.group(1)) + 1
+                loss, val_loss = float(match.group(2)), float(match.group(3))
+                relay.history.append((epoch, loss, val_loss))
+                progress(
+                    f"Epoch {epoch}/{relay.epochs} — "
+                    f"loss {loss:.4f}, val_loss {val_loss:.4f}",
+                    epoch,
+                    relay.epochs,
+                )
+
+        self._handler = Handler()
+        self._log = logging.getLogger("cellpose.train")
+        self._level = self._log.level
+        self._propagate = self._log.propagate
+        # INFO, or the record is dropped before any handler sees it. No
+        # propagation, or it reaches a stdout handler and breaks the protocol.
+        self._log.setLevel(logging.INFO)
+        self._log.propagate = False
+        self._log.addHandler(self._handler)
+        return self
+
+    def __exit__(self, *exc):
+        self._log.removeHandler(self._handler)
+        self._log.setLevel(self._level)
+        self._log.propagate = self._propagate
+
+
+def continued_from(model_path, initial_model: str) -> bool:
+    """Whether this run carried on the model it is about to write.
+
+    True only when ``initial_model`` is the same file as ``model_path``.
+    Starting from a built-in, or from some *other* model of your own, is a new
+    lineage however familiar the name -- the weights do not continue, so
+    neither does the curve.
+    """
+    if not initial_model:
+        return False
+    try:
+        return os.path.samefile(initial_model, model_path)
+    except OSError:
+        # One of them does not exist yet -- the first run writing this name.
+        return os.path.abspath(initial_model) == os.path.abspath(model_path)
+
+
+def write_history(
+    model_path, history, name: str, dataset_id: str, initial_model: str = ""
+) -> str:
+    """Write this run's epochs to ``<model file>_history.csv``. Columns match
+    ``train_stardist2d``. Rewritten rather than appended: an older file has a
+    shorter header, and wider rows read back wrong.
+
+    Kept epochs continue the old ones only when this run continued the old
+    *weights* -- see ``continued_from``. Otherwise the previous history is
+    dropped, because Cellpose has just overwritten the model it described:
+    keeping a curve for weights that no longer exist draws one training run
+    as though it were the tail of another.
+    """
+    columns = ["epoch", "loss", "val_loss", "run", "model", "dataset"]
+    path = f"{model_path}_history.csv"
+
+    previous = []
+    if continued_from(model_path, initial_model) and os.path.exists(path):
+        with open(path) as f:
+            previous = list(csv.DictReader(f))
+    last_run = int(previous[-1].get("run") or 0) if previous else 0
+    # Where the last run got to, not how many rows it wrote: Cellpose logs
+    # every tenth epoch, so rows and epochs are not the same count.
+    done = int(previous[-1].get("epoch") or 0) if previous else 0
+
+    with open(path, "w", newline="") as f:
+        writer = csv.DictWriter(f, columns, restval="")
+        writer.writeheader()
+        for row in previous:
+            writer.writerow({k: row.get(k, "") for k in columns})
+        for epoch, loss, val_loss in history:
+            writer.writerow(
+                {
+                    "epoch": done + epoch,
+                    "loss": loss,
+                    "val_loss": val_loss,
+                    "run": last_run + 1,
+                    "model": name,
+                    "dataset": dataset_id,
+                }
+            )
+    return path
+
+
+def read_pairs(images: list[str], labels: list[str], val_size: int):
+    """Read the patches, validation split off the end. Not random -- a caller
+    wanting that shuffles its own lists and records the seed."""
+    from tifffile import imread
+
+    if len(images) != len(labels):
+        raise ValueError(
+            f"{len(images)} images and {len(labels)} labels: a training set "
+            f"is pairs, so the two lists must be the same length."
+        )
+    if len(images) <= val_size:
+        raise ValueError(
+            f"{len(images)} pairs is not enough to hold {val_size} back for "
+            f"validation and still train on the rest."
+        )
+
+    progress(f"Reading {len(images)} pairs", 0, len(images))
+    X, Y = [], []
+    for i, (image_path, label_path) in enumerate(zip(images, labels)):
+        X.append(imread(image_path))
+        Y.append(imread(label_path))
+        progress(current=i + 1)
+
+    return X[:-val_size], Y[:-val_size], X[-val_size:], Y[-val_size:]