pyhctsa.operations.nonlinearity.takens_estimator

pyhctsa.operations.nonlinearity.takens_estimator(y, nref=-1, c0=0.01, past=('ac', 1), embed_params=('ac', 'fnn'))

Takens’ estimator of the correlation dimension, at the length scale enclosing a fixed fraction of pairs.

Estimates the correlation dimension, \(D\), of a time-delay embedding of y with Takens’ estimator [1], at an upper length scale \(\epsilon_{up}\) set by the data: the c0 quantile of the max-norm distances between pairs of delay vectors (pairs closer in time than the Theiler window, and repeated points, are excluded). With \(r_{ij}\) the \(n\) pair distances below \(\epsilon_{up}\),

\[D = (n - 1) / \sum \ln(\epsilon_{up} / r_{ij}).\]

Under the estimator’s model, \(C(r) \propto r^D\) below \(\epsilon_{up}\), the \(\ln(\epsilon_{up} / r_{ij})\) are independent exponential variables with rate \(D\) given \(\epsilon_{up}\) ([1]; with \(\epsilon_{up}\) an order statistic of the distances, [2]), so their sum is Gamma(\(n\), \(D\)) and \((n - 1)/\sum\) is the unbiased estimate of \(D\) (the maximum-likelihood form \(n/\sum\) is biased upward by \(n/(n - 1)\) [3]).

Setting the length scale by a fraction of pairs, rather than as a fixed radius, keeps it at a small scale that always holds the same share of pairs, whatever the embedding dimension and the spread of the embedded points, and its target (the scale below which a fraction c0 of pairs lie) does not depend on the length of the series. (At a fixed radius, noise-like series embedded in several dimensions have no pairs at all at small scales.) Takens’ estimator is a reasonable dimension estimate when evaluated at the upper end of the scaling range [4], which for a low-dimensional attractor lies at small scales.

Details:

  • Pairs of delay vectors closer than tol = 1e-12 * (max(y) - min(y)) are repeated points: they carry no length-scale information, and a positive fraction of them makes the estimator inconsistent [3], so they are left out.

  • Distances closer than tol are equal. If the values of y lie on a lattice, i.e., all differences between distinct values are within 1% of integer multiples of a common step \(q\) (the smallest difference divided by the smallest \(k = 1, ..., 100\) that fits, well above tol, with \(q\) fitted to the differences by least squares; quantized data, also when stored with rounding), distances closer than \(q/2\) are equal, since finer differences are not resolved by the data. Equal distances are merged into levels after sorting (not snapped to a grid), each level taking its smallest value; pairs at the level of \(\epsilon_{up}\) lie at \(\epsilon_{up}\). The tolerances are relative to the data, so shifting, rescaling or reflecting y leaves the output unchanged, apart from distances within round-off of tol.

  • The output is NaN if fewer than 3 distinct distances lie below \(\epsilon_{up}\): the data then do not resolve the length scale (\(\epsilon_{up}\) lies within two resolution steps of the smallest distance), and the estimate is set by the lattice of the values rather than by the dynamics.

  • The output is NaN if the estimate exceeds \(2m\) for an \(m\)-dimensional embedding: a set with a scaling region below \(\epsilon_{up}\) has a dimension of at most \(m\), and finite-sample and finite-scale effects keep estimates for sets with a scaling region well below \(2m\). Larger values arise when the correlation sum rises much faster than \(r^m\) below \(\epsilon_{up}\), as when the pairs outside the Theiler window are all far apart (a Theiler window that is a large fraction of a nonstationary series), so there is no scaling region at that scale.

  • The output is NaN if c0 times the number of pairs that are not repeated points is below 33, the smallest number of pairs for which the 95% sampling interval of the estimate (for independent pairs) spans less than a factor of two.

  • The pairs are (i, j) with i among the first nref delay vectors and j > i + past.

References

Parameters:
y : array-like

Input time series.

nref : int, optional

The number of reference points (the first nref delay vectors); -1 uses all points. Default is -1.

c0 : float, optional

The fraction of pairs (other than repeated points) that lie below the upper length scale. Default is 0.01.

past=('ac', 1)

The Theiler window (see pyhctsa.utils.theiler_window()): ['ac', k] for k times the first zero-crossing of the autocorrelation function, or a number of samples. Default is ['ac', 1].

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:

The estimate of the correlation dimension. NaN if the delay or Theiler window cannot be set, the series cannot be embedded or is constant, c0 times the number of pairs that are not repeated points is below 33, fewer than 3 distinct distances lie below the upper length scale, or the estimate exceeds twice the embedding dimension (see Details).

Return type:

float