pyhctsa.operations.nonlinearity.recurrence_times¶

pyhctsa.operations.nonlinearity.recurrence_times(y, tau=1, m=3, theiler_win=('ac', 1), rr=0.1, num_segments=4, max_n=10000, random_seed='default')¶

Recurrence-time statistics from a recurrence plot.

Embeds the series in a time-delay space and finds, for each embedded point, the times at which the trajectory returns to its neighborhood: the lengths of the white vertical lines of the recurrence plot (the numbers of non-recurrent points between successive recurrent points), cf. [1]. This is the distribution of the times between recurrences to a given neighborhood, rather than the black line-length statistics of rqa(). Quasi-periodic dynamics on a torus return at a few distinct times, so the distribution of recurrence times has a few sharp peaks, whereas strange nonchaotic attractors have a more broadly distributed (and segment-to-segment more variable) set of recurrence times.

The neighborhood radius is set once, from the full embedded series, to the rr-quantile of a subsample of pairwise distances; the same radius is then reused for every segment, so that segment-to-segment differences reflect the dynamics rather than a re-calibrated threshold. The Theiler band around each point counts as recurrent, so that no white line spans the excluded band.

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 (see pyhctsa.utils.theiler_window()): ['ac', k] for k times the first zero-crossing of the autocorrelation function, or a number of samples. Narrowed to Nemb // 5 for short series. Default is ['ac', 1].

rr : float, optional¶

The target recurrence rate used to set the neighborhood radius. Default is 0.1.

num_segments : int, optional¶

The embedded trajectory is divided into this many contiguous, non-overlapping segments, and the mean recurrence time and modal probability are recomputed independently within each; their variance across segments is the paper’s diagnostic for the torus-to-SNA transition. Each segment needs at least 50 embedded points, otherwise the variance outputs (but not the full-series T_MRT/N_MPRT) are NaN. Default is 4.

max_n : int or 'full', optional¶

The maximum number of samples to consider (the first max_n); 'full' to disable cropping. 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, or the embedded series is too short (under 50 points) or degenerate (zero radius). Otherwise:

• T_MRT: the mean recurrence time of the full series (the mean white-line length)

• N_MPRT: the modal recurrence-time probability mass of the full series: the fraction of all recurrence-time samples taking the single most common value (the paper’s raw count, normalized so that it does not scale with series length)

• T_MRT_var, N_MPRT_var: the variance of T_MRT and of N_MPRT across the num_segments segments

Return type:¶

dict or float