itasc.contact_analysis.dynamics.kinematics

Per-frame velocities, per-track motility summaries, and persistence times.

Pure NumPy over Trajectory lists; no I/O, no Qt. Three public pieces:

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

• track_summary_table() — one row per track: path length, net displacement, curvilinear / net speed, directionality (confinement) ratio, and the directional-autocorrelation persistence time.

• directional_autocorrelation() / fit_persistence_time() — the shared DAC machinery, reused for the ensemble curve in 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.

Module attributes

INSTANTANEOUS_COLUMNS	Instantaneous per-(frame, cell) value columns (keys frame/cell_id are prepended by the store).
DAC_COLUMNS	Ensemble directional-autocorrelation curve columns.
TRACK_COLUMNS	Per-track summary value columns (key cell_id prepended by the store).

Functions

accumulate_dac(dirs_by_frame, max_lag, sums, ...)	Add û(f)·û(f+n) dot products into sums / counts, keyed by lag n.
directional_autocorrelation(sums, counts)	Turn accumulated sums/counts into (lags, C, n_samples) arrays.
ensemble_dac(trajectories, *, time_interval_s)	Pooled DAC curve over all tracks → (DAC_COLUMNS table, persistence_s).
fit_persistence_time(lags_s, C)	Fit C = exp(-τ/P) over the leading positive run; return P (s).
instantaneous_table(trajectories, *, ...)	Column-major (frame, cell_id, …INSTANTANEOUS_COLUMNS) over all tracks.
step_directions_by_frame(traj)	start_frame -> unit step direction for each real (Δf == 1) step.
track_summary_table(trajectories, *, ...[, ...])	Column-major per-track summary; tracks shorter than min_track_frames drop.

itasc.contact_analysis.dynamics.kinematics.INSTANTANEOUS_COLUMNS = ('x_um', 'y_um', 'vx_um_per_s', 'vy_um_per_s', 'speed_um_per_s', 'net_disp_um')

Instantaneous per-(frame, cell) value columns (keys frame/cell_id are prepended by the store). Order is the on-disk order.

itasc.contact_analysis.dynamics.kinematics.DAC_COLUMNS = ('lag_s', 'dac', 'n_samples', 'sem')

Ensemble directional-autocorrelation curve columns.

itasc.contact_analysis.dynamics.kinematics.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')

Per-track summary value columns (key cell_id prepended by the store).

itasc.contact_analysis.dynamics.kinematics.instantaneous_table(trajectories, *, time_interval_s)

Column-major (frame, cell_id, …INSTANTANEOUS_COLUMNS) over all tracks.

Return type:

dict[str, ndarray]

Parameters:

• trajectories (list[Trajectory])

• time_interval_s (float)

itasc.contact_analysis.dynamics.kinematics.track_summary_table(trajectories, *, time_interval_s, min_track_frames=3)

Column-major per-track summary; tracks shorter than min_track_frames drop.

Return type:

dict[str, ndarray]

Parameters:

• trajectories (list[Trajectory])

• time_interval_s (float)

• min_track_frames (int)

itasc.contact_analysis.dynamics.kinematics.step_directions_by_frame(traj)

start_frame -> unit step direction for each real (Δf == 1) step.

Zero-length steps (a stationary cell) have no defined direction and are skipped.

Return type:

dict[int, ndarray]

Parameters:

traj (Trajectory)

itasc.contact_analysis.dynamics.kinematics.accumulate_dac(dirs_by_frame, max_lag, sums, counts, sumsq=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).

Return type:

None

Parameters:

• dirs_by_frame (dict[int, ndarray])

• max_lag (int)

• sums (dict[int, float])

• counts (dict[int, int])

• sumsq (dict[int, float] | None)

itasc.contact_analysis.dynamics.kinematics.ensemble_dac(trajectories, *, time_interval_s)

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.

Return type:

tuple[dict[str, ndarray], float]

Parameters:

• trajectories (list[Trajectory])

• time_interval_s (float)

itasc.contact_analysis.dynamics.kinematics.directional_autocorrelation(sums, counts)

Turn accumulated sums/counts into (lags, C, n_samples) arrays.

lags are integer frame lags 1 … max present in counts, sorted.

Return type:

tuple[ndarray, ndarray, ndarray]

Parameters:

• sums (dict[int, float])

• counts (dict[int, int])

itasc.contact_analysis.dynamics.kinematics.fit_persistence_time(lags_s, C)

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

Return type:

float

Parameters:

• lags_s (ndarray)

• C (ndarray)