pyhctsa.operations.nonlinearity.rqa

pyhctsa.operations.nonlinearity.rqa(y, tau=1, m=3, theiler_win=('ac', 1), rr=0.1, lmin=2, vmin=2, max_n=10000, random_seed='default')

Recurrence quantification analysis (RQA) of the delay-embedded series.

Embeds the time series in an m-dimensional delay space and computes standard recurrence quantification measures from the resulting recurrence plot [1]: recurrence rate, determinism, laminarity, trapping time, and related diagonal and vertical line-length statistics. Two embedded states are recurrent if they lie within a radius of each other; the radius is set to give a target recurrence rate rr. Pairs closer in time than the Theiler window are excluded.

Neighbors are found with a KD-tree rather than by forming the full N x N distance matrix, and the line-length statistics are computed directly from the list of recurrent pairs. The number of recurrent pairs is itself about rr * N**2, so run time grows roughly quadratically with N at fixed rr (hence the max_n cap).

References

Parameters:
y : array-like

The input time series.

tau : int or str, optional

The time delay for the embedding: an integer, or a rule understood by pyhctsa.utils.get_tau() ('ac', 'ac1e' or 'mi'). Default is 1.

m : int, str or tuple, optional

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

theiler_win=('ac', 1)

The Theiler window excluding temporally-correlated neighbors from the main diagonal (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].

rr : float, optional

The target recurrence rate used to set the neighborhood radius: the radius is the rr-quantile of a subsample of pairwise distances in the embedded space (standard RQA practice, to fix the recurrence rate for comparability across series). Default is 0.1.

lmin : int, optional

The minimum diagonal line length counted toward determinism and the line-length entropy. Default is 2.

vmin : int, optional

The minimum vertical line length counted toward laminarity and trapping time. Default is 2.

max_n : int or 'full', optional

The maximum number of samples to consider: longer series are reduced to their first max_n points, since the number of recurrent pairs grows as rr * N**2. 'full' disables cropping (a warning is logged above N = 20000). Default is 10000.

random_seed : int, str or None, optional

Not used: the radius is set from all the embedded points (above 2000, from 2000 spread evenly over the series), so nothing is random. Kept so that existing calls still work.

Returns:

NaN if the embedding or Theiler window cannot be determined, the series is too short (fewer than 50 embedded points, or no more than four Theiler windows), the radius is degenerate, or no points recur outside the Theiler window. Otherwise:

  • RR: recurrence rate, the proportion of pairs outside the Theiler window that are recurrent

  • DET: determinism, the proportion of recurrent points on diagonal lines of length at least lmin

  • L_mean, L_max: mean and maximum diagonal line length (lines of length at least lmin)

  • L_entr: Shannon entropy (nats) of the distribution of diagonal line lengths

  • DIV: divergence, 1 / L_max

  • LAM: laminarity, the proportion of recurrent points on vertical lines of length at least vmin

  • TT: trapping time, the mean vertical line length (lines of length at least vmin)

  • V_max: the maximum vertical line length

If there are no diagonal lines, DET = 0, L_mean = NaN, L_max = 0, L_entr = 0 and DIV = inf; if there are no vertical lines, LAM = 0, TT = NaN and V_max = 0.

Return type:

dict or float