pyhctsa.operations.nonlinearity.fractal_dimensions¶

pyhctsa.operations.nonlinearity.fractal_dimensions(y, kmin=3, kmax=10, nref=0.2, gstart=1, gend=10, past=('ac', 1), steps=32, embed_params=('ac', 'fnn'), random_seed=0)¶

The spectrum of generalized (fractal) dimensions of the delay embedding, estimated from nearest-neighbor distances.

Estimates \(D(q)\), the generalized dimension of the time-delay embedding as a function of the order of the moment, from the distances of reference points to their nearest neighbors, by the method of van de Water and Schram [1] (that of TSTOOL’s fracdims). For each of nref reference points, the distances to its 1st to kmax-th nearest neighbors are found (excluding a Theiler window of past samples). For each moment order \(\gamma\) swept linearly from gstart to gend (steps values), the \(\gamma\)-th moment of the k-th-neighbor distance across all reference points is

\[M(k) = \langle r_k^\gamma \rangle^{1/\gamma}\]

(or \(\exp\langle \ln r_k \rangle\) as \(\gamma \to 0\)), for \(k = 1..k_{max}\). Under an assumed dimension \(D\) the expected relation is \(M(k) \propto (\Gamma(k + \gamma/D)/\Gamma(k))^{1/\gamma}\) (or \(\exp(\psi(k)/D)\) as \(\gamma \to 0\)), up to an overall scale factor that is fitted separately. \(D(\gamma)\) is the value that best matches the measured moments \(M(k_{min}..k_{max})\) under a robust \(\log(1 + e^2/2)\) error, found by nested bounded one-dimensional minimizations. The error has a fixed width (1) in the units of the moments, so \(D(\gamma)\) depends on the scale of the series. Finally \(q(\gamma) = 1 - \gamma / D(\gamma)\). The outputs summarize \(D\) and \(q\) across the moments, and a straight-line fit of \(D\) against \(q\).

\(D(\gamma)\) is identified only where the error has a minimum inside the search interval for \(D\), and the moments are not zero: a minimum at either end of the interval (for instance at the upper end when the moments do not grow with k, as on a periodic orbit) is no estimate, nor is a fit to moments that are zero (to within 1e-12 of the range of y; every kth neighbor coincides with its reference point, so the error is flat in \(D\)), and the outputs are then NaN.

Method as implemented in the TSTOOL package for nonlinear time-series analysis (C. Merkwirth, U. Parlitz, I. Wedekind, D. Engster and W. Lauterborn; GNU GPL), here re-implemented through hctsa’s NL_FractalDimensions.

References

Parameters:¶

y : array-like¶

Input time series.

kmin : int, optional¶

Minimum number of neighbors for each reference point. Default is 3.

kmax : int, optional¶

Maximum number of neighbors for each reference point. Default is 10.

nref : int or float, optional¶

Number of reference points, spread evenly over the embedded series (a deterministic subset): -1 uses all points, a value in (0, 1) is a proportion of the embedded points. Default is 0.2.

gstart : float, optional¶

Starting and ending values of the moment order. Defaults are 1 and 10.

gend : float, optional¶

Starting and ending values of the moment order. Defaults are 1 and 10.

past=('ac', 1)¶

The Theiler window of samples to exclude before and after each reference index (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].

steps : int, optional¶

Number of moments to calculate. Default is 32.

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'].

random_seed : int, str or None, optional¶

Not used: the reference points (when nref != -1) are the first of a fixed, evenly spread ordering (bf_spread_perm()), as in hctsa.

Returns:¶

rangeDq, maxDq, meanDq: range, maximum and mean of \(D\) across the moments; maxq, rangeq, meanq: maximum, range and mean of \(q\); linfit_a, linfit_b: slope and intercept of a linear fit of \(D\) against \(q\); linfit_rmsqres: root-mean-square residual of that fit. Returns NaN if the Theiler window or delay cannot be set, the embedding fails, kmax is not smaller than the number of embedded points, too few neighbors lie outside the Theiler window, or \(D\) is not identified at every moment order.

Return type:¶

dict or float