itasc 0.2.0.dev0__py3-none-any.whl

itasc/core/commit.py

@@ -0,0 +1,61 @@
+"""The final-output commit contract.
+
+The numbered stage dirs (``2_nucleus/``, ``3_cell/``) hold re-runnable *working*
+label files; :func:`promote_labels` copies one up to a stable *committed* name in
+the position base folder (``nucleus_labels.tif`` / ``cell_labels.tif``), the
+downstream-stable output that discovery defaults to. :func:`commit_state` reports
+where a position sits in that working-vs-committed split — the signal the
+workflow widgets surface and the catalog status rail reads.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import numpy as np
+import tifffile
+
+CommitState = str  # one of: "missing" | "uncommitted" | "committed" | "stale"
+
+
+def promote_labels(src: Path | str, dst: Path | str) -> Path:
+    """Promote a working label file *src* to the committed output *dst*.
+
+    Copies bytes verbatim (the working file is already a dtype-correct label
+    image), creating ``dst``'s parent and overwriting any existing ``dst``.
+    Raises ``FileNotFoundError`` if *src* is missing and ``ValueError`` if it is
+    not an integer-typed label image.
+    """
+    src = Path(src)
+    dst = Path(dst)
+    if not src.is_file():
+        raise FileNotFoundError(f"No working label file to commit: {src}")
+    with tifffile.TiffFile(str(src)) as tf:
+        dtype = tf.series[0].dtype
+    if not np.issubdtype(dtype, np.integer):
+        raise ValueError(
+            f"Not a label image (dtype {dtype}); refusing to commit {src}"
+        )
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dst)
+    return dst
+
+
+def commit_state(working: Path | str, committed: Path | str) -> CommitState:
+    """Return the working-vs-committed state for one stage output.
+
+    * ``"missing"`` — no working file yet.
+    * ``"uncommitted"`` — working file exists but has not been committed.
+    * ``"committed"`` — committed copy is at least as new as the working file.
+    * ``"stale"`` — the working file was re-run after the last commit (strictly
+      newer), so the committed copy no longer reflects it.
+    """
+    working = Path(working)
+    committed = Path(committed)
+    if not working.is_file():
+        return "missing"
+    if not committed.is_file():
+        return "uncommitted"
+    if working.stat().st_mtime > committed.stat().st_mtime:
+        return "stale"
+    return "committed"

itasc/core/imageops.py

@@ -0,0 +1,34 @@
+# src/itasc/core/imageops.py
+"""Generic, deterministic image operations shared across ITASC pieces.
+
+Pure functions with no ITASC dependencies, usable by segmentation, tracking,
+and any other consumer without pulling in a heavier subpackage.
+"""
+from __future__ import annotations
+
+import numpy as np
+from skimage.filters import threshold_local
+
+
+def residual(frame: np.ndarray, window: int, strength: float = 1.0) -> np.ndarray:
+    """Local-mean-subtracted residual: ``clip(frame - strength*localmean(frame), 0)``.
+
+    Flattens each map's per-nucleus offset so a single global threshold works
+    everywhere while staying ~0 in flat background. ``window`` is forced odd.
+
+    ``strength`` blends between the raw map and the fully-flattened residual:
+    ``1.0`` subtracts the whole local background (default), ``0.0`` subtracts
+    nothing so the result is the raw (non-negative) map, and values in between
+    partially flatten. Lowering it trades uniform-threshold behaviour for
+    keeping more of the original signal where the background is already flat.
+    """
+    window = int(window) | 1
+    frame = np.asarray(frame, dtype=np.float32)
+    if strength == 0.0:
+        # No background subtraction requested (the default): the result is just
+        # the non-negative raw map, so skip the O(Y·X) gaussian entirely. This
+        # matters because ``CellDivergenceParams.fg_strength`` defaults to 0.0,
+        # so every default-config frame — including live previews — hit this.
+        return np.clip(frame, 0.0, None)
+    local_mean = threshold_local(frame, block_size=window, method="gaussian")
+    return np.clip(frame - strength * local_mean, 0.0, None).astype(np.float32)

itasc/core/label_store.py

@@ -0,0 +1,53 @@
+"""TIFF storage for tracked nucleus label volumes.
+
+Schema: single multipage TIFF — shape (T, Y, X), dtype uint32.
+Frames that have not yet been tracked are stored as all-zeros.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import tifffile
+
+from itasc.core.tiff import imwrite_grayscale
+
+_LABEL_DTYPE = np.uint32
+
+
+def _load_stack(path: Path) -> np.ndarray:
+    """Load the TIFF as (T, Y, X). Returns empty array if file does not exist.
+
+    Tolerates legacy files written with a singleton Z axis: ``(T, 1, Y, X)``
+    is squeezed to ``(T, Y, X)`` so the in-memory shape always matches the
+    documented schema.
+    """
+    if not path.exists():
+        return np.empty((0, 0, 0), dtype=_LABEL_DTYPE)
+    stack = np.asarray(tifffile.imread(str(path)), dtype=_LABEL_DTYPE)
+    if stack.ndim == 2:
+        stack = stack[np.newaxis]
+    elif stack.ndim == 4 and stack.shape[1] == 1:
+        stack = stack[:, 0]
+    return stack
+
+
+def write_full_tracked_stack(path: str | Path, stack: np.ndarray) -> None:
+    """Write the entire ``(T, Y, X)`` tracked stack in one encode.
+
+    A multipage zlib TIFF cannot be updated in place, so a per-frame writer
+    would decode and re-encode the whole file on every frame (O(T²) over a
+    full-stack save). This encodes once (O(T)). A legacy singleton-Z axis
+    ``(T, 1, Y, X)`` is squeezed to match the documented schema.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    stack = np.asarray(stack, dtype=_LABEL_DTYPE)
+    if stack.ndim == 4 and stack.shape[1] == 1:
+        stack = stack[:, 0]
+    imwrite_grayscale(path, stack, compression="zlib")
+
+
+def read_full_tracked_stack(path: str | Path) -> np.ndarray:
+    """Read all tracked frames as a (T, Y, X) uint32 array."""
+    return _load_stack(Path(path))

itasc/core/lineage.py

@@ -0,0 +1,113 @@
+"""Per-track temporal presence ("swimlane") model from a tracked label stack.
+
+This is the data half of the correction *lineage graph*: for each track id it
+records the frame ranges where the cell is present, collapsed into contiguous
+segments so a gap (track vanishes then returns — a likely ID swap or missed
+link) reads as a break between segments. It is deliberately array-only — true
+parent/daughter division edges live in the Ultrack database and are a separate,
+heavier concern layered on top later.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True, slots=True)
+class TrackSegment:
+    """A contiguous run of frames ``[start, end]`` (inclusive) for one track."""
+
+    start: int
+    end: int
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start + 1
+
+
+@dataclass(frozen=True, slots=True)
+class TrackLane:
+    """One track id and the frame segments where it is present."""
+
+    cell_id: int
+    segments: tuple[TrackSegment, ...]
+
+    @property
+    def first_frame(self) -> int:
+        return self.segments[0].start
+
+    @property
+    def last_frame(self) -> int:
+        return self.segments[-1].end
+
+    @property
+    def n_frames(self) -> int:
+        return sum(seg.length for seg in self.segments)
+
+    @property
+    def has_gap(self) -> bool:
+        return len(self.segments) > 1
+
+
+@dataclass(frozen=True, slots=True)
+class LineageModel:
+    """All track lanes plus the total frame count, for the lineage panel."""
+
+    n_frames: int
+    lanes: tuple[TrackLane, ...]
+
+    def lane_for(self, cell_id: int) -> TrackLane | None:
+        for lane in self.lanes:
+            if lane.cell_id == cell_id:
+                return lane
+        return None
+
+
+def _segments_from_frames(frames: list[int]) -> tuple[TrackSegment, ...]:
+    """Collapse a sorted frame list into contiguous inclusive segments."""
+    segments: list[TrackSegment] = []
+    start = prev = frames[0]
+    for t in frames[1:]:
+        if t == prev + 1:
+            prev = t
+            continue
+        segments.append(TrackSegment(start=start, end=prev))
+        start = prev = t
+    segments.append(TrackSegment(start=start, end=prev))
+    return tuple(segments)
+
+
+def build_lineage(tracked: np.ndarray) -> LineageModel:
+    """Build a :class:`LineageModel` from a ``(T, Y, X)`` tracked label stack.
+
+    A singleton Z axis (``(T, 1, Y, X)``) is squeezed; a single 2D frame is
+    treated as one timepoint. Lanes are sorted by track id so a cell keeps its
+    row across refreshes; correction actions (retrack, extend, relabel, …) that
+    change a track's id move it to its new sorted position on the next refresh.
+    """
+    arr = np.asarray(tracked)
+    if arr.ndim == 4 and arr.shape[1] == 1:
+        arr = arr[:, 0]
+    if arr.ndim == 2:
+        arr = arr[np.newaxis]
+    if arr.ndim != 3:
+        raise ValueError(f"tracked must be (T, Y, X); got shape {arr.shape}")
+
+    n_t = arr.shape[0]
+    frames_of: dict[int, list[int]] = {}
+    for t in range(n_t):
+        for cell_id in np.unique(arr[t]).tolist():
+            if cell_id == 0:
+                continue
+            frames_of.setdefault(int(cell_id), []).append(t)
+
+    lanes = [
+        TrackLane(cell_id=cell_id, segments=_segments_from_frames(frames))
+        for cell_id, frames in frames_of.items()
+    ]
+    lanes.sort(key=lambda lane: lane.cell_id)
+    return LineageModel(n_frames=n_t, lanes=tuple(lanes))
+
+
+__all__ = ["LineageModel", "TrackLane", "TrackSegment", "build_lineage"]

