pyhctsa.operations.correlation.matrix_profile

pyhctsa.operations.correlation.matrix_profile(y, m=('ac', 8), max_n=5000)

How well each subsequence shape recurs elsewhere in a time series (the matrix profile).

Port of hctsa’s CO_MatrixProfile. Computes the matrix profile: for every length-m window (subsequence) of the time series, the distance to its nearest neighbor among all other windows, after z-normalizing each window (so only its shape matters, not its local level or amplitude). Trivial matches (overlapping windows, |i-j| < m/2) are excluded. Distances are expressed as the equivalent nearest-neighbor Pearson correlation, r = 1 - d^2/(2m), which is bounded and interpretable.

Features summarize the distribution of r across windows: high values mean shapes recur (‘motifs’); a window with unusually low r is a ‘discord’ (anomaly). The corrected arc curve (Gharghabi et al., 2017; the FLUSS algorithm [1]) counts how many nearest-neighbor links cross each time point, relative to what a stationary process would give; its minimum is low when the series has a regime change, because windows then match within their own regime.

A one-off anomaly lasting longer than about m/2 is not a discord: its own overlapping windows match each other (the ‘twin freak’ problem).

Uses the STOMP recursion (O(N^2) time, O(N) memory), compiled with numba.

References

Parameters:
y : array-like

The input time series (z-scored in hctsa).

m : int or ('ac', k), optional

The window length in samples; or ('ac', k) for k times the first zero-crossing of the autocorrelation function (at least 10 samples). Default ('ac', 8). Longer windows give more reliable estimates of the nearest-neighbor statistics (test-retest across processes: 0.93-0.96 at k = 8 vs 0.73-0.84 at k = 4), at the cost of needing longer series.

max_n : int or 'full', optional

Crops time series longer than this to their first max_n samples (or 'full' to use every sample). Default 5000.

Returns:

  • meanR, medianR: the mean and median nearest-neighbor correlation (‘matchiness’);

  • motifR: the highest nearest-neighbor correlation (the best-repeated shape);

  • discordR: the lowest nearest-neighbor correlation (the most anomalous shape);

  • discordGap: medianR - discordR, how anomalous the discord is relative to a typical window;

  • propMatch90: the proportion of windows with a nearest neighbor at r > 0.9;

  • minCAC: the minimum of the corrected arc curve (low = regime change). A specialist statistic: it separates regime-switching from stationary series well, but across stationary series it mostly reflects estimation noise.

The output is a single NaN if the series is too short (fewer than 5m windows), no correlation length can be estimated, or most windows are flat.

Return type:

dict or float