Anomaly detection module

This module contains functionality to detect anomalies. It can be imported as follows:

>>> from dtaianomaly import anomaly_detection

We refer to the documentation for more information regarding detecting anomalies using dtaianomaly.

API cheatsheet

Below there is a quick overview of the most essential methods to detect anomalies:

1. fit(). Fit the anomaly detector. This method requires both an X (the time series) and y (anomaly labels) parameter. However, in practice, most anomaly detectors will not use the ground truth labels. The parameter y is present for API consistency and is not required.

2. decision_function(). Compute the decision scores of an observation being an anomaly for a given time series X. Returns an array with an entry for each observation in the time series. Note that this score is not normalized, and depends on the specific anomaly detector. However, for all detectors, a higher score means more anomalous.

3. predict_proba(). Compute the probability of an anomaly being an anomaly. This is similar to the decision_function() method, but the computed scores are normalized to the interval \([0, 1]\), which enables the interpretation as a probability.

   Note

   The output of a predict_proba is often a matrix of size (n_samples, n_classes). For anomaly detection, this would lead to a matrix with two columns, one columns for the normal probabilities and one column for the anomalous probabilities. However, in dtaianomaly, the predict_proba() only returns the probability of a sample being anomalous, because this is the probability of interest in many anomaly detection applications.

Base Objects

BaseDetector(supervision)	Abstract base class for time series anomaly detection.
BaseNeuralDetector(supervision, window_size)	Base class for neural anomaly detectors, based on PyTorch.
BaseNeuralForecastingDetector(window_size[, ...])	Base class for forecasting-based neural anomaly detectors.
BaseNeuralReconstructionDetector(window_size)	Base class for reconstruction-based neural anomaly detectors.
BasePyODAnomalyDetector(window_size[, stride])	Abstract class for anomaly detection based on the PyOD library [41].
Supervision(*values)	Supervision types.
MultivariateDetector(detector[, ...])	Multivariate wrapper for anomaly detection.

Utility functions

load_detector(path)

Load a detector from disk.

Statistical methods

ClusterBasedLocalOutlierFactor(window_size)	Anomaly detector based on the Cluster-based Local Outlier Factor (CBLOF) [15].
CopulaBasedOutlierDetector(window_size[, stride])	Copula-based outlier detector (COPD) algorithm [20].
HistogramBasedOutlierScore(window_size[, ...])	Anomaly detector based on the Histogram Based Outlier Score (HBOS) algorithm [12].
IsolationForest(window_size[, stride, ...])	Anomaly detector based on the Isolation Forest algorithm [22].
KernelPrincipalComponentAnalysis(window_size)	Anomaly detector based on the Kernel Principal Component Analysis (KPCA) [16].
KMeansAnomalyDetector(window_size[, stride, ...])	Use KMeans clustering to detect anomalies [40].
KNearestNeighbors(window_size[, stride, ...])	Anomaly detector based on K-nearest neighbors [27].
LocalOutlierFactor(window_size[, stride, ...])	Anomaly detector based on the Local Outlier Factor [5].
OneClassSupportVectorMachine(window_size[, ...])	Anomaly detector based on One-Class Support Vector Machines (OC-SVM) [31].
PrincipalComponentAnalysis(window_size[, ...])	Anomaly detector based on the Principal Component Analysis (PCA) [1].
RobustPrincipalComponentAnalysis(window_size)	Anomaly detection based on Robust Principal Component Analysis (Robust PCA) [6].

Time series statistical methods

DWT_MLEAD([start_level, ...])	Anomaly detection based on the Discrete Wavelet Transform [36].
KShapeAnomalyDetector(window_size[, ...])	Anomaly detector based on KShape-clustering [25].
LocalPolynomialApproximation(neighborhood[, ...])	Perform anomaly detection based on local polynomial approximations [21].
MatrixProfileDetector(window_size[, ...])	Anomaly detector based on the Matrix Profile [42].
MedianMethod(neighborhood_size_before[, ...])	Anomaly detection based on the Two-sided Median Method [3].
RobustRandomCutForestAnomalyDetector(window_size)	Detect anomalies using robust random cut forest [14].
ROCKAD(window_size[, stride, n_kernels, ...])	Detect anomalies in time series subsequences with ROCKAD [35].
SpectralResidual(moving_average_window_size)	Detect anomalies using Spectral Residual [28].

Neural methods

AutoEncoder(window_size[, error_metric, ...])	Use an auto encoder to detect anomalies [30].
ConvolutionalNeuralNetwork(window_size[, ...])	Use a convolutional neural network to detect anomalies.
HybridKNearestNeighbors(window_size[, ...])	Anomaly detection based on a hybrid K-NN with AutoEncoder embedding [33].
LongShortTermMemoryNetwork(window_size[, ...])	Use an LSTM to detect anomalies [23].
MultilayerPerceptron(window_size[, ...])	Use a multilayer perceptron to detect anomalies.
Transformer(window_size[, error_metric, ...])	Use a transformer to detect anomalies [37].

Time series foundation models

Chronos(window_size[, model_path, ...])	Detect anomalies in time series using Chronos [2].
MOMENT(window_size[, model_size, ...])	Detect anomalies in time series using MOMENT [13].
TimeMoE(window_size[, model_path, ...])	Detect anomalies using the Time-MoE foundation model [32].

Baselines

AlwaysNormal()	Detector that predicts all instances to be normal.
AlwaysAnomalous()	Detector that predicts all instances to be anomalous.
MovingWindowVariance(window_size)	Detect anomalies based on the variance within a window.
RandomDetector([seed])	Assign random anomaly scores to the time series observations.
SquaredDifference([square_errors])	Compute anomaly scores based on the squared difference.