pyhctsa.operations.nonlinearity.embed_cluster

pyhctsa.operations.nonlinearity.embed_cluster(y, tau='ac', m=2, max_n='full')

Whether the time-delay embedding of the series forms separate clusters of points.

Reconstructs the time series as a time-delay embedding (as in embed_pca()) and asks whether the resulting point cloud is made of distinct groups. A process whose trajectory visits distinct regions of phase space (e.g., alternating between two attractor states, or a system with intermittent bursts) leaves a multi-modal point cloud in the embedding; a process with a single smooth (e.g., unimodal-stochastic) attractor does not. This is a distinct signal from marginal-distribution multi-modality, since two states can overlap entirely in amplitude yet still separate cleanly once lagged coordinates are added, and from regime-switching detected by hidden Markov models, which cluster points in raw-amplitude (not lagged/embedded) space.

All statistics are computed on the whitened cloud (zero mean, identity covariance, along its principal axes, each eigenvector signed so that its largest-magnitude element is positive), so they do not depend on its scale or orientation. sep_pp, sep_mahal and valley measure the separation of a two-group split of the cloud; they are always defined, even when two groups are not favored over one, and grow with the separation of genuine clusters. nongauss measures how far the cloud is from a single Gaussian, whatever the reason.

A curved-but-unimodal manifold (e.g., the ring traced out by a periodic signal in a 2-d embedding) has a bimodal projection along any direction, and so also raises sep_pp, sep_mahal and valley, despite having no distinct dynamical states; it also raises nongauss, which measures departure from Gaussianity in general (e.g., a skewed marginal distribution also raises it), not separation specifically. No statistic involves random numbers.

Parameters:
y : array-like

The input time series.

tau : int or str, optional

The time delay of the embedding: an integer, or a rule understood by pyhctsa.utils.get_tau(). 'ac' is the first zero-crossing of the autocorrelation function, 'ac1e' the (floored) first 1/e crossing of the autocorrelation function, and 'mi' the smaller of the first minimum of the (Kraskov) automutual information and the 1/e time. Default is 'ac'.

m : int, optional

The embedding dimension. Default is 2.

max_n : int or 'full', optional

The maximum number of embedded points used: longer embeddings are reduced to their first max_n points (a memory/time cap; the estimates keep sharpening with more points), or 'full' for no cropping. Default is 'full'.

Returns:

NaN if the embedding fails, there are fewer than 80 * m embedded points, or the embedded point cloud is constant. Otherwise:

  • sep_pp: projection-pursuit two-means separation. The whitened cloud is projected onto a fixed grid of directions (m = 2: 90 equally spaced angles; m = 3: 300 Fibonacci-lattice points on a hemisphere; other dimensions: 1 direction for m = 1 and 300 low-discrepancy directions for m > 3). For each direction the exact optimal 1-D two-means split is found, and its between-cluster fraction of the total variance is recorded. sep_pp is the maximum over directions: about 2/pi (0.64) for Gaussian data, 1 for two distinct point masses.

  • sep_mahal: log1p of the Mahalanobis separation between the two component means of a 2-component Gaussian mixture fit, using their pooled covariance (log-compressed to tame the heavy tail from near-singular covariance on near-deterministic embeddings). The EM fit (covariance regularization of 1e-6 times the mean variance of the embedded coordinates) starts from a deterministic hard split of the points at the optimal 1-D two-means threshold along the first principal component, and again from the split found for sep_pp; the fit of higher likelihood is kept. If neither split can start a fit (e.g., a group with too few points), splits at the median of the same two projections are used. NaN only if no 2-component fit is possible.

  • valley: the depth of the density valley at the sep_pp split. The points are projected onto the sep_pp direction (unit variance) and their density is estimated with a Gaussian kernel of bandwidth 0.9 * N ** (-1/5) (Silverman’s rule of thumb for unit variance); valley is one minus the density at the cut relative to the smaller of the densities at the two groups’ lower median points, floored at 0. 0 when the projected density has no dip at the cut (e.g., any unimodal cloud), 1 when the two groups are separated by an empty gap.

  • nongauss: the negentropy of the whitened cloud, in nats: the entropy of a Gaussian with the same covariance, (m/2) log(2 pi e), minus the cloud’s entropy estimated with the Kozachenko-Leonenko nearest-neighbor estimator (5 neighbors, each nearest-neighbor distance floored at 0.01 in whitened units, so that repeated values give a finite, saturating value). Near 0 for Gaussian data, and larger the more structured (clustered, curved, skewed or heavy-tailed) the cloud.

Return type:

dict or float