itasc/core/logging.py

@@ -0,0 +1,51 @@
+"""StageLogger — JSON-lines logger writing to per-position pipeline.log."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class StageLogger:
+    """Context manager that appends JSON-lines entries to pipeline.log."""
+
+    def __init__(
+        self,
+        pipeline_log: Path,
+        stage_name: str,
+    ) -> None:
+        self._pipeline_log = pipeline_log
+        self._stage_name = stage_name
+
+    def _write(self, level: str, message: str) -> None:
+        entry = json.dumps(
+            {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "stage": self._stage_name,
+                "level": level,
+                "message": message,
+            }
+        )
+        self._pipeline_log.parent.mkdir(parents=True, exist_ok=True)
+        with self._pipeline_log.open("a", encoding="utf-8") as fh:
+            fh.write(entry + "\n")
+
+    def info(self, message: str) -> None:
+        self._write("INFO", message)
+
+    def warning(self, message: str) -> None:
+        self._write("WARNING", message)
+
+    def error(self, message: str) -> None:
+        self._write("ERROR", message)
+
+    def __enter__(self) -> StageLogger:
+        self.info("Stage started")
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if exc_type is None:
+            self.info("Stage completed successfully")
+        else:
+            self.error(f"Stage failed: {exc_val}")
+        return False

itasc/core/paths.py

@@ -0,0 +1,34 @@
+"""Unified path resolution for the ITASC pipeline directory layout."""
+from __future__ import annotations
+
+from pathlib import Path
+
+#: Filename ITASC writes a position's metadata/config into.
+CONFIG_NAME = "itasc_config.json"
+
+#: Pre-rename filename, written by the old CellFlow app. Read-only fallback.
+_LEGACY_CONFIG_NAME = "cellflow_config.json"
+
+
+def pos_dir(root: Path | str, pos: int) -> Path:
+    """Return <root>/pos<pos:02d>."""
+    return Path(root) / f"pos{pos:02d}"
+
+
+def position_config_path(position_dir: Path | str) -> Path:
+    """Path to a position's ITASC config file.
+
+    Prefers the current ``itasc_config.json``. When it is absent but a legacy
+    ``cellflow_config.json`` (written before the rename) is present, returns the
+    legacy path so old data keeps loading. When neither exists, returns the
+    current name, so new writes always use it.
+    """
+    base = Path(position_dir)
+    current = base / CONFIG_NAME
+    if current.exists():
+        return current
+    legacy = base / _LEGACY_CONFIG_NAME
+    if legacy.exists():
+        return legacy
+    return current
+

itasc/core/tiff.py

@@ -0,0 +1,13 @@
+"""TIFF writing helpers for ITASC grayscale stacks."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import tifffile
+
+
+def imwrite_grayscale(path: str | Path, data: Any, **kwargs: Any) -> None:
+    """Write a grayscale TIFF stack without tifffile RGB-shape ambiguity."""
+    kwargs.setdefault("photometric", "minisblack")
+    tifffile.imwrite(str(path), data, **kwargs)

itasc/correction/__init__.py

@@ -0,0 +1,25 @@
+from itasc.correction.labels import (
+    clean_stranded_pixels,
+    draw_cell_path,
+    erase_cell,
+    expand_label_to_foreground,
+    fill_label_holes,
+    fix_label_semiholes,
+    merge_cells,
+    split_across,
+    split_draw,
+    swap_labels,
+)
+
+__all__ = [
+    "clean_stranded_pixels",
+    "draw_cell_path",
+    "erase_cell",
+    "expand_label_to_foreground",
+    "fill_label_holes",
+    "fix_label_semiholes",
+    "merge_cells",
+    "split_across",
+    "split_draw",
+    "swap_labels",
+]