pyhctsa.operations.nonlinearity.local_density¶

pyhctsa.operations.nonlinearity.local_density(y, nnr=3, past=('ac', 1), tau='ac', m=2)¶

How densely the delay-embedded trajectory is sampled around each of its points, and how that density changes along the orbit.

Computes a k-nearest-neighbor estimate of the local probability density at each point of the time-delay embedding: density(i) = (k/Neff) / (V_m * r_k(i)^m), where r_k(i) is the distance from point i to its k-th (k = nnr) nearest neighbor (excluding temporally-close points within a Theiler window of past samples), m is the embedding dimension, V_m = pi^(m/2) / Gamma(m/2 + 1) is the volume of the unit m-ball, and Neff = N_embed - 2*past - 1 is the number of points that can be neighbors. The estimate is computed in units of the series’ standard deviation, and its logarithm is analyzed:

log density(i) = log(k/Neff) - log(V_m) - m*log(r_k(i)/std(y)),

which makes the outputs independent of the units of y and, for a stationary process, of the number of points. Working with the log density keeps the statistics well behaved (the density itself is heavy-tailed). To avoid infinite densities when there are repeated values (zero neighbor distance, as in quantized or held series), distances are smoothed as sqrt(r^2 + (0.01*median(r[r > 0]))^2).

Parameters:¶

y : array-like¶

Input time series.

nnr : int, optional¶

Number of nearest neighbors to compute. Default is 3.

past=('ac', 1)¶

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

tau : str or int, optional¶

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

m : int or 'fnn', optional¶

The embedding dimension: an integer, or 'fnn' (or ['fnn', threshold]) to set it by TISEAN’s false nearest neighbors (fnn(), threshold 0.05 by default, at most floor(2 log10 N); as hctsa’s BF_Embed, see _embedding_params()). Default is 2.

Returns:¶

Statistics on the log local density series (output names retain ‘den’), in the time order of the embedded points: the minimum, maximum, interquartile range, range, standard deviation, mean and median (minden … medianden), the autocorrelation at lags 1 to 5 (ac1den … ac5den), and the correlation lengths of the density sequence, tauacden (first zero-crossing of the autocorrelation function) and taumigaussden (first minimum of the Gaussian automutual information function, a monotonic function of the autocorrelation). Returns NaN if the Theiler window or delay cannot be set, the series is too short, or all neighbor distances are zero.

Return type:¶

dict