pyhctsa.operations.physics.kramers_moyal

pyhctsa.operations.physics.kramers_moyal(y, tau=1, num_bins=15)

How the series’ average drift and noise intensity depend on its current level, from its increments.

Treats the time series as a sampled Langevin process, dx = D1(x) dt + sqrt(2 D2(x)) dW, and estimates the conditional-moment (Kramers-Moyal) coefficients as a function of the current level x, from increments over tau samples:

D1(x) = E[dx | x] / tau            (drift: the deterministic restoring force)
D2(x) = E[dx^2 | x] / (2 tau)      (diffusion: the local noise intensity)
D4(x) = E[dx^4 | x] / (24 tau)

with conditioning on x done in equiprobable (quantile) bins.

The features summarize the shape of D1 and D2 across levels: a linear D1 with a constant D2 is an Ornstein-Uhlenbeck (AR(1)-like) process; a cubic D1 indicates a nonlinear potential (e.g., bistability); a D2 that varies with x indicates state-dependent noise (note that a monotone transformation of an Ornstein-Uhlenbeck process also has state-dependent D2, so this is partly a property of the marginal distribution); the Pawula ratio D4/D2^2 is small for continuous diffusion and large when increments are dominated by jumps.

Parameters:
y : array-like

The input time series (z-scored in hctsa).

tau : int or str, optional

The increment lag, in samples (default: 1); or a rule that sets it from the series: ‘ac’ (first zero-crossing of the autocorrelation function), ‘ac1e’ (floor of its first 1/e crossing), or ‘mi’ (the smaller of the first minimum of the Kraskov automutual information and the ‘ac1e’ delay); see pyhctsa.utils.get_tau.

num_bins : int, optional

The number of equiprobable bins used to condition on x (default: 15).

Returns:

Dictionary containing:

  • driftLin, driftQuad, driftCubic: coefficients of a count-weighted cubic fit of D1(x) (driftCubic < 0 for a stiffening restoring force).

  • driftNonlinGain: fraction of the residual variance of a linear drift fit that is removed by the cubic fit (0 = linear drift).

  • diffSlope, diffCurv: linear and quadratic coefficients of a quadratic fit of D2(x), each relative to the mean of D2 across bins (0 = additive noise).

  • diffTailRatio: mean D2 in the outer bins (the lowest and highest fifth of the bins) / mean D2 in the central bins.

  • pawula: mean over bins of D4/D2^2 (tau/2 for Gaussian increments; larger for jumps). Unlike the shape of D2, not changed by a monotone transformation of the data.

NaN (a single float) if there are fewer than 20 * num_bins increments, if no delay can be estimated for a tau rule, or if tied values make the quantile bins coincide.

Return type:

dict or float