pyhctsa.operations.nonlinearity.largest_lyap¶

pyhctsa.operations.nonlinearity.largest_lyap(y, nref=-1, maxtstep=('ac1e', 30), past=('ac1e', 1), nnr=3, embed_params=('ac', 'fnn'))¶

Largest Lyapunov exponent: how nearest-neighbor trajectories diverge, and the scaling of that divergence.

Estimates the divergence of nearby trajectories of the delay embedding as a function of time by the algorithm of Rosenstein et al. [1] (TISEAN’s lyap_r): the logarithm of the distance between each reference point’s trajectory and that of its nearest neighbor (outside a Theiler window) averaged over the reference points, \(p(t)\), for t up to maxtstep. For a chaotic system, \(p\) rises linearly before saturating, with slope the largest Lyapunov exponent. Outputs summarize \(p\) (its first values, maximum, crossings of fractions of the maximum, times to reach them), straight-line fits to its scaling region (varying both start and end times, vse, or just the end time, ve, chosen to minimize the mean absolute residual less 0.006 per point), those slopes per autocorrelation time, and a saturating exponential fit \(a (1 - e^{bt})\).

Unlike hctsa, which shells out to installed TISEAN binaries, this runs an in-process port of lyap_r.

Distances are compared with a tolerance of 1e-12 (of the range of the data), so that the result depends neither on rounding nor on the order in which neighbors are searched: a point closer than that to the reference point is the same state visited again, not a neighbor; when several points are equally near (within the tolerance), each contributes its log-distance curve with weight one over their number (the expected curve for a random choice among them); and a pair that merges (comes within the tolerance) within the maxtstep steps is left out at every step, so that every step averages over the same pairs. With a unique nearest neighbor and no merging, as for continuously distributed data, this is the published method.

References

Parameters:¶

y : array-like¶

Input time series.

nref : int or float, optional¶

Unused (kept for compatibility with hctsa’s signature). Default is -1.

maxtstep=('ac1e', 30)¶

The maximum number of time steps to follow neighbors for: a number of steps, a value in (0, 1) as a proportion of the time-series length, or ['ac1e', k] (or ['ac', k]) for k times the autocorrelation time (see pyhctsa.utils.theiler_window()). At least 10 and at most half the series length; an 'ac1e' horizon too long for the series is shortened to fit (NaN if this leaves fewer than max(10, 3 * ac1e time) steps). Default is ['ac1e', 30].

past=('ac1e', 1)¶

The Theiler window of time-correlated points to exclude as neighbors (see pyhctsa.utils.theiler_window()). Default is ['ac1e', 1].

nnr : int, optional¶

Unused (kept for compatibility with hctsa’s signature). Default is 3.

embed_params : [tau, m], optional¶

Embedding parameters: tau is an integer or a rule understood by pyhctsa.utils.get_tau() ('ac', 'ac1e', 'mi'), m an integer, or 'fnn' (or ['fnn', threshold]) for the dimension from TISEAN’s false nearest neighbors (fnn(); threshold 0.05 by default; at most floor(2 log10 N), see _embedding_params()). Default is ['ac', 'fnn'].

Returns:¶

p1 to p5, maxp: the first five values and the maximum of \(p(t)\) (relative to \(p(0)\)); ncross08max, pcross08max, ncross09max, pcross09max: the number (and proportion) of times \(p\) crosses 80% and 90% of its maximum; to095max … to05max: the time to first exceed 95%, 90%, 80%, 70%, 50% of the maximum; vse_* and ve_* (meanabsres, rmsres, gradient, intercept, minbad, and gradient_pertau, the gradient per autocorrelation time): the straight-line fits (NaN if the rise to 95% of the maximum takes at most three steps, or \(p\) never rises above its value at \(t = 0\)); expfit_a, expfit_b, expfit_r2, expfit_adjr2, expfit_rmse: the least-squares fit of a saturating exponential, a*(1 - exp(b*t)) (the global optimum over rates 1e-5 <= |b| <= 5 per time step; see _saturating_exp_fit). Returns NaN if the delay, horizon, or Theiler window cannot be set, the series is too short for the horizon, TISEAN finds no neighbor for some reference point (data too sparse or quantized) or too little output, or the curve is flat.

Return type:¶

dict or float