pyhctsa.operations.correlation.time_rev_kld¶

pyhctsa.operations.correlation.time_rev_kld(y, tau='ac', m=2, k=3, theiler_win=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 (can be ‘ac’ or ‘mi’, or an integer). 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, optional¶

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. Default: 1.

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).

Return type:¶

dict