itasc 0.2.0.dev0__py3-none-any.whl

itasc/contact_analysis/dynamics/store.py

@@ -0,0 +1,251 @@
+"""Persist / read the track-dynamics artifact and orchestrate the build.
+
+One **HDF5** per substrate (``cell_dynamics.h5`` / ``nucleus_dynamics.h5``) — the
+quantity is several heterogeneous tables, so a single flat CSV (as the shape
+family uses) does not fit; this mirrors how contacts stores ``cells/`` /
+``edges/`` / ``t1_events/``. Groups::
+
+    instantaneous/table  per (frame, cell_id) positions + velocities (the
+                         object_table for the generic plotting layer)
+    tracks/table         per-track motility summary
+    msd/table            ensemble MSD curve (+ D_um2_per_s / alpha / r2 attrs)
+    dac/table            ensemble directional autocorrelation (+ persistence_time_s attr)
+    collective/table     per-frame order parameter / correlation length / NN distance
+    corr_curve/table     pooled velocity-correlation curve
+    provenance           run metadata as group attrs
+
+:func:`build_track_dynamics` runs the headless core and writes the file;
+:func:`read_track_dynamics` loads it back; :func:`read_instantaneous_table`
+serves the tidy-table contract. Backend-only (no Qt / napari).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+import h5py
+import numpy as np
+
+from .collective import collective_tables, pooled_corr_length
+from .kinematics import ensemble_dac, instantaneous_table, track_summary_table
+from .msd import MSD_TRACK_COLUMNS, ensemble_msd, fit_msd_power_law, per_track_msd_fit
+from .trajectories import extract_trajectories
+from itasc.contact_analysis._provenance import (
+    itasc_version as _itasc_version,
+)
+
+#: Build params and their defaults (a position with no override uses these).
+DEFAULT_PARAMS = {
+    "min_track_frames": 3,   # drop shorter tracks from the per-track summary
+    "min_msd_samples": 10,   # lags with fewer samples are excluded from the fit
+    "msd_track_window_frames": 8,  # fixed lag window for the per-track MSD fit
+    "corr_bin_um": None,     # None → global median nearest-neighbour distance
+    "min_corr_cells": 5,     # frames with fewer velocity-bearing cells → NaN
+}
+
+
+@dataclass(frozen=True)
+class TrackDynamics:
+    """In-memory view of a dynamics ``.h5`` — every table plus the fit scalars."""
+
+    instantaneous: dict[str, np.ndarray]
+    tracks: dict[str, np.ndarray]
+    msd: dict[str, np.ndarray]
+    dac: dict[str, np.ndarray]
+    collective: dict[str, np.ndarray]
+    corr_curve: dict[str, np.ndarray]
+    msd_D_um2_per_s: float
+    msd_alpha: float
+    msd_r2: float
+    dac_persistence_time_s: float
+    corr_length_um: float
+
+
+def build_track_dynamics(
+    label_path: str | Path,
+    output_path: str | Path,
+    *,
+    pixel_size_um: float,
+    time_interval_s: float,
+    source_path: str | Path | None = None,
+    params: dict | None = None,
+    quantity_id: str = "",
+    progress_cb: Callable[[int, int, str], None] | None = None,
+) -> Path:
+    """Compute every dynamics table from a tracked label TIFF and write the ``.h5``."""
+    pixel_size_um = float(pixel_size_um)
+    time_interval_s = float(time_interval_s)
+    if not pixel_size_um > 0:
+        raise ValueError(f"pixel_size_um must be positive, got {pixel_size_um!r}")
+    if not time_interval_s > 0:
+        raise ValueError(f"time_interval_s must be positive, got {time_interval_s!r}")
+    p = {**DEFAULT_PARAMS, **(params or {})}
+    label_path = Path(label_path)
+    output_path = Path(output_path)
+
+    def step(done: int, total: int, message: str) -> None:
+        if progress_cb is not None:
+            progress_cb(done, total, message)
+
+    trajectories = extract_trajectories(label_path, pixel_size_um=pixel_size_um)
+    step(1, 5, "trajectories")
+
+    instantaneous = instantaneous_table(trajectories, time_interval_s=time_interval_s)
+    tracks = track_summary_table(
+        trajectories,
+        time_interval_s=time_interval_s,
+        min_track_frames=int(p["min_track_frames"]),
+    )
+    track_msd = per_track_msd_fit(
+        trajectories,
+        time_interval_s=time_interval_s,
+        window_frames=int(p["msd_track_window_frames"]),
+    )
+    tracks = _merge_track_msd(tracks, track_msd)
+    step(2, 5, "kinematics")
+
+    msd = ensemble_msd(trajectories, time_interval_s=time_interval_s)
+    msd_fit = fit_msd_power_law(
+        msd["lag_s"], msd["msd_um2"],
+        min_samples_mask=msd["n_samples"] >= int(p["min_msd_samples"]),
+    )
+    step(3, 5, "msd")
+
+    dac, dac_persistence = ensemble_dac(trajectories, time_interval_s=time_interval_s)
+    step(4, 5, "persistence")
+
+    collective, corr_curve = collective_tables(
+        instantaneous,
+        corr_bin_um=p["corr_bin_um"],
+        min_cells=int(p["min_corr_cells"]),
+    )
+    corr_length = pooled_corr_length(corr_curve)
+    step(5, 5, "collective")
+
+    _write_h5(
+        output_path,
+        tables={
+            "instantaneous": instantaneous,
+            "tracks": tracks,
+            "msd": msd,
+            "dac": dac,
+            "collective": collective,
+            "corr_curve": corr_curve,
+        },
+        msd_fit=msd_fit,
+        dac_persistence_time_s=dac_persistence,
+        corr_length_um=corr_length,
+        provenance={
+            "quantity_id": quantity_id,
+            "source_position_path": str(source_path) if source_path else "",
+            "label_path": str(label_path),
+            "pixel_size_um": pixel_size_um,
+            "time_interval_s": time_interval_s,
+            "params": {k: ("" if v is None else v) for k, v in p.items()},
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "itasc_version": _itasc_version(),
+        },
+    )
+    return output_path
+
+
+def read_track_dynamics(path: str | Path) -> TrackDynamics:
+    """Load a dynamics ``.h5`` into a :class:`TrackDynamics`."""
+    path = Path(path)
+    with h5py.File(path, "r") as h5:
+        tables = {name: _read_table(h5[f"{name}/table"]) for name in (
+            "instantaneous", "tracks", "msd", "dac", "collective", "corr_curve"
+        )}
+        msd_attrs = h5["msd/table"].attrs
+        dac_attrs = h5["dac/table"].attrs
+        corr_attrs = h5["corr_curve/table"].attrs
+        return TrackDynamics(
+            instantaneous=tables["instantaneous"],
+            tracks=tables["tracks"],
+            msd=tables["msd"],
+            dac=tables["dac"],
+            collective=tables["collective"],
+            corr_curve=tables["corr_curve"],
+            msd_D_um2_per_s=float(msd_attrs["D_um2_per_s"]),
+            msd_alpha=float(msd_attrs["alpha"]),
+            msd_r2=float(msd_attrs["r2"]),
+            dac_persistence_time_s=float(dac_attrs["persistence_time_s"]),
+            # Absent in .h5 files built before per-tissue ξ → NaN (backward compat).
+            corr_length_um=float(corr_attrs.get("corr_length_um", float("nan"))),
+        )
+
+
+def read_instantaneous_table(path: str | Path) -> dict[str, np.ndarray]:
+    """The ``(frame, cell_id, …)`` instantaneous table — the tidy-table contract."""
+    path = Path(path)
+    with h5py.File(path, "r") as h5:
+        return _read_table(h5["instantaneous/table"])
+
+
+# --------------------------------------------------------------------- h5 I/O
+def _write_h5(
+    output_path, *, tables, msd_fit, dac_persistence_time_s, corr_length_um, provenance
+) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with h5py.File(output_path, "w") as h5:
+        for name, table in tables.items():
+            group = h5.create_group(f"{name}/table")
+            for column, values in table.items():
+                group.create_dataset(column, data=np.asarray(values))
+            # h5py iterates datasets alphabetically; persist the authored column
+            # order so _read_table can restore it rather than reshuffling.
+            group.attrs["column_order"] = list(table.keys())
+        msd_table = h5["msd/table"]
+        msd_table.attrs["D_um2_per_s"] = float(msd_fit.D_um2_per_s)
+        msd_table.attrs["alpha"] = float(msd_fit.alpha)
+        msd_table.attrs["r2"] = float(msd_fit.r2)
+        h5["dac/table"].attrs["persistence_time_s"] = float(dac_persistence_time_s)
+        # Symmetric with the msd fit attrs and the dac persistence attr.
+        h5["corr_curve/table"].attrs["corr_length_um"] = float(corr_length_um)
+        prov = h5.create_group("provenance")
+        _write_provenance_attrs(prov, provenance)
+
+
+def _merge_track_msd(
+    tracks: dict[str, np.ndarray], track_msd: dict[int, object]
+) -> dict[str, np.ndarray]:
+    """Add the per-track MSD-fit columns to the per-track table, aligned to
+    ``tracks["cell_id"]`` (NaN for any track absent from the fit map).
+
+    Lives here rather than in kinematics or msd: it bridges the two tables, and
+    neither of those modules should import the other.
+    """
+    cell_ids = tracks["cell_id"]
+    columns = {name: np.full(cell_ids.size, np.nan, dtype=float) for name in MSD_TRACK_COLUMNS}
+    for i, cid in enumerate(cell_ids.tolist()):
+        fit = track_msd.get(int(cid))
+        if fit is None:
+            continue
+        columns["msd_D_um2_per_s"][i] = fit.D_um2_per_s
+        columns["msd_alpha"][i] = fit.alpha
+        columns["msd_r2"][i] = fit.r2
+    return {**tracks, **columns}
+
+
+def _write_provenance_attrs(group: h5py.Group, provenance: dict) -> None:
+    for key, value in provenance.items():
+        if isinstance(value, dict):
+            for sub_key, sub_value in value.items():
+                group.attrs[f"{key}.{sub_key}"] = sub_value
+        else:
+            group.attrs[key] = value
+
+
+def _read_table(group: h5py.Group) -> dict[str, np.ndarray]:
+    """Read a table group, preserving the authored column order.
+
+    h5py iterates datasets alphabetically, so fall back to that only for legacy
+    files written without the ``column_order`` attribute.
+    """
+    order = group.attrs.get("column_order")
+    if order is not None:
+        names = [n.decode() if isinstance(n, bytes) else str(n) for n in order]
+        return {name: group[name][:] for name in names if name in group}
+    return {name: dataset[:] for name, dataset in group.items()}

itasc/contact_analysis/dynamics/trajectories.py

@@ -0,0 +1,100 @@
+"""Tracked label stack → per-track centroid trajectories (µm), gaps preserved.
+
+The shared front end of every dynamics calculation. Runs
+:func:`skimage.measure.regionprops` over each frame of a tracked label stack
+(``label == track_id``, constant across frames — the same per-frame loop the
+shape core uses) and groups centroids into one trajectory per track id. Frames
+where a track's label is absent are simply missing from its series, so a
+:class:`Trajectory` carries an explicit ``frames`` array and downstream code can
+detect gaps (``diff(frames) > 1``).
+
+Centroids are returned in **µm** (``(x, y)`` = ``(col, row) · pixel_size_um``);
+``x`` is the column axis and ``y`` the row axis, matching the shape core's
+``centroid_x_um`` / ``centroid_y_um``. Backend-only (no Qt / napari).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from skimage.measure import regionprops
+
+from ..shape.core import read_label_stack
+
+
+@dataclass(frozen=True)
+class Trajectory:
+    """One track's centroid path in µm, in frame order.
+
+    ``frames`` is strictly increasing (one entry per frame the track is present);
+    ``xy`` is the matching ``(N, 2)`` array of ``(x_um, y_um)`` centroids. A jump
+    of more than 1 between consecutive ``frames`` is a gap.
+    """
+
+    track_id: int
+    frames: np.ndarray  # (N,) int64, strictly increasing
+    xy: np.ndarray      # (N, 2) float, columns (x_um, y_um)
+
+    @property
+    def n_frames(self) -> int:
+        return int(self.frames.size)
+
+    @property
+    def n_gaps(self) -> int:
+        if self.frames.size < 2:
+            return 0
+        return int(np.count_nonzero(np.diff(self.frames) > 1))
+
+
+def extract_trajectories(
+    label_path: str | Path,
+    *,
+    pixel_size_um: float,
+    progress_cb: Callable[[int, int, str], None] | None = None,
+) -> list[Trajectory]:
+    """Read a tracked label TIFF and return one :class:`Trajectory` per track id.
+
+    Centroids come from ``regionprops(frame).centroid`` (row, col) scaled by
+    *pixel_size_um* into ``(x_um, y_um)``. Trajectories are sorted by track id;
+    each is internally sorted by frame.
+    """
+    pixel_size_um = float(pixel_size_um)
+    if not pixel_size_um > 0:
+        raise ValueError(f"pixel_size_um must be positive, got {pixel_size_um!r}")
+    label_stack = read_label_stack(Path(label_path))
+    return trajectories_from_stack(
+        label_stack, pixel_size_um=pixel_size_um, progress_cb=progress_cb
+    )
+
+
+def trajectories_from_stack(
+    label_stack: np.ndarray,
+    *,
+    pixel_size_um: float,
+    progress_cb: Callable[[int, int, str], None] | None = None,
+) -> list[Trajectory]:
+    """:func:`extract_trajectories` over an in-memory ``T×Y×X`` label stack."""
+    total = int(label_stack.shape[0])
+    # track_id -> (list[frame], list[(x_um, y_um)])
+    by_track: dict[int, tuple[list[int], list[tuple[float, float]]]] = {}
+    for frame_idx, frame in enumerate(label_stack):
+        for prop in regionprops(frame):
+            row, col = prop.centroid
+            frames, coords = by_track.setdefault(int(prop.label), ([], []))
+            frames.append(frame_idx)
+            coords.append((col * pixel_size_um, row * pixel_size_um))
+        if progress_cb is not None:
+            progress_cb(frame_idx + 1, total, "extract centroids")
+
+    trajectories: list[Trajectory] = []
+    for track_id in sorted(by_track):
+        frames, coords = by_track[track_id]
+        frame_arr = np.asarray(frames, dtype=np.int64)
+        xy = np.asarray(coords, dtype=float)
+        order = np.argsort(frame_arr, kind="stable")
+        trajectories.append(
+            Trajectory(track_id=track_id, frames=frame_arr[order], xy=xy[order])
+        )
+    return trajectories

