pyhctsa.operations.nonlinearity.return_time

pyhctsa.operations.nonlinearity.return_time(y, nnr=0.01, num_lags=100, past=('ac', 1), nref=-1, embed_params=('ac', 'fnn'))

Analysis of the histogram of return times.

Return times are the times taken for the time series to return to a similar location in phase space from a given reference point. Strong peaks in the histogram indicate periodicities in the data.

For each reference point in the embedding space, its nnr nearest neighbors are found (excluding a Theiler window of past samples either side), and the time offset T of each neighbor from the reference point is recorded. The histogram of these offsets over the num_lags lags beyond the Theiler window, T = past + 1, ..., past + num_lags (the “return-time profile”), is analyzed. This follows TSTOOL’s return_time, with one change: each lag’s count is divided by its expected count if neighbors were placed at random among the valid (Theiler-excluded) candidates, rather than by TSTOOL’s 2 * nnr * (N - T), so that the profile is about 1 at every lag for an uncorrelated process at any series length (TSTOOL’s normalization scaled as 1/N). Values above 1 mark lags at which the trajectory preferentially returns to its neighborhood. The profile is closely related to the tau-recurrence rate of recurrence quantification analysis, with neighborhoods holding a fixed proportion of points rather than having a fixed radius. (For the distribution of first return times to a neighborhood, see recurrence_times().)

The neighborhood of a reference point is the ball out to its nnr-th nearest neighbor, boundary included, with distances that differ by at most 1e-12 of the range of y treated as equal: so the neighborhood, and the profile, do not depend on rounding or on the order in which neighbors are found. With exactly repeated delay vectors (quantized data, periodic orbits) a neighborhood can hold more than nnr points, and the expected count uses the number it holds.

Method as implemented in the TSTOOL package for nonlinear time-series analysis (C. Merkwirth, U. Parlitz, I. Wedekind, D. Engster and W. Lauterborn; GNU GPL), here re-implemented through hctsa’s NL_ReturnTime.

References

Parameters:
y : array-like

The input time series.

nnr : int or float, optional

The number of nearest neighbors, or, if in (0, 1), a proportion of the number of embedded points (keeping neighborhoods the same size in probability as the series length changes). Default is 0.01.

num_lags : int, optional

The number of lags beyond the Theiler window to analyze, in samples (at least 2). Default is 100.

past=('ac', 1)

The Theiler window, excluding neighbors that are close only because they are close in time (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].

nref : int, optional

The number of reference points, spaced evenly through the series (-1 uses all points). A fixed number keeps the number of neighbors counted at each lag, and so the sampling noise of the histogram, independent of the series length (neighbors are still sought among all points). Default is -1.

embed_params : list or tuple, optional

The embedding, as (tau, m): the time delay (an integer or a rule understood by pyhctsa.utils.get_tau()) and the embedding dimension (an integer, or 'fnn' for false nearest neighbors). Default is ('ac', 'fnn').

Returns:

NaN if the Theiler window or embedding cannot be determined, or the series is too short (fewer embedded points than twice the largest lag, or than nnr plus two Theiler windows). Otherwise measures of the return-time profile (the neighbor count at each lag relative to chance), and of the histogram of its values:

  • max, std, iqr: the maximum, standard deviation and interquartile range of the profile

  • pzeros: the proportion of lags with no neighbors

  • pg05: the proportion of lags at which the profile exceeds half its maximum

  • meanpeaksep, maxpeaksep, minpeaksep, rangepeaksep, stdpeaksep: statistics of the intervals between successive crossings of half the maximum (which are alternately the widths of peaks and the gaps between them, those shorter than 0.4 of the longest interval being dropped), as a proportion of the number of lags (stdpeaksep is divided by the square root of the number of lags instead); all are NaN with fewer than 3 crossings

  • fracsdrt, fracmeanrt: the share of the first half of the lags in the standard deviation (fracsdrt) or mean (fracmeanrt) of the profile, a / (a + b) with a and b the statistic over the first and second halves. This lies in [0, 1]: 0.5 when the halves match and 1 when all the variation (or mass) is at short lags; NaN if both halves are constant (or empty)

  • hhist: the entropy of the profile as a distribution over lags

  • hcgdist, rangecgdist, pzeroscgdist: the entropy, range and proportion of zeros of the profile after summing it into 20 equal bins of lags (as a distribution over bins)

  • maxhisthist, phisthistmin, hhisthist: the maximum, the first (lowest-value) bin probability, and the entropy of the histogram of profile values (ceil(sqrt(n)) equal-width bins, explicit edges)

Return type:

dict or float