pyhctsa.operations.graph.visibility_graph

pyhctsa.operations.graph.visibility_graph(y, meth='horiz', max_l=20000)

Visibility graph analysis of a time series.

Constructs a visibility graph of the time series, with one node per sample, and returns statistics on the distribution of the number of links per node (the degree). In the natural visibility graph ('norm'), two samples are linked if the straight line between them passes above every sample in between. In the horizontal visibility graph ('horiz'), they are linked if a horizontal line between them passes above every sample in between. The outputs summarize the degrees (mode, mean, spread, extremes, heaviness of the upper tail), the entropy of their histogram, fits of Gaussian, exponential and power-law curves to that histogram and of an extreme-value distribution to the degrees, and the autocorrelation of the sequence of degrees taken in time order. cf. [1] and [2].

Follows hctsa’s NW_VisibilityGraph, which builds on visibility-graph code by Enyu Zhuang (after Lacasa et al. [1] and Luque et al. [2]); the degree computations here are written for pyhctsa.

References

Parameters:
y : array-like

Input time series

meth : str, optional

Method for constructing the visibility graph:

  • ’horiz’: Uses horizontal visibility (only horizontal lines link nodes)

  • ’norm’: Uses natural visibility (standard visibility definition)

Default is 'horiz'.

max_l : int or str, optional

Maximum number of samples to analyze. Longer time series are truncated to first max_l points. Set to 'full' to analyze the entire time series with no cropping (a warning is logged if the series exceeds 50000 samples and meth is 'norm', since the natural visibility graph may be slow). Only the degrees are computed, with no adjacency matrix stored, so memory is not a concern. Default is 20000.

Returns:

Statistics on the degree distribution:

  • modek, propmode: the most common degree, and the proportion of nodes that have it

  • meank, mediank, stdk: mean, median and standard deviation of the degrees

  • maxk, mink, rangek, iqrk: maximum, minimum, range and interquartile range of the degrees

  • skewnessk: skewness of the degrees

  • maxonmedian: maximum degree divided by the median degree

  • ol90: mean of the degrees between the 5th and 95th percentiles, divided by the mean of all degrees

  • olu90: how far the mean of the top 5% of degrees lies above the overall mean, in standard deviations of the degrees

  • dgaussk_*, dexpk_*, dpowerk_* (r2, adjr2, rmse, resAC1, resAC2, resrunsz): goodness of fit, autocorrelation of the residuals at lags 1 and 2, and the signed z-statistic of a runs test on the residuals (pyhctsa.robust.bf_runs_z()), for a single Gaussian, exponential and power law fitted by deterministic least squares (pyhctsa.robust.bf_fit_density_curve()) to the distribution of degrees (the proportion of nodes at each integer degree, from the minimum to the maximum degree; the rmse is in units of probability density of the degrees divided by their standard deviation, so it does not depend on the number of nodes). Each is NaN if the degrees take no more distinct values than the fit has parameters (3 for the Gaussian, 2 for the others); the three residual statistics are also NaN if the residuals have no variation beyond floating-point round-off, as for an exact fit (pyhctsa.robust.bf_residual_stats())

  • gaussnlogL, expnlogL: mean negative log-likelihood per node of a Gaussian and of an exponential distribution fitted to the degrees

  • evparam1, evparam2, evnlogL: location and scale of an extreme-value distribution fitted to the degrees, and its mean negative log-likelihood per node

  • entropy: entropy of the histogram of degrees (square-root bin rule with explicit edges), in nats

  • kac1, kac2, kac3: autocorrelation of the degree sequence (in time order) at lags 1, 2 and 3

  • ktau: lag at which the autocorrelation of the degree sequence first crosses zero (interpolated)

Return type:

dict