pyhctsa.operations.correlation.time_rev_kld¶

pyhctsa.operations.correlation.time_rev_kld(y, tau='ac', m=2, k=3, theiler_win=('ac', 1), max_n='full')¶

Kullback-Leibler divergence between forward and time-reversed embeddings.

Embeds the time series in m dimensions at time delay tau (e.g., the pair (x_t,x_{t+tau}) for m=2, or the triple (x_t,x_{t+tau},x_{t+2tau}) for m=3), and estimates the Kullback-Leibler divergence between the distribution of these embedded points and the distribution of the same points with their coordinate order reversed (equivalent to embedding the time-reversed series). For a (statistically) time-reversible process, these two distributions coincide and the divergence is zero in the population; departures reflect time-irreversibility.

References

Parameters:¶

y : array-like¶

The input time series.

tau : int or str, optional¶

The time delay for the embedding: an integer number of samples, or a rule (see get_tau()): 'ac' (first zero crossing of the autocorrelation function), 'ac1e' (floor of its first 1/e crossing) or 'mi' (the smaller of the first minimum of the Kraskov automutual information and the 'ac1e' delay). Default: 'ac'.

m : int, optional¶

The embedding dimension. Default: 2, for the pairwise joint distribution (x_t,x_{t+tau}); set to 3 for the triple-wise joint distribution (x_t,x_{t+tau},x_{t+2tau}).

k : int, optional¶

The number of nearest neighbors used by the k-NN divergence estimator. Default: 3 (matches local_density’s default).

theiler_win : int, float, list or tuple, optional¶

The Theiler window: the number of temporally-adjacent points excluded from both the within-set and cross-set neighbor searches (|i-j| <= theiler_win), applied at matching time indices in both the forward and reversed embeddings. Either ['ac', c] for c times the first zero crossing of the autocorrelation function (or ['ac1e', c] for its 1/e time), a number of samples, or a number in (0, 1) for a proportion of the series length (see theiler_window()). Default: ('ac', 1). Narrowed to fit short series.

max_n : int or str, optional¶

The maximum number of embedded points used. Default: ‘full’ (no cropping); set to an integer to cap runtime on unusually long series.

Returns:¶

The raw k-NN estimate of KL(forward || reversed) and its magnitude. A unitless departure-from-reversibility measure, zero up to estimation noise for a reversible process (the k-NN estimator can dip slightly negative near a true value of zero – expected behavior of this nonparametric estimator, not a bug), with no attached significance level (see note above). NaN if the delay or the Theiler window cannot be set, the embedding fails, or there are too few embedded points (fewer than max(50, 10*k)).

Return type:¶

dict