pyhctsa.operations.nonlinearity.dvv¶

pyhctsa.operations.nonlinearity.dvv(y, m=3, num_dvs=100, nd=2.0, ntv=None, num_surr=10, random_seed=0, tau=1)¶

How well nearby delay vectors predict their target value, compared with surrogates.

The delay vector variance (DVV) method [1] for detecting determinism and nonlinearity. A delay vector is a run of m values (spaced tau apart) and its target is the value tau samples after the last of them. For each of num_dvs randomly chosen reference vectors, the variance of the targets of all delay vectors within a distance rd of the reference is found (only if at least 30 vectors lie within rd). The mean of these variances over the references, divided by the variance of the series, is the target variance; it is computed at ntv values of rd that span the mean distance between delay vectors plus or minus nd standard deviations. The same curve is found for num_surr iterated amplitude-adjusted Fourier transform (IAAFT) surrogates, and the outputs summarize the data curve and its difference from the mean surrogate curve.

References

Notes

Adapted from hctsa’s NL_DVV, which is B. D. Fulcher’s modification of the DVV toolbox of Danilo P. Mandic (c) 2008 (GNU GPL, version 2 or later); the delay-vector-variance curve and the IAAFT surrogate are in pyhctsa.toolboxes.DVV.dvv.

The surrogates keep the best-matching of (at most) 100 IAAFT iterates, and the rank-ordering step ranks the real part of the spectrum-matched series by value. The set of delay vectors around a reference vector excludes the reference itself. The reference vectors (sampled without replacement) and the surrogate starting permutations are drawn from hctsa’s portable generator (bf_random()), one seeded block per draw (see _dvv_draws): the outputs are reproducible for a given random_seed, and different seeds give different, equally valid, random draws.

Parameters:¶

y : array-like¶

Input time series (real-valued).

m : int, optional¶

The delay embedding dimension. Default is 3.

num_dvs : int, optional¶

Number of reference delay vectors to consider. Default is 100.

nd : float, optional¶

Span over which to perform DVV, in standard deviations of the distances between delay vectors. Default is 2.

ntv : int, optional¶

Number of points on the horizontal (distance) axis. Default is 25 * nd.

num_surr : int, optional¶

Number of surrogates to compare to. Default is 10.

random_seed : int, optional¶

Seed for the random choices of reference vectors and surrogates. Default is 0.

tau : int or str, optional¶

The time delay between delay-vector elements: an integer number of samples, or a rule understood by pyhctsa.utils.get_tau() ('ac1e', 'mi', …). The same delay is used for the data and the surrogates. An adaptive delay makes the statistics much less dependent on the sampling rate. Default is 1.

Returns:¶

Statistics of the curve of target variance against standardized distance (the data curve, at the distances where it is defined): trend (slope of a linear fit), max, min, mean, meanDiff and stdDiff (mean and standard deviation of its successive differences), trendDiff (slope of a linear fit to them); and against the mean surrogate curve: rmsDiffSurr, meanDiffSurr, dataSurrCorr, trendDataSurr (slope of the surrogate curve against the data curve), numZeroCrossings (sign changes of the difference), trendSurr, meanDiffTrendSurr (trendSurr minus trend) and meanNormCDF (the mean over distances of the Gaussian cumulative probability of the data value given the mean and standard deviation across surrogates, over the distances at which the surrogate values differ; NaN if they never do). dataSurrCorr and trendDataSurr are NaN if the data curve is constant. Returns NaN if no delay can be set, the series is too short to draw num_dvs reference vectors, or the data curve is defined at fewer than two distances.

The target variance of a set is computed in two passes (mean, then mean squared deviation) [2], so it is never negative; a variance below the square of 1e-12 of the range of the series comes from targets that are equal up to rounding, and is 0.

Return type:¶

dict or float