itasc 0.2.0.dev0__py3-none-any.whl

itasc/contact_analysis/dynamics/__init__.py

@@ -0,0 +1,43 @@
+"""Track-dynamics compute core: motion read off tracked label stacks.
+
+The headless backend for the dynamics quantifiers. A tracked label stack becomes
+per-track centroid trajectories (:mod:`.trajectories`), then instantaneous
+velocities + per-track motility summaries (:mod:`.kinematics`), an ensemble
+mean-square-displacement curve with a power-law fit (:mod:`.msd`), and
+tissue-scale collective metrics — alignment, velocity correlation, length scale
+(:mod:`.collective`). :func:`build_track_dynamics` runs all of it and persists a
+multi-table ``.h5``; :func:`read_track_dynamics` loads it back. No Qt / napari
+import, so scripts and the standalone wheel can use it.
+"""
+
+from .collective import COLLECTIVE_COLUMNS, CORR_CURVE_COLUMNS, pooled_corr_length
+from .kinematics import DAC_COLUMNS, INSTANTANEOUS_COLUMNS, TRACK_COLUMNS
+from .msd import MSD_COLUMNS, MSD_TRACK_COLUMNS, per_track_msd_fit
+from .store import (
+    DEFAULT_PARAMS,
+    TrackDynamics,
+    build_track_dynamics,
+    read_instantaneous_table,
+    read_track_dynamics,
+)
+from .trajectories import Trajectory, extract_trajectories, trajectories_from_stack
+
+__all__ = [
+    "COLLECTIVE_COLUMNS",
+    "CORR_CURVE_COLUMNS",
+    "DAC_COLUMNS",
+    "DEFAULT_PARAMS",
+    "INSTANTANEOUS_COLUMNS",
+    "MSD_COLUMNS",
+    "MSD_TRACK_COLUMNS",
+    "TRACK_COLUMNS",
+    "TrackDynamics",
+    "Trajectory",
+    "build_track_dynamics",
+    "extract_trajectories",
+    "per_track_msd_fit",
+    "pooled_corr_length",
+    "read_instantaneous_table",
+    "read_track_dynamics",
+    "trajectories_from_stack",
+]

itasc/contact_analysis/dynamics/collective.py

