Matrix Profile Detector

class dtaianomaly.anomaly_detection.MatrixProfileDetector(window_size: int | str, normalize: bool = True, p: float = 2.0, k: int = 1, novelty: bool = False)

Anomaly detector based on the Matrix Profile

Use the STOMP algorithm to detect anomalies in a time series [Zhu2016matrixII]. STOMP is a fast and scalable algorithm for computing the matrix profile, which measures the distance from each sequence to the most similar other sequence. Consequently, the matrix profile can be used to quantify how anomalous a subsequence is, because it has a large distance to all other subsequences.

Parameters:

• window_size (int or str) – The window size to use for computing the matrix profile. This value will be passed to compute_window_size().

• normalize (bool, default=True) – Whether to z-normalize the time series before computing the matrix profile.

• p (float, default=2.0) – The norm to use for computing the matrix profile.

• k (int, default=1) – The k-th nearest neighbor to use for computing the sequence distance in the matrix profile.

• novelty (bool, default=False) – If novelty detection should be performed, i.e., detect anomalies in regard to the train time series. If False, the matrix profile equals a self-join, otherwise the matrix profile will be computed by comparing the subsequences in the test data to the subsequences in the train data.

window_size_

The effectively used window size for computing the matrix profile

Type:

int

X_reference_

The reference time series. Only available if novelty=True

Type:

np.ndarray of shape (n_samples, n_attributes)

Notes

If the given time series is multivariate, the matrix profile is computed for each dimension separately and then summed up.

Examples

>>> from dtaianomaly.anomaly_detection import MatrixProfileDetector
>>> from dtaianomaly.data import demonstration_time_series
>>> x, y = demonstration_time_series()
>>> matrix_profile = MatrixProfileDetector(window_size=50).fit(x)
>>> matrix_profile.decision_function(x)
array([1.20325439, 1.20690487, 1.20426043, ..., 1.47953858, 1.50188666,
       1.49891281])

References

[Zhu2016matrixII]

Y. Zhu et al., “Matrix Profile II: Exploiting a Novel Algorithm and GPUs to Break the One Hundred Million Barrier for Time Series Motifs and Joins,” 2016 IEEE 16th International Conference on Data Mining (ICDM), Barcelona, Spain, 2016, pp. 739-748, doi: 10.1109/ICDM.2016.0085.

decision_function(X: ndarray) → ndarray

Compute anomaly scores.

Parameters:

X (array-like of shape (n_samples, n_attributes)) – Input time series.

Returns:

matrix_profile – Matrix profile scores. Higher is more anomalous.

Return type:

array-like of shape (n_samples)

Raises:

• ValueError – If X is not a valid array.

• NotFittedError – If novelty detection must be performed (novelty=True), but this detector has not been fitted yet.

• ValueError – If novelty detection must be performed (novelty=True), but the reference data X_reference_ has a different number of attributes than the given data X.

fit(X: ndarray, y: ndarray | None = None, **kwargs) → MatrixProfileDetector

Fit this detector to the given data. Function is only present for consistency. Only saves the given data as a numpy array if novelty=True.

Parameters:

• X (array-like of shape (n_samples, n_attributes)) – Input time series.

• y (ignored) – Not used, present for API consistency by convention.

• kwargs – Additional parameters to be passed to compute_window_size().

Returns:

self – Returns the instance itself

Return type:

MatrixProfileDetector

predict_proba(X: ndarray) → ndarray

Predict anomaly probabilities

Estimate the probability of a sample of X being anomalous, based on the anomaly scores obtained from decision_function by rescaling them to the range of [0, 1] via min-max scaling.

Parameters:

X (array-like of shape (n_samples, n_attributes)) – Input time series.

Returns:

anomaly_scores – 1D array with the same length as X, with values in the interval [0, 1], in which a higher value implies that the instance is more likely to be anomalous.

Return type:

array-like of shape (n_samples)

Raises:

• ValueError – If scores is not a valid array.

• ValueError – If the prediction scores from ‘decision_function’ are constant, but not in the interval [0, 1], because these values can not unambiguously be transformed to an anomaly probability.

save(path: str | Path) → None

Save detector to disk as a pickle file with extension .dtai. If the given path consists of multiple subdirectories, then the not existing subdirectories are created.

Parameters:

path (str or Path) – Location where to store the detector.