itasc/contact_analysis/frame_interval.py

@@ -0,0 +1,85 @@
+"""Resolve a position's frame interval (seconds per frame).
+
+The time twin of :mod:`.pixel_size`. Track dynamics needs the real elapsed time
+between frames to turn pixel displacements into µm/s, MSD into µm²/s, and lags
+into seconds. Backend-only (no Qt / napari) so the standalone wheel and headless
+batch runs can use it. Two sources are consulted, in order:
+
+1. The position's ``itasc_config.json`` — ``metadata.time_interval_s`` — the
+   key the main pipeline widget already writes (``main_widget.py``).
+2. The label TIFF's ImageJ ``finterval`` tag (seconds between frames), the
+   convention ImageJ/Fiji writes for time-lapse stacks.
+
+Returns ``None`` when neither yields a positive value; callers treat that as
+"interval unknown" (the dynamics build is then blocked until one is set).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import tifffile
+
+from itasc.core.paths import position_config_path
+
+__all__ = [
+    "resolve_time_interval_s",
+    "time_interval_from_config",
+    "time_interval_from_tiff",
+]
+
+
+def resolve_time_interval_s(
+    position_dir: Path | str | None,
+    label_path: Path | str | None,
+) -> float | None:
+    """Seconds/frame for a position, from its config first, then the TIFF tag.
+
+    Returns ``None`` when no positive interval can be found.
+    """
+    interval = time_interval_from_config(position_dir)
+    if interval is not None:
+        return interval
+    return time_interval_from_tiff(label_path)
+
+
+def time_interval_from_config(position_dir: Path | str | None) -> float | None:
+    """``metadata.time_interval_s`` from ``itasc_config.json`` in *position_dir*."""
+    if position_dir is None:
+        return None
+    config_path = position_config_path(position_dir)
+    if not config_path.is_file():
+        return None
+    try:
+        with open(config_path) as f:
+            config = json.load(f)
+        metadata = config.get("metadata", {})
+        return _positive_float(metadata.get("time_interval_s"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+
+
+def time_interval_from_tiff(label_path: Path | str | None) -> float | None:
+    """Seconds/frame from a TIFF's ImageJ ``finterval`` metadata."""
+    if label_path is None:
+        return None
+    path = Path(label_path)
+    if not path.is_file():
+        return None
+    try:
+        with tifffile.TiffFile(str(path)) as tf:
+            metadata = tf.imagej_metadata or {}
+            return _positive_float(metadata.get("finterval"))
+    except (OSError, ValueError, KeyError, tifffile.TiffFileError):
+        # An unreadable/empty/corrupt TIFF means "frame interval unknown", not a
+        # crash. tifffile raises TiffFileError (not a KeyError/OSError subclass)
+        # for a malformed file, so it must be named explicitly.
+        return None
+
+
+def _positive_float(value: object) -> float | None:
+    try:
+        result = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+    return result if result > 0 else None

itasc/contact_analysis/napari.yaml

@@ -0,0 +1,10 @@
+name: itasc-aggregate
+display_name: ITASC Aggregate Quantification
+contributions:
+  commands:
+    - id: itasc-aggregate.widget
+      title: "ITASC Aggregate"
+      python_name: itasc.napari.main_widget:make_aggregate_app_widget
+  widgets:
+    - command: itasc-aggregate.widget
+      display_name: "ITASC Aggregate"