itasc.contact_analysis.dynamics.collective

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.

Module attributes

COLLECTIVE_COLUMNS

Per-frame collective columns.

CORR_CURVE_COLUMNS

Pooled correlation-curve columns.

Functions

collective_tables(instantaneous, *[, ...])

Return (collective_table, corr_curve_table) from the instantaneous table.

pooled_corr_length(corr_curve)

Single per-tissue correlation length ξ from the pooled C(r) curve.
itasc.contact_analysis.dynamics.collective.COLLECTIVE_COLUMNS = ('frame', 'n_cells', 'order_param', 'corr_length_um', 'nn_distance_um')

Per-frame collective columns.

itasc.contact_analysis.dynamics.collective.CORR_CURVE_COLUMNS = ('separation_um', 'corr', 'n_pairs')

Pooled correlation-curve columns.

itasc.contact_analysis.dynamics.collective.collective_tables(instantaneous, *, corr_bin_um=None, min_cells=5)[source]

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.

Return type:

tuple[dict[str, ndarray], dict[str, ndarray]]

Parameters:
itasc.contact_analysis.dynamics.collective.pooled_corr_length(corr_curve)[source]

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