@@ -0,0 +1,206 @@
+"""Tissue-scale collective motion: alignment, velocity correlation, length scale.
+
+Consumes the per-frame instantaneous table (positions + velocities, the single
+source of truth) and, for each frame, measures how coherently neighbours move:
+
+* **order parameter** ``φ = |⟨v_i/|v_i|⟩|`` ∈ [0,1] — 0 random, 1 fully aligned
+  (uses raw velocities).
+* **velocity correlation** of fluctuations ``δv_i = v_i − ⟨v⟩`` (the per-frame
+  drift removed): ``C(r) = ⟨δv_i·δv_j⟩_{|r_i−r_j|≈r} / ⟨δv_i·δv_i⟩``, normalised
+  so ``C → 1`` as ``r → 0``.
+* **correlation length** ``ξ`` = the separation where ``C(r)`` decays to ``1/e``
+  (linear interpolation between bin centres); NaN when it never does.
+* **nearest-neighbour distance** (median, per frame) — a natural length scale and
+  the default correlation bin width.
+
+Pairs are binned by separation with width *corr_bin_um* (defaults to the global
+median NN distance). The per-frame ``C(r)`` curves are also pooled across frames
+into a single dataset-level curve. Pure NumPy; no I/O.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+#: Per-frame collective columns.
+COLLECTIVE_COLUMNS = ("frame", "n_cells", "order_param", "corr_length_um", "nn_distance_um")
+#: Pooled correlation-curve columns.
+CORR_CURVE_COLUMNS = ("separation_um", "corr", "n_pairs")
+
+_INV_E = float(np.exp(-1.0))
+
+
+def collective_tables(
+    instantaneous: dict[str, np.ndarray],
+    *,
+    corr_bin_um: float | None = None,
+    min_cells: int = 5,
+) -> tuple[dict[str, np.ndarray], dict[str, np.ndarray]]:
+    """Return ``(collective_table, corr_curve_table)`` from the instantaneous table.
+
+    *min_cells* is the minimum velocity-bearing cells a frame needs for its
+    correlation/alignment metrics (fewer → NaN, but the frame's NN distance is
+    still recorded). *corr_bin_um* defaults to the global median NN distance.
+    """
+    frames_all = instantaneous["frame"]
+    x = instantaneous["x_um"]
+    y = instantaneous["y_um"]
+    vx = instantaneous["vx_um_per_s"]
+    vy = instantaneous["vy_um_per_s"]
+
+    per_frame = _per_frame_views(frames_all, x, y, vx, vy)
+    bin_width = _resolve_bin_width(corr_bin_um, per_frame)
+
+    frames: list[int] = []
+    n_cells: list[int] = []
+    order: list[float] = []
+    corr_len: list[float] = []
+    nn_dist: list[float] = []
+
+    # Pooled-curve accumulators, keyed by integer bin index.
+    pooled_dot: dict[int, float] = {}
+    pooled_count: dict[int, int] = {}
+    pooled_var_sum = 0.0
+    pooled_var_count = 0
+
+    for frame, (pos_all, pos_v, vel) in per_frame.items():
+        frames.append(frame)
+        n_cells.append(pos_v.shape[0])
+        nn_dist.append(_median_nn_distance(pos_all))
+        if pos_v.shape[0] < int(min_cells):
+            order.append(np.nan)
+            corr_len.append(np.nan)
+            continue
+        order.append(_order_parameter(vel))
+        dV = vel - vel.mean(axis=0)
+        var = float(np.mean(np.einsum("ij,ij->i", dV, dV)))
+        centers, C, counts, dot_by_bin = _velocity_correlation(pos_v, dV, bin_width, var)
+        corr_len.append(_one_over_e_length(centers, C))
+        # Pool raw dot sums + the variance normaliser (a single global C(0)).
+        for b, d_sum in dot_by_bin.items():
+            pooled_dot[b] = pooled_dot.get(b, 0.0) + d_sum
+            pooled_count[b] = pooled_count.get(b, 0) + counts[b]
+        pooled_var_sum += var * pos_v.shape[0]
+        pooled_var_count += pos_v.shape[0]
+
+    collective = {
+        "frame": np.asarray(frames, dtype=np.int64),
+        "n_cells": np.asarray(n_cells, dtype=np.int64),
+        "order_param": np.asarray(order, dtype=float),
+        "corr_length_um": np.asarray(corr_len, dtype=float),
+        "nn_distance_um": np.asarray(nn_dist, dtype=float),
+    }
+    curve = _pooled_curve(pooled_dot, pooled_count, pooled_var_sum, pooled_var_count, bin_width)
+    return collective, curve
+
+
+# --------------------------------------------------------------------- helpers
+def _per_frame_views(frames_all, x, y, vx, vy):
+    """``frame -> (positions_all, positions_with_velocity, velocities)`` arrays."""
+    out: dict[int, tuple[np.ndarray, np.ndarray, np.ndarray]] = {}
+    for frame in np.unique(frames_all):
+        m = frames_all == frame
+        pos_all = np.column_stack((x[m], y[m]))
+        has_v = np.isfinite(vx[m]) & np.isfinite(vy[m])
+        pos_v = pos_all[has_v]
+        vel = np.column_stack((vx[m][has_v], vy[m][has_v]))
+        out[int(frame)] = (pos_all, pos_v, vel)
+    return out
+
+
+def _resolve_bin_width(corr_bin_um, per_frame) -> float:
+    if corr_bin_um is not None and float(corr_bin_um) > 0:
+        return float(corr_bin_um)
+    nn = [_median_nn_distance(pos_all) for pos_all, _, _ in per_frame.values()]
+    nn = [v for v in nn if np.isfinite(v) and v > 0]
+    return float(np.median(nn)) if nn else 1.0
+
+
+def _order_parameter(vel: np.ndarray) -> float:
+    speed = np.hypot(vel[:, 0], vel[:, 1])
+    moving = speed > 0
+    if not moving.any():
+        return float("nan")
+    units = vel[moving] / speed[moving, None]
+    return float(np.hypot(*units.mean(axis=0)))
+
+
+def _velocity_correlation(pos: np.ndarray, dV: np.ndarray, bin_width: float, var: float):
+    """Per-frame ``C(r)``: bin centres, normalised correlation, pair counts, dot sums."""
+    n = pos.shape[0]
+    iu, ju = np.triu_indices(n, k=1)
+    diff = pos[iu] - pos[ju]
+    r = np.hypot(diff[:, 0], diff[:, 1])
+    dots = np.einsum("ij,ij->i", dV[iu], dV[ju])
+    bins = np.floor(r / bin_width).astype(np.int64)
+
+    dot_by_bin: dict[int, float] = {}
+    count_by_bin: dict[int, int] = {}
+    for b, d in zip(bins.tolist(), dots.tolist()):
+        dot_by_bin[b] = dot_by_bin.get(b, 0.0) + d
+        count_by_bin[b] = count_by_bin.get(b, 0) + 1
+
+    order = sorted(dot_by_bin)
+    centers = np.asarray([(b + 0.5) * bin_width for b in order], dtype=float)
+    denom = var if var > 0 else np.nan
+    C = np.asarray([dot_by_bin[b] / count_by_bin[b] / denom for b in order], dtype=float)
+    counts = {b: count_by_bin[b] for b in order}
+    return centers, C, counts, dot_by_bin
+
+
+def pooled_corr_length(corr_curve: dict[str, np.ndarray]) -> float:
+    """Single per-tissue correlation length ``ξ`` from the pooled ``C(r)`` curve.
+
+    Applies the same ``1/e`` crossing rule as the per-frame ``corr_length_um``
+    column to the dataset-level pooled curve; returns ``NaN`` when the curve is
+    empty or never decays to ``1/e``.
+    """
+    centers = np.asarray(corr_curve.get("separation_um", []), dtype=float)
+    C = np.asarray(corr_curve.get("corr", []), dtype=float)
+    if centers.size == 0:
+        return float("nan")
+    return _one_over_e_length(centers, C)
+
+
+def _one_over_e_length(centers: np.ndarray, C: np.ndarray) -> float:
+    """Separation where *C* first decays to ``1/e``, by linear interpolation."""
+    if centers.size == 0:
+        return float("nan")
+    for i in range(centers.size):
+        if C[i] <= _INV_E:
+            if i == 0:
+                # Already below 1/e at the first populated bin: the curve
+                # crossed at a separation smaller than we can resolve. Report
+                # "cannot resolve" (NaN) rather than claiming ξ = the first bin
+                # center, which would overstate the resolution.
+                return float("nan")
+            c0, c1 = C[i - 1], C[i]
+            if c0 == c1:
+                return float(centers[i])
+            t = (c0 - _INV_E) / (c0 - c1)
+            return float(centers[i - 1] + t * (centers[i] - centers[i - 1]))
+    return float("nan")  # never decays to 1/e within the field
+
+
+def _pooled_curve(dot_by_bin, count_by_bin, var_sum, var_count, bin_width):
+    if not count_by_bin or var_count == 0:
+        return {name: np.asarray([], dtype=float) for name in CORR_CURVE_COLUMNS}
+    var = var_sum / var_count
+    order = sorted(count_by_bin)
+    sep = np.asarray([(b + 0.5) * bin_width for b in order], dtype=float)
+    corr = np.asarray(
+        [dot_by_bin[b] / count_by_bin[b] / var if var > 0 else np.nan for b in order],
+        dtype=float,
+    )
+    n_pairs = np.asarray([count_by_bin[b] for b in order], dtype=np.int64)
+    return {"separation_um": sep, "corr": corr, "n_pairs": n_pairs}
+
+
+def _median_nn_distance(pos: np.ndarray) -> float:
+    n = pos.shape[0]
+    if n < 2:
+        return float("nan")
+    # Pairwise distances; small per-frame cell counts make this cheap and exact.
+    diff = pos[:, None, :] - pos[None, :, :]
+    dist = np.hypot(diff[..., 0], diff[..., 1])
+    np.fill_diagonal(dist, np.inf)
+    return float(np.median(dist.min(axis=1)))

itasc/contact_analysis/dynamics/kinematics.py

@@ -0,0 +1,278 @@
+"""Per-frame velocities, per-track motility summaries, and persistence times.
+
+Pure NumPy over :class:`~.trajectories.Trajectory` lists; no I/O, no Qt. Three
+public pieces:
+
+* :func:`instantaneous_table` — one row per ``(frame, cell_id)``: position,
+  velocity, speed, and net displacement from the track's start. Forward
+  differences between consecutive **present** frames, divided by the *real*
+  elapsed time ``Δf · dt`` so gaps don't inflate speed. A track's last present
+  frame has no forward step → NaN velocity/speed.
+* :func:`track_summary_table` — one row per track: path length, net displacement,
+  curvilinear / net speed, directionality (confinement) ratio, and the
+  directional-autocorrelation persistence time.
+* :func:`directional_autocorrelation` / :func:`fit_persistence_time` — the
+  shared DAC machinery, reused for the ensemble curve in :mod:`.msd`-adjacent
+  code (the dynamics store) and for each track's own persistence time.
+
+``step directions`` use only **real** single-frame steps (``Δf == 1``); a step
+spanning a gap is dropped from the direction statistics (its heading over the
+gap is unreliable), though it still contributes to path length / speed.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .trajectories import Trajectory
+
+#: Instantaneous per-(frame, cell) value columns (keys ``frame``/``cell_id`` are
+#: prepended by the store). Order is the on-disk order.
+INSTANTANEOUS_COLUMNS = (
+    "x_um",
+    "y_um",
+    "vx_um_per_s",
+    "vy_um_per_s",
+    "speed_um_per_s",
+    "net_disp_um",
+)
+
+#: Ensemble directional-autocorrelation curve columns.
+DAC_COLUMNS = ("lag_s", "dac", "n_samples", "sem")
+
+#: Per-track summary value columns (key ``cell_id`` prepended by the store).
+TRACK_COLUMNS = (
+    "n_frames",
+    "n_gaps",
+    "frame_start",
+    "frame_end",
+    "duration_s",
+    "path_length_um",
+    "net_displacement_um",
+    "curvilinear_speed_um_per_s",
+    "net_speed_um_per_s",
+    "directionality_ratio",
+    "persistence_time_s",
+)
+
+
+def instantaneous_table(
+    trajectories: list[Trajectory], *, time_interval_s: float
+) -> dict[str, np.ndarray]:
+    """Column-major ``(frame, cell_id, …INSTANTANEOUS_COLUMNS)`` over all tracks."""
+    dt = float(time_interval_s)
+    frame: list[int] = []
+    cell_id: list[int] = []
+    cols: dict[str, list[float]] = {name: [] for name in INSTANTANEOUS_COLUMNS}
+    for traj in trajectories:
+        xy = traj.xy
+        frames = traj.frames
+        n = traj.n_frames
+        r0 = xy[0]
+        for k in range(n):
+            frame.append(int(frames[k]))
+            cell_id.append(traj.track_id)
+            cols["x_um"].append(float(xy[k, 0]))
+            cols["y_um"].append(float(xy[k, 1]))
+            cols["net_disp_um"].append(float(np.hypot(*(xy[k] - r0))))
+            if k < n - 1:
+                dt_real = float(frames[k + 1] - frames[k]) * dt
+                step = xy[k + 1] - xy[k]
+                vx, vy = step / dt_real
+                cols["vx_um_per_s"].append(float(vx))
+                cols["vy_um_per_s"].append(float(vy))
+                cols["speed_um_per_s"].append(float(np.hypot(vx, vy)))
+            else:
+                cols["vx_um_per_s"].append(np.nan)
+                cols["vy_um_per_s"].append(np.nan)
+                cols["speed_um_per_s"].append(np.nan)
+    out: dict[str, np.ndarray] = {
+        "frame": np.asarray(frame, dtype=np.int64),
+        "cell_id": np.asarray(cell_id, dtype=np.int64),
+    }
+    for name in INSTANTANEOUS_COLUMNS:
+        out[name] = np.asarray(cols[name], dtype=float)
+    return out
+
+
+def track_summary_table(
+    trajectories: list[Trajectory],
+    *,
+    time_interval_s: float,
+    min_track_frames: int = 3,
+) -> dict[str, np.ndarray]:
+    """Column-major per-track summary; tracks shorter than *min_track_frames* drop."""
+    dt = float(time_interval_s)
+    cell_id: list[int] = []
+    rows: dict[str, list[float]] = {name: [] for name in TRACK_COLUMNS}
+    for traj in trajectories:
+        if traj.n_frames < int(min_track_frames):
+            continue
+        xy = traj.xy
+        frames = traj.frames
+        steps = np.diff(xy, axis=0)
+        step_len = np.hypot(steps[:, 0], steps[:, 1])
+        path_length = float(step_len.sum())
+        net_disp = float(np.hypot(*(xy[-1] - xy[0])))
+        duration = float(frames[-1] - frames[0]) * dt
+        curv_speed = path_length / duration if duration > 0 else np.nan
+        net_speed = net_disp / duration if duration > 0 else np.nan
+        dir_ratio = net_disp / path_length if path_length > 0 else np.nan
+        persistence = _track_persistence_time(traj, time_interval_s=dt)
+
+        cell_id.append(traj.track_id)
+        rows["n_frames"].append(traj.n_frames)
+        rows["n_gaps"].append(traj.n_gaps)
+        rows["frame_start"].append(int(frames[0]))
+        rows["frame_end"].append(int(frames[-1]))
+        rows["duration_s"].append(duration)
+        rows["path_length_um"].append(path_length)
+        rows["net_displacement_um"].append(net_disp)
+        rows["curvilinear_speed_um_per_s"].append(curv_speed)
+        rows["net_speed_um_per_s"].append(net_speed)
+        rows["directionality_ratio"].append(dir_ratio)
+        rows["persistence_time_s"].append(persistence)
+
+    out: dict[str, np.ndarray] = {"cell_id": np.asarray(cell_id, dtype=np.int64)}
+    # Integer-valued columns stay integers on disk; the rest are floats (NaN-safe).
+    int_cols = {"n_frames", "n_gaps", "frame_start", "frame_end"}
+    for name in TRACK_COLUMNS:
+        dtype = np.int64 if name in int_cols else float
+        out[name] = np.asarray(rows[name], dtype=dtype)
+    return out
+
+
+# --------------------------------------------------------- directional autocorr
+def step_directions_by_frame(traj: Trajectory) -> dict[int, np.ndarray]:
+    """``start_frame -> unit step direction`` for each **real** (``Δf == 1``) step.
+
+    Zero-length steps (a stationary cell) have no defined direction and are
+    skipped.
+    """
+    out: dict[int, np.ndarray] = {}
+    frames = traj.frames
+    xy = traj.xy
+    for k in range(traj.n_frames - 1):
+        if int(frames[k + 1] - frames[k]) != 1:
+            continue
+        step = xy[k + 1] - xy[k]
+        norm = float(np.hypot(step[0], step[1]))
+        if norm > 0:
+            out[int(frames[k])] = step / norm
+    return out
+
+
+def accumulate_dac(
+    dirs_by_frame: dict[int, np.ndarray],
+    max_lag: int,
+    sums: dict[int, float],
+    counts: dict[int, int],
+    sumsq: dict[int, float] | None = None,
+) -> None:
+    """Add ``û(f)·û(f+n)`` dot products into *sums* / *counts*, keyed by lag *n*.
+
+    Reused for a single track (fresh accumulators → that track's persistence
+    time) and for the ensemble (shared accumulators across all tracks). Pass
+    *sumsq* to also accumulate squared dot products (for the ensemble SEM).
+    """
+    if not dirs_by_frame:
+        return
+    for f in sorted(dirs_by_frame):
+        u = dirs_by_frame[f]
+        for n in range(1, max_lag + 1):
+            v = dirs_by_frame.get(f + n)
+            if v is None:  # f+n absent (gap / track end) — no pair at this lag
+                continue
+            dot = float(u[0] * v[0] + u[1] * v[1])
+            sums[n] = sums.get(n, 0.0) + dot
+            counts[n] = counts.get(n, 0) + 1
+            if sumsq is not None:
+                sumsq[n] = sumsq.get(n, 0.0) + dot * dot
+
+
+def ensemble_dac(
+    trajectories: list[Trajectory], *, time_interval_s: float
+) -> tuple[dict[str, np.ndarray], float]:
+    """Pooled DAC curve over all tracks → ``(DAC_COLUMNS table, persistence_s)``.
+
+    Each track contributes its real-step direction pairs up to its own span; the
+    fitted ensemble persistence time uses the same recipe as the per-track one.
+    """
+    dt = float(time_interval_s)
+    sums: dict[int, float] = {}
+    counts: dict[int, int] = {}
+    sumsq: dict[int, float] = {}
+    for traj in trajectories:
+        dirs = step_directions_by_frame(traj)
+        if len(dirs) < 2:
+            continue
+        accumulate_dac(dirs, max(dirs) - min(dirs), sums, counts, sumsq)
+
+    lags, dac, n_samples = directional_autocorrelation(sums, counts)
+    lag_s = lags.astype(float) * dt
+    sem = np.asarray(
+        [_dac_sem(sums[int(n)], sumsq[int(n)], counts[int(n)]) for n in lags],
+        dtype=float,
+    )
+    table = {"lag_s": lag_s, "dac": dac, "n_samples": n_samples, "sem": sem}
+    return table, fit_persistence_time(lag_s, dac)
+
+
+def _dac_sem(s: float, ss: float, count: int) -> float:
+    if count < 2:
+        return float("nan")
+    var = (ss - s * s / count) / (count - 1)
+    return float(np.sqrt(max(var, 0.0) / count))
+
+
+def directional_autocorrelation(
+    sums: dict[int, float], counts: dict[int, int]
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Turn accumulated sums/counts into ``(lags, C, n_samples)`` arrays.
+
+    ``lags`` are integer frame lags ``1 … max`` present in *counts*, sorted.
+    """
+    lags = np.asarray(sorted(counts), dtype=np.int64)
+    C = np.asarray([sums[n] / counts[n] for n in lags], dtype=float)
+    n_samples = np.asarray([counts[n] for n in lags], dtype=np.int64)
+    return lags, C, n_samples
+
+
+def fit_persistence_time(lags_s: np.ndarray, C: np.ndarray) -> float:
+    """Fit ``C = exp(-τ/P)`` over the leading positive run; return ``P`` (s).
+
+    Linear fit of ``ln C`` vs ``τ`` across the contiguous ``C > 0`` prefix
+    (autocorrelation decays from 1, so the leading run is the signal). ``P =
+    -1/slope``. NaN when fewer than two positive points or a non-negative slope
+    (no decay).
+    """
+    lags_s = np.asarray(lags_s, dtype=float)
+    C = np.asarray(C, dtype=float)
+    if lags_s.size == 0:
+        return float("nan")
+    # Leading contiguous positive run.
+    positive = C > 0
+    if not positive[0]:
+        return float("nan")
+    cut = int(np.argmin(positive)) if not positive.all() else positive.size
+    if cut < 2:
+        return float("nan")
+    x = lags_s[:cut]
+    y = np.log(C[:cut])
+    slope = float(np.polyfit(x, y, 1)[0])
+    if slope >= 0:
+        return float("nan")
+    return -1.0 / slope
+
+
+def _track_persistence_time(traj: Trajectory, *, time_interval_s: float) -> float:
+    dirs = step_directions_by_frame(traj)
+    if len(dirs) < 2:
+        return float("nan")
+    max_lag = max(dirs) - min(dirs)
+    sums: dict[int, float] = {}
+    counts: dict[int, int] = {}
+    accumulate_dac(dirs, max_lag, sums, counts)
+    if not counts:
+        return float("nan")
+    lags, C, _ = directional_autocorrelation(sums, counts)
+    return fit_persistence_time(lags.astype(float) * float(time_interval_s), C)

itasc/contact_analysis/dynamics/msd.py

@@ -0,0 +1,165 @@
+"""Ensemble time-averaged mean-square displacement and its power-law fit.
+
+For each integer frame lag ``n``, the MSD is averaged over **all tracks** and
+**all present overlapping origin pairs** ``(k, k+n)`` whose frames are separated
+by exactly ``n`` (a gap inside a pair breaks it, so only genuine ``n``-frame
+displacements count)::
+
+    MSD(n) = mean over tracks, origins of |r(f+n) − r(f)|²        (µm²)
+
+Lags run ``1 … n_max`` with ``n_max = max(1, ⌊¼ · longest track span⌋)`` — the
+usual reliability cap, since large-lag estimates rest on few, strongly
+overlapping samples. The curve is fit in log-log to ``MSD = 2·d·D·τ^α`` (``d =
+2``): ``α`` is the anomalous exponent (≈1 diffusive, →2 ballistic/persistent, <1
+confined) and ``D`` the (generalised) diffusion coefficient in µm²/s. Pure
+NumPy; no I/O.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .trajectories import Trajectory
+
+#: Spatial dimensionality of the trajectories (2-D centroids everywhere here).
+_DIMS = 2
+
+#: MSD curve columns (the store prepends nothing; these are the full set).
+MSD_COLUMNS = ("lag_s", "msd_um2", "n_samples", "sem")
+
+#: Per-track MSD-fit value columns, merged into the per-track summary table.
+MSD_TRACK_COLUMNS = ("msd_D_um2_per_s", "msd_alpha", "msd_r2")
+#: Default fixed lag window (frames) for the per-track MSD fit. A fixed window
+#: makes every track's ``D``/``α`` comparable and excludes the noisy long-lag tail.
+DEFAULT_MSD_TRACK_WINDOW = 8
+
+
+@dataclass(frozen=True)
+class MsdFit:
+    """Power-law fit of the MSD curve: ``MSD = 2·d·D·τ^α``."""
+
+    D_um2_per_s: float
+    alpha: float
+    r2: float
+
+
+def ensemble_msd(
+    trajectories: list[Trajectory],
+    *,
+    time_interval_s: float,
+    n_max: int | None = None,
+) -> dict[str, np.ndarray]:
+    """Column-major ``MSD_COLUMNS`` table (``lag_s, msd_um2, n_samples, sem``)."""
+    dt = float(time_interval_s)
+    if n_max is None:
+        n_max = _default_n_max(trajectories)
+    # lag -> running sum of squared displacements and a list for the SEM.
+    sq_by_lag: dict[int, list[float]] = {}
+    for traj in trajectories:
+        _accumulate_track_sq(traj, n_max, sq_by_lag)
+
+    lags = np.asarray(sorted(sq_by_lag), dtype=np.int64)
+    msd = np.empty(lags.size, dtype=float)
+    n_samples = np.empty(lags.size, dtype=np.int64)
+    sem = np.empty(lags.size, dtype=float)
+    for i, n in enumerate(lags):
+        vals = np.asarray(sq_by_lag[int(n)], dtype=float)
+        msd[i] = float(vals.mean())
+        n_samples[i] = vals.size
+        sem[i] = float(vals.std(ddof=1) / np.sqrt(vals.size)) if vals.size > 1 else np.nan
+    return {
+        "lag_s": lags.astype(float) * dt,
+        "msd_um2": msd,
+        "n_samples": n_samples,
+        "sem": sem,
+    }
+
+
+def fit_msd_power_law(
+    lag_s: np.ndarray, msd_um2: np.ndarray, *, min_samples_mask: np.ndarray | None = None
+) -> MsdFit:
+    """Log-log fit ``log MSD = log(2dD) + α·log τ`` → :class:`MsdFit`.
+
+    *min_samples_mask* optionally restricts the fit to well-sampled lags. NaNs in
+    ``D``/``α``/``r2`` when fewer than two usable positive points remain.
+    """
+    lag_s = np.asarray(lag_s, dtype=float)
+    msd_um2 = np.asarray(msd_um2, dtype=float)
+    valid = (lag_s > 0) & (msd_um2 > 0) & np.isfinite(lag_s) & np.isfinite(msd_um2)
+    if min_samples_mask is not None:
+        valid &= np.asarray(min_samples_mask, dtype=bool)
+    if int(valid.sum()) < 2:
+        return MsdFit(float("nan"), float("nan"), float("nan"))
+    x = np.log(lag_s[valid])
+    y = np.log(msd_um2[valid])
+    slope, intercept = np.polyfit(x, y, 1)
+    alpha = float(slope)
+    D = float(np.exp(intercept) / (2.0 * _DIMS))
+    r2 = _r_squared(x, y, slope, intercept)
+    return MsdFit(D_um2_per_s=D, alpha=alpha, r2=r2)
+
+
+def per_track_msd_fit(
+    trajectories: list[Trajectory],
+    *,
+    time_interval_s: float,
+    window_frames: int = DEFAULT_MSD_TRACK_WINDOW,
+) -> dict[int, MsdFit]:
+    """Fit each track's own MSD over a shared fixed lag window → ``track_id → MsdFit``.
+
+    For each track the MSD is averaged over its present ``(k, k+n)`` origin pairs
+    for lags ``1 … window_frames`` (the same rule as :func:`ensemble_msd`, capped
+    at the window), then fit in log-log. A track that cannot fill at least two
+    distinct lags within the window yields ``MsdFit(nan, nan, nan)``, so its
+    ``D``/``α``/``r2`` are NaN rather than a spurious single-point slope.
+    """
+    dt = float(time_interval_s)
+    window = int(window_frames)
+    fits: dict[int, MsdFit] = {}
+    for traj in trajectories:
+        sq_by_lag: dict[int, list[float]] = {}
+        _accumulate_track_sq(traj, window, sq_by_lag)
+        if len(sq_by_lag) < 2:
+            fits[traj.track_id] = MsdFit(float("nan"), float("nan"), float("nan"))
+            continue
+        lags = np.asarray(sorted(sq_by_lag), dtype=np.int64)
+        msd = np.asarray([float(np.mean(sq_by_lag[int(n)])) for n in lags], dtype=float)
+        fits[traj.track_id] = fit_msd_power_law(lags.astype(float) * dt, msd)
+    return fits
+
+
+def _accumulate_track_sq(
+    traj: Trajectory, n_max: int, sq_by_lag: dict[int, list[float]]
+) -> None:
+    frames = traj.frames
+    xy = traj.xy
+    # frame -> position index, so an origin pair is "present" only when both
+    # endpoints exist and are exactly n frames apart.
+    pos = {int(f): i for i, f in enumerate(frames)}
+    for f, i in pos.items():
+        for n in range(1, n_max + 1):
+            j = pos.get(f + n)
+            if j is None:
+                continue
+            d = xy[j] - xy[i]
+            sq_by_lag.setdefault(n, []).append(float(d[0] * d[0] + d[1] * d[1]))
+
+
+def _default_n_max(trajectories: list[Trajectory]) -> int:
+    # Use each track's effective length (number of observed points), not its
+    # frame span. A gappy 2-point track present only in frames {0, 400} has a
+    # span of 400 but supports a single lag; keying n_max off the span would
+    # extend the ensemble MSD curve into an unreliable, poorly-sampled tail.
+    lengths = [t.n_frames - 1 for t in trajectories if t.n_frames >= 2]
+    longest = max(lengths) if lengths else 1
+    return max(1, longest // 4)
+
+
+def _r_squared(x: np.ndarray, y: np.ndarray, slope: float, intercept: float) -> float:
+    pred = slope * x + intercept
+    ss_res = float(np.sum((y - pred) ** 2))
+    ss_tot = float(np.sum((y - y.mean()) ** 2))
+    if ss_tot == 0:
+        return float("nan")
+    return 1.0 - ss_res / ss_tot