pyhctsa.operations.correlation.nonlinear_autocorr

pyhctsa.operations.correlation.nonlinear_autocorr(y, taus, absval=None, tau=1)

Compute a custom nonlinear autocorrelation of a time series.

Nonlinear autocorrelations generalize the usual (two-point) autocorrelation to higher-order products evaluated at multiple lags. In general,

\[\left\langle \prod_{k=0}^{m} x_{i-\tau_k} \right\rangle,\]

where \(\langle \cdot \rangle\) denotes the time average. The usual two-point autocorrelation is recovered when \(m=1\) with \(\tau_0 = 0\) and \(\tau_1 = \tau\):

\[\langle x_i\, x_{i-\tau} \rangle.\]
Parameters:
y : array-like

The z-scored input time series.

taus : array-like of int

Vector of time delays (lags) \(\{\tau_k\}\) defining the product.

Examples:

  • [2] computes \(\langle x_i\, x_{i-2} \rangle\).

  • [1, 2] computes \(\langle x_i\, x_{i-1}\, x_{i-2} \rangle\).

  • [1, 1, 3] computes \(\langle x_i\, x_{i-1}^2\, x_{i-3} \rangle\).

  • [0, 0, 1] computes \(\langle x_i^3\, x_{i-1} \rangle\).

absval : bool or None, optional

Whether to apply an absolute value before the final mean.

  • If True, takes the absolute value before averaging (often useful when

    the product has an odd number of factors, i.e. when len(taus) is even).

  • If None, sets absval=True when len(taus) is even and

    absval=False when len(taus) is odd.

Default is None.

tau : int or str, optional

The unit of the lags, in samples: an integer, or a rule for get_tau() (e.g. 'ac1e'). The product is taken at lags tau * taus over every time point, which is the average over all tau phases of the series sampled every tau samples. Default 1. NaN when a rule cannot set the delay.

Returns:

The computed nonlinear autocorrelation (NaN if the series is not longer than the largest lag).

Return type:

float

Notes

A nonzero value does not by itself indicate nonlinear dependence. For a Gaussian (linear) process, the mean of a product of an even number of factors is a sum of products of the autocorrelations at the lags involved (Isserlis’ theorem); only the difference from that value is nonlinear. With absval=True and iid data, the value is a moment of the value distribution alone. The variants nonlinear_autocorr_excess() (the difference from the Gaussian value) and nonlinear_autocorr_abs_surrogate_ratio() (absval=True, relative to phase-randomised surrogates) target the nonlinear part.