pyhctsa.operations.nonlinearity.persistent_homology¶

pyhctsa.operations.nonlinearity.persistent_homology(y, tau='mi', m=3, max_dim=1, max_n=1000)¶

Persistent homology of the delay embedding: the lifetimes of its loops and components.

Embeds the time series in m dimensions, builds the Vietoris-Rips filtration of the point cloud, and summarizes the lifetimes (death minus birth, as a proportion of the filtration threshold, the maximum distance between 300 evenly spaced embedded points) of its one-dimensional holes (loops, H1; a periodic series gives a long-lived loop) and its connected components (H0). The filtration stops at the threshold, so a class still alive there is counted as dying at the threshold (lifetime (threshold - birth)/threshold), except for the single essential H0 class (the connected component that never dies), which is dropped. Uses ripser [1] (the ripser Python package, an optional dependency; hctsa runs the ripser executable).

References

Parameters:¶

y : array-like¶

Input time series.

tau : int or str, optional¶

The embedding delay: an integer number of samples, a rule understood by pyhctsa.utils.get_tau() ('ac', 'ac1e', 'mi'), or 'periodWelch' for one fifth of the dominant period (the most prominent peak of the log Welch power spectrum, falling back to 'mi' if there is none). A fixed tau = 1 embeds a smooth periodic series nearly collinearly, which makes its loop short-lived. Default is 'mi'.

m : int, optional¶

The embedding dimension. Default is 3.

max_dim : int, optional¶

The maximum homology dimension computed (at least 1 for the H1 outputs; with 0 they are zero). Default is 1.

max_n=1000¶

The maximum number of embedded points: a longer point cloud is subsampled at evenly spaced points (the cost of ripser grows steeply with the size of the cloud), or 'full' for no subsampling. Default is 1000.

Returns:¶

maxPersistenceH1, totalPersistenceH1, persistenceEntropyH1: the maximum and sum of the (normalized) lifetimes of the H1 classes and the entropy of their distribution (all 0 if there are none); totalPersistenceH0: the sum of the lifetimes of the H0 classes other than the essential one. Returns NaN if the delay cannot be set, the embedding fails, there are fewer than 20 embedded points, or the point cloud is degenerate (e.g. a constant series).

Return type:¶

dict or float

Raises:¶

ImportError – If the ripser package is not installed.