itasc.contact_analysis.dynamics.msd

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.

Module attributes

MSD_COLUMNS

MSD curve columns (the store prepends nothing; these are the full set).

MSD_TRACK_COLUMNS

Per-track MSD-fit value columns, merged into the per-track summary table.

DEFAULT_MSD_TRACK_WINDOW

Default fixed lag window (frames) for the per-track MSD fit.

Functions

ensemble_msd(trajectories, *, time_interval_s)

Column-major MSD_COLUMNS table (lag_s, msd_um2, n_samples, sem).

fit_msd_power_law(lag_s, msd_um2, *[, ...])

Log-log fit log MSD = log(2dD) + α·log τ → MsdFit.

per_track_msd_fit(trajectories, *, ...[, ...])

Fit each track's own MSD over a shared fixed lag window → track_id → MsdFit.

Classes

MsdFit(D_um2_per_s, alpha, r2)

Power-law fit of the MSD curve: MSD = 2·d·D·τ^α.
itasc.contact_analysis.dynamics.msd.MSD_COLUMNS = ('lag_s', 'msd_um2', 'n_samples', 'sem')

MSD curve columns (the store prepends nothing; these are the full set).

itasc.contact_analysis.dynamics.msd.MSD_TRACK_COLUMNS = ('msd_D_um2_per_s', 'msd_alpha', 'msd_r2')

Per-track MSD-fit value columns, merged into the per-track summary table.

itasc.contact_analysis.dynamics.msd.DEFAULT_MSD_TRACK_WINDOW = 8

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.

class itasc.contact_analysis.dynamics.msd.MsdFit(D_um2_per_s, alpha, r2)[source]

Bases: object

Power-law fit of the MSD curve: MSD = 2·d·D·τ^α.

Parameters:
D_um2_per_s: float
alpha: float
r2: float
itasc.contact_analysis.dynamics.msd.ensemble_msd(trajectories, *, time_interval_s, n_max=None)[source]

Column-major MSD_COLUMNS table (lag_s, msd_um2, n_samples, sem).

Return type:

dict[str, ndarray]

Parameters:
itasc.contact_analysis.dynamics.msd.fit_msd_power_law(lag_s, msd_um2, *, min_samples_mask=None)[source]

Log-log fit log MSD = log(2dD) + α·log τ → MsdFit.

min_samples_mask optionally restricts the fit to well-sampled lags. NaNs in D/α/r2 when fewer than two usable positive points remain.

Return type:

MsdFit

Parameters:
itasc.contact_analysis.dynamics.msd.per_track_msd_fit(trajectories, *, time_interval_s, window_frames=8)[source]

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: