pyhctsa.operations.surrogates.surrogates

pyhctsa.operations.surrogates.surrogates(y, tau=1, nsurr=50, surr_method=1, surrfn='tc3', random_seed=0)

Surrogate data test of a nonlinear statistic, tc3 or trev (hctsa’s SD_Surrogates).

Generates surrogate time series and tests them against the original time series according to a test statistic: T_{C3} (tc3()) or T_{rev} (trev()), both reimplementations of the expressions originally used by the TSTOOL package’s tc3/trev functions. The statistic is computed on the series and on each surrogate, and the outputs describe where the series’ value lies in the distribution of the surrogates’ values (a Gaussian fit to them, their median and interquartile range, and a kernel-smoothed density).

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

Parameters:
y : array-like

The input time series.

tau : int or str, optional

The time lag used in the test statistic: an integer, or a string that sets it from the series: ‘ac’ for the first zero-crossing of the autocorrelation function, ‘ac1e’ for the floor of its first 1/e crossing, or ‘mi’ for the smaller of the first minimum of the Kraskov automutual information and the ‘ac1e’ delay (see utils.get_tau). The delay is set once, from the original series, and used for the series and all its surrogates. For ‘tc3’ the statistic is <x_n x_{n-tau} x_{n-2tau}> / |<x_n x_{n-tau}>|^(3/2); for ‘trev’ it is <d^3> / <d^2>^(3/2) for the increments d = x_{n+tau} - x_n. Default is 1.

nsurr : int, optional

The number of surrogates to generate. Default is 50.

surr_method : int, optional

The method of generating surrogates: 1 randomizes the phases of the Fourier spectrum (‘RP’), 2 is Theiler’s algorithm II (‘AAFT’), 3 permutes the samples randomly (‘RandPerm’). Default is 1.

surrfn : {'tc3', 'trev'}, optional

The statistic to evaluate on all surrogates. Default is 'tc3'.

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.

Returns:

With s the value of the statistic on the series, and the surrogates’ values having mean muhat, standard deviation sigmahat, median and interquartile range iqrsurr:

  • 'meansurr', 'stdsurr': the mean and standard deviation of the statistic over the surrogates.

  • 'meannumsurr': the mean over the surrogates of the statistic’s numerator (<x_n x_{n-tau} x_{n-2tau}> for ‘tc3’, <d^3> for ‘trev’). Unlike meansurr it has no denominator, so it is not dominated by the few surrogates whose denominator is near zero. It is the mean third-order moment of the null ensemble: for AAFT surrogates (surr_method=2) it measures how much <x_n x_{n-tau} x_{n-2tau}> a static monotone transform of a linear Gaussian process with this series’ distribution and autocorrelation produces. For ‘trev’ and for random-phase surrogates its expectation is near zero for every series (the null processes are time-reversible, and random phases cancel third-order moments of a zero-mean series); for permuted surrogates it depends only on the series’ distribution.

  • 'normpatponmax': the Gaussian density N(muhat, sigmahat) at s relative to its peak value.

  • 'stdfrommean': |s - muhat| / sigmahat.

  • 'zsigned': (s - muhat) / sigmahat, the z-score of the series’ statistic against the surrogates keeping its sign (whether the series has more or less of the statistic than the null ensemble); NaN if sigmahat is at the rounding level of the surrogates’ values (sigmahat <= 1e-10 * max|value|).

  • 'ztestp': the p-value of a z-test of s against N(muhat, sigmahat).

  • 'iqrsfrommedian': |s - median| / iqrsurr (NaN if iqrsurr is 0).

  • 'kspminfromext': the smaller of the kernel-density probabilities of a value below and above s (0 if s lies above the density grid).

  • 'ksphereonmax': the kernel density at s relative to the peak of N(muhat, sigmahat) (0 if s lies above the density grid).

  • 'ksiqrsfrommode': |s - (mode of the kernel density)| / iqrsurr (NaN if iqrsurr is 0).

normpatponmax, stdfrommean, ztestp, kspminfromext and ksphereonmax are NaN if the surrogates all have the same value (the kernel density uses bf_ks_density()). The output is NaN if tau cannot be determined or the statistic fails for any surrogate.

Return type:

dict or float