pyhctsa.operations.correlation.add_noise

pyhctsa.operations.correlation.add_noise(y, tau=1, ami_method='even', extra_param=None, random_seed=None, num_draws=10)

Changes in the automutual information with the addition of noise.

Adds independent Gaussian noise of standard deviation eta to the (z-scored) time series, for 50 noise levels evenly spaced from eta = 0 to eta = 3, and measures the automutual information (AMI) at lag tau at each level, averaged over num_draws independent noise draws per level (so that the curve reflects the series rather than one particular noise realization). Can be measured using histograms with extra_param bins, or Kraskov estimators with k = extra_param. The output is a set of statistics on the resulting set of automutual information estimates, including a fit to an exponential decay, since the automutual information decreases with the added white noise. This algorithm is quite different, but was based on the idea in [1].

The noise comes from bf_random() (seed random_seed + i + 1 at noise level i, counting from 0), so it is the same as in hctsa’s CO_AddNoise, in every release and platform, and leaves NumPy’s global random state untouched.

The exponential a * exp(b * eta) is fitted in closed form: least squares of log(AMI) on eta weighted by AMI**2, which approximates a least-squares fit of the AMI itself (errors in log(AMI) scale as 1/AMI). Levels with AMI <= 0 (possible for the Kraskov estimator) have no logarithm and zero weight. If fewer than two levels have a positive AMI (or the AMI curve is constant) there is nothing to fit, and the fit outputs are NaN.

References

Parameters:
y : array-like

Input time series (should be z-scored prior to analysis).

tau : int or str, optional

Time delay used to compute AMI.

  • If an int, computes AMI at that lag.

  • If "ac" or "tau", uses the first zero-crossing of the autocorrelation function.

  • If "ac1e", the floor of the first 1/e crossing of the autocorrelation function.

  • If "mi", the smaller of the first minimum of the Kraskov automutual information and the "ac1e" delay (see get_tau()).

Default is 1. A delay that cannot be set from the series gives NaN.

ami_method : str, optional

Estimation method for AMI.

Histogram-based estimators:

  • "std1"

  • "std2"

  • "quantiles"

  • "even"

Alternative estimators:

  • "gaussian"

  • "kraskov1"

  • "kraskov2"

Default is "even".

extra_param : int, optional

Additional parameter for the AMI estimator.

  • For histogram methods: number of bins (default 10).

  • For the Kraskov methods: the number of nearest neighbors (default 4).

random_seed : int or None, optional

Seed of the noise (a number, passed to bf_random(); at noise level i, counting from 0, the seed is random_seed + i + 1). None (or a string such as 'default') is 0.

num_draws : int, optional

Number of independent noise vectors averaged at each noise level (default 10). The draws at a level are consecutive blocks of len(y) values of one stream, so fewer draws are cheaper but make the curve noisier. hctsa’s Kraskov settings use 5.

Returns:

Summary statistics of the AMI-noise curve, including exponential decay fit parameters and descriptive measures.

Return type:

dict