pyhctsa.operations.nonlinearity.evt_local_dim

pyhctsa.operations.nonlinearity.evt_local_dim(y, tau='ac', m=3, q=0.98, theiler_win=('ac', 1), n_poles=200, m_order=5, max_n='full', random_seed='default')

The local dimension and persistence of the reconstructed attractor, from extreme-value statistics of close returns.

Time-delay embeds the series and, for a sample of reference points (“poles”) on the reconstructed orbit, treats close returns of the orbit to each pole as extreme events: g_i = -log(||Y_i - pole||) is large exactly when the orbit passes close to the pole. Extreme value theory applied to this observable gives two local quantities per pole:

  • a local dimension d(pole): under the Freitas-Freitas-Todd theorem [1], the Gumbel-law scale parameter of the extreme value law for g_i equals the local dimension of the attractor at that pole exactly. In practice this is estimated by a peaks-over-threshold fit [2, 3, 4]: take the exceedances of g_i above a high quantile q, and set d(pole) = 1 / mean(exceedances) (the reciprocal of the exponential maximum-likelihood scale, i.e. the generalized Pareto fit with shape fixed at its ansatz-implied value of 0, appropriate here because g_i = -log(distance) is unbounded above, putting it in the Gumbel/exponential-tail domain).

  • a persistence theta(pole) (the “extremal index” of g_i at that pole): whether close returns to the pole arrive as isolated events (theta near 1) or cluster into runs where the orbit lingers nearby (theta well below 1, i.e. long average residence time near that point of phase space; 1 / theta is the average cluster/sojourn size). Estimated with the O’Brien order-m_order estimator, which Caby et al. [5] found more reliable for this observable than the Suveges likelihood estimator [6], particularly near near-periodic (sticky) poles.

This differs from the attractor-dimension operations that pool all pairwise distances or neighbor ranks into one global scaling exponent: it estimates a genuinely local dimension and persistence separately at each of several poles and reports how they are distributed (and covary) across the attractor, capturing multifractal-style local heterogeneity that a single global exponent cannot.

Both estimates assume that the distances to a pole are continuously distributed. Distances within 1e-12 of the range of y of each other are therefore equal (they are merged, so the exceedances do not depend on rounding), an embedded point within that distance of the pole is the same state visited again rather than a close return, and a pole whose exceedances take fewer than 15 distinct distances (quantized data, finite orbits) has no estimate.

References

Parameters:
y : array-like

The input time series (assumed z-scored).

tau : int or str, optional

The embedding time delay: an integer, or a rule understood by pyhctsa.utils.get_tau() ('ac': the first zero-crossing of the autocorrelation function, 'ac1e': the floor of its first 1/e crossing, 'mi': the smaller of the first minimum of the Kraskov automutual information and the 'ac1e' delay). Default is 'ac'.

m : int or str, optional

The embedding dimension (an integer, or 'fnn' for false nearest neighbors). Default is 3.

q : float, optional

The quantile level defining “extreme” close returns: exceedances of g_i above its q-quantile are treated as events (default 0.98, i.e. the closest 2% of returns to each pole).

theiler_win=('ac', 1)

The Theiler window excluding temporally-correlated neighbors of each pole from being treated as (trivially close) returns (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].

n_poles : int, optional

The number of reference points (poles) to sample from the embedded orbit (the cost is O(n_poles * Nemb)). Default is 200.

m_order : int, optional

The order of the O’Brien persistence estimator: how many steps ahead to check for a further exceedance before counting a given exceedance as “isolated” (default 5, following Caby et al.).

max_n : int or 'full', optional

The maximum number of samples to consider (the first max_n); 'full' for no cropping (a warning is logged above 50000 samples). Default is 'full'.

random_seed : int, str or None, optional

Not used: the poles are the first of a fixed, evenly spread ordering of the embedded points (bf_spread_perm()), as in hctsa. Kept so that existing calls still work.

Returns:

NaN if the embedding or Theiler window cannot be determined, or the embedded series is too short for the exceedances required. Otherwise:

  • propValidPoles: the proportion of poles that gave a valid local dimension (at least 15 exceedances, at 15 or more distinct distances; such a pole also has a valid persistence, as long as m_order is smaller than the number of returns used): a diagnostic of whether q, n_poles and the series length were adequate, not a property of the dynamics

  • meanLocalDim, stdLocalDim: mean and standard deviation of the local dimension across poles

  • meanTheta, stdTheta: mean and standard deviation of the persistence (extremal index) across poles

  • corrDimTheta: correlation across poles between the local dimension and the persistence (NaN if fewer than 10 poles are valid)

Return type:

dict or float