itasc.contact_analysis.dynamics

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 (trajectories), then instantaneous velocities + per-track motility summaries (kinematics), an ensemble mean-square-displacement curve with a power-law fit (msd), and tissue-scale collective metrics — alignment, velocity correlation, length scale (collective). build_track_dynamics() runs all of it and persists a multi-table .h5; read_track_dynamics() loads it back. No Qt / napari import, so scripts and the standalone wheel can use it.

class itasc.contact_analysis.dynamics.TrackDynamics(instantaneous, tracks, msd, dac, collective, corr_curve, msd_D_um2_per_s, msd_alpha, msd_r2, dac_persistence_time_s, corr_length_um)

Bases: object

In-memory view of a dynamics .h5 — every table plus the fit scalars.

Parameters:

• instantaneous (dict[str, ndarray])

• tracks (dict[str, ndarray])

• msd (dict[str, ndarray])

• dac (dict[str, ndarray])

• collective (dict[str, ndarray])

• corr_curve (dict[str, ndarray])

• msd_D_um2_per_s (float)

• msd_alpha (float)

• msd_r2 (float)

• dac_persistence_time_s (float)

• corr_length_um (float)

instantaneous: dict[str, ndarray]

tracks: dict[str, ndarray]

msd: dict[str, ndarray]

dac: dict[str, ndarray]

collective: dict[str, ndarray]

corr_curve: dict[str, ndarray]

msd_D_um2_per_s: float

msd_alpha: float

msd_r2: float

dac_persistence_time_s: float

corr_length_um: float

class itasc.contact_analysis.dynamics.Trajectory(track_id, frames, xy)

Bases: object

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.

Parameters:

• track_id (int)

• frames (ndarray)

• xy (ndarray)

track_id: int

frames: ndarray

xy: ndarray

property n_frames: int

property n_gaps: int

itasc.contact_analysis.dynamics.build_track_dynamics(label_path, output_path, *, pixel_size_um, time_interval_s, source_path=None, params=None, quantity_id='', progress_cb=None)

Compute every dynamics table from a tracked label TIFF and write the .h5.

Return type:

Path

Parameters:

• label_path (str | Path)

• output_path (str | Path)

• pixel_size_um (float)

• time_interval_s (float)

• source_path (str | Path | None)

• params (dict | None)

• quantity_id (str)

• progress_cb (Callable[[int, int, str], None] | None)

itasc.contact_analysis.dynamics.extract_trajectories(label_path, *, pixel_size_um, progress_cb=None)

Read a tracked label TIFF and return one 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.

Return type:

list[Trajectory]

Parameters:

• label_path (str | Path)

• pixel_size_um (float)

• progress_cb (Callable[[int, int, str], None] | None)

itasc.contact_analysis.dynamics.per_track_msd_fit(trajectories, *, time_interval_s, window_frames=8)

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 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.

Return type:

dict[int, MsdFit]

Parameters:

• trajectories (list[Trajectory])

• time_interval_s (float)

• window_frames (int)

itasc.contact_analysis.dynamics.pooled_corr_length(corr_curve)

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.

Return type:

float

Parameters:

corr_curve (dict[str, ndarray])

itasc.contact_analysis.dynamics.read_instantaneous_table(path)

The (frame, cell_id, …) instantaneous table — the tidy-table contract.

Return type:

dict[str, ndarray]

Parameters:

path (str | Path)

itasc.contact_analysis.dynamics.read_track_dynamics(path)

Load a dynamics .h5 into a TrackDynamics.

Return type:

TrackDynamics

Parameters:

path (str | Path)

itasc.contact_analysis.dynamics.trajectories_from_stack(label_stack, *, pixel_size_um, progress_cb=None)

extract_trajectories() over an in-memory T×Y×X label stack.

Return type:

list[Trajectory]

Parameters:

• label_stack (ndarray)

• pixel_size_um (float)

• progress_cb (Callable[[int, int, str], None] | None)

Submodules

collective	Tissue-scale collective motion: alignment, velocity correlation, length scale.
kinematics	Per-frame velocities, per-track motility summaries, and persistence times.
msd	Ensemble time-averaged mean-square displacement and its power-law fit.
store	Persist / read the track-dynamics artifact and orchestrate the build.
trajectories	Tracked label stack → per-track centroid trajectories (µm), gaps preserved.