pyhctsa.operations.surrogates.surrogate_test

pyhctsa.operations.surrogates.surrogate_test(x, surr_meth='RP', num_surrs=99, the_test_stat='amikraskov1', random_seed=0, extrap=None)

Analyzes test statistics obtained from surrogate time series.

This function is based on [1].

The generation of surrogates is done by the periphery function, _make_surrogates.

References

Parameters:
x : array-like

The input time series.

surr_meth : str, optional

The method for generating surrogate time series:

  • ’RP’: random phase surrogates that maintain linear correlations in

    the data but destroy any nonlinear structure through phase randomization.

  • ’AAFT’: amplitude-adjusted Fourier transform method maintains

    linear correlations but destroys nonlinear structure through phase randomization, yet preserves the approximate amplitude distribution.

  • ’TFT’: preserves low-frequency phases but randomizes high-frequency phases

    (as a way of dealing with non-stationarity, cf. [2] “A new surrogate data method for nonstationary time series”, D. L. Guarin Lopez et al., arXiv 1008.1804 (2010)); the cut-off frequency is extrap.

  • ’RandPerm’: random permutations of the samples (destroying all temporal structure).

Default is 'RP'.

num_surrs : int, optional

The number of surrogates to compute. Default is 99 for a 0.01 significance level 1-sided test.

the_test_stat : str or array-like, optional

The test statistic(s) to evaluate on all surrogates and the original time series. A single name or a list of names; output is returned for each statistic:

  • ’amikraskov1’: the automutual information at lag 1, estimated with the Kraskov

    nearest-neighbor estimator (automutual_info(y, 1, 'kraskov1', 4)); tested one-sided (surrogates should have lower values), cf. [2].

  • ’amikraskovmi’: as ‘amikraskov1’, but at the delay get_tau(x, 'mi') of the

    original series, used for the series and every surrogate; it also detects nonlinear dependence that builds up over several steps (e.g., in oversampled flows). That delay is at most the autocorrelation’s 1/e time, which the surrogates share, so choosing it does not favor the series (a lag at the series’ own first AMI minimum would). One-sided.

  • ’fmmikraskov’: the first minimum of the Kraskov automutual information function

    (first_min(y, 'mi-kraskov1')); tested one-sided.

  • ’o3’: a third-order statistic used in [3] (the mean cubed increment at lag 1);

    tested two-sided.

  • ’tc3’: a time-reversal asymmetry measure (tc3 at lag 1); tested two-sided.

  • ’amigaussian1’ and ‘fmmigaussian’: as ‘amikraskov1’ and ‘fmmikraskov’ but with

    the Gaussian estimate of the automutual information. That is a function of the autocorrelation only, which random-phase surrogates preserve, so these tests cannot detect anything (their p-values are close to uniform for every series); hctsa does not register them. The earlier names ‘ami1’ and ‘fmmi’ (which both meant the Gaussian estimate) are accepted as ‘amigaussian1’ and ‘fmmigaussian’ with a deprecation warning.

  • ’nlpe’: the mean squared error of the locally constant nonlinear prediction

    (pyhctsa.operations.nonlinearity.nlpe(), embedding dimension 3, delay 1, Theiler window of one autocorrelation time), for the series and each surrogate; tested one-sided (nonlinear structure makes the series more predictable: its error should be lower than the surrogates’). Slow.

  • ’fnn’: the fraction of false nearest neighbors at embedding dimension 2

    (pyhctsa.operations.nonlinearity.fnn(), delay 1, escape factor 5); tested one-sided.

Default is 'amikraskov1'. Outputs for each statistic s (amikraskov, amikraskovmi, fmmikraskov, amigaussian, fmmigaussian, o3, tc3, nlpe, fnn) are s_zscore (the z-statistic of the series’ value against the Gaussian fitted to the surrogates’ values; NaN if all surrogates have the same value), s_mediqr (distance from the surrogates’ median in interquartile ranges; NaN if the interquartile range is 0) and s_prank (rank-based p-value (k + 1) / (num_surrs + 1), with k the number of surrogates at least as extreme as the series in the tested direction; doubled and capped at 1 for two-sided tests). As in hctsa, no Gaussian p-value or kernel density (s_p, s_f) is returned.

random_seed : int, str or None, optional

The seed of the surrogates (see _make_surrogates(); 'default' is 0, as in hctsa’s registered calls). Default is 0.

extrap : float, optional

The cut-off frequency for ‘TFT’ surrogates (see _make_surrogates).

Returns:

Dictionary of statistics comparing the original time series to its surrogates for each test statistic. NaN if a statistic cannot be computed on every surrogate (hctsa raises an error, which its operation wrapper turns into NaN).

Return type:

dict or float