Time Series Detectors

PyOD has 7 dedicated time series detectors. Rankings from TSB-AD (NeurIPS 2024, 1,070 datasets).

See Layer 1: Time Series Anomaly Detection for usage and input format.

pyod.models.ts_od module

TimeSeriesOD: Windowed bridge that wraps any PyOD detector for time series anomaly detection.

Creates sliding windows from a time series, runs any PyOD detector on the resulting window matrix, and maps anomaly scores back to individual timestamps.

class pyod.models.ts_od.TimeSeriesOD(detector='IForest', window_size=50, step=1, score_aggregation='max', contamination=0.1)

Bases: BaseDetector

Windowed bridge that wraps any PyOD detector for time series anomaly detection.

Takes a time series, creates sliding windows, runs any PyOD detector on the window matrix, and maps scores back to timestamps.

Parameters

detectorstr or BaseDetector, optional (default=’IForest’)

Any PyOD detector. String resolves to a default-configured instance via the shortcut registry. If a BaseDetector instance is passed, it will be cloned.

window_sizeint, optional (default=50)

Size of the sliding window.

stepint, optional (default=1)

Step size between consecutive windows.

score_aggregationstr, optional (default=’max’)

How to aggregate window-level scores to timestamp-level scores. One of ‘max’ or ‘mean’.

contaminationfloat, optional (default=0.1)

Expected proportion of outliers in the dataset. Must be in (0, 0.5].

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Outlier scores of the training data. Higher is more abnormal.

threshold_float

Score threshold based on contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels of training data (0: inlier, 1: outlier).

detector_BaseDetector

The resolved and fitted inner detector instance.

Examples

>>> from pyod.models.ts_od import TimeSeriesOD
>>> import numpy as np
>>> X_train = np.random.randn(500)
>>> clf = TimeSeriesOD(detector='IForest', window_size=20)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))

decision_function(X)

Predict raw anomaly scores for time series X.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Test time series data.

Returns

anomaly_scoresnumpy array of shape (n_timestamps,)

Anomaly scores. Higher is more abnormal.

fit(X, y=None)

Fit detector on time series data.

Validates the input, creates sliding windows, fits the inner detector on the window matrix, and maps scores back to timestamps using the masked-score workflow.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → TimeSeriesOD

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → TimeSeriesOD

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.

pyod.models.ts_matrix_profile module

MatrixProfile: Time series anomaly detection using the STOMP algorithm.

Computes the Matrix Profile via the STOMP (Scalable Time-series Ordered Matrix Profile) algorithm, which identifies anomalous subsequences by measuring z-normalized Euclidean distance to the nearest non-trivial match.

See [MYZU+16] for details.

Reference:

Yeh, C.C.M., Zhu, Y., Ulanova, L., Begum, N., Ding, Y., Dau, H.A., Silva, D.F., Mueen, A. and Keogh, E., 2016. Matrix profile I: All pairs similarity joins for time series: a unifying view that includes motifs, discords and shapelets. In ICDM, pp. 1317-1322.

class pyod.models.ts_matrix_profile.MatrixProfile(window_size=50, contamination=0.1, channel_aggregation='max')

Bases: BaseDetector

Matrix Profile time series anomaly detector using STOMP.

Computes the Matrix Profile via the STOMP algorithm, identifying anomalous subsequences by measuring z-normalized Euclidean distance to the nearest non-trivial neighbor. Subsequences with high Matrix Profile values (discords) are anomalous.

This is a transductive detector: it only scores the training data. decision_function, predict, predict_proba, and predict_confidence raise NotImplementedError when called with new data.

Parameters

window_sizeint, optional (default=50)

Subsequence length for the Matrix Profile computation.

contaminationfloat in (0., 0.5), optional (default=0.1)

Expected proportion of outliers in the dataset.

channel_aggregationstr, optional (default=’max’)

How to aggregate per-channel scores for multivariate data. One of ‘max’ or ‘mean’.

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Outlier scores of the training data. Higher is more abnormal.

threshold_float

Score threshold based on contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels of training data (0: inlier, 1: outlier).

References

Yeh, C.C.M., Zhu, Y., Ulanova, L., Begum, N., Ding, Y., Dau, H.A., Silva, D.F., Mueen, A. and Keogh, E., 2016. Matrix profile I: All pairs similarity joins for time series. In ICDM, pp. 1317-1322.

Examples

>>> from pyod.models.ts_matrix_profile import MatrixProfile
>>> import numpy as np
>>> X_train = np.random.randn(300)
>>> clf = MatrixProfile(window_size=20, contamination=0.1)
>>> clf.fit(X_train)
>>> scores = clf.decision_scores_

decision_function(X)

Not supported (transductive detector).

Raises

NotImplementedError

fit(X, y=None)

Fit the Matrix Profile detector on time series data.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

predict(X, return_confidence=False)

Not supported (transductive detector).

Raises

NotImplementedError

predict_confidence(X)

Not supported (transductive detector).

Raises

NotImplementedError

predict_proba(X, method='linear', return_confidence=False)

Not supported (transductive detector).

Raises

NotImplementedError

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → MatrixProfile

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → MatrixProfile

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.

pyod.models.ts_spectral_residual module

SpectralResidual: FFT-based saliency for time series anomaly detection.

Implements the spectral residual (SR) saliency computation from Ren et al., “Time-Series Anomaly Detection Service at Microsoft”, KDD 2019.

Only the SR saliency step is implemented (not the full service pipeline with CNN post-processing).

class pyod.models.ts_spectral_residual.SpectralResidual(score_window=3, contamination=0.1, channel_aggregation='max')

Bases: BaseDetector

Spectral Residual anomaly detector for time series.

Computes a saliency map via the spectral residual of the log-amplitude spectrum. This is a dense method that produces one anomaly score per timestamp with no gaps.

Parameters

score_windowint, optional (default=3)

Size of the uniform averaging filter applied to the log-amplitude spectrum. Must be >= 1.

contaminationfloat, optional (default=0.1)

Expected proportion of outliers. Must be in (0, 0.5].

channel_aggregationstr, optional (default=’max’)

How to aggregate per-channel saliency scores for multivariate input. One of 'max' or 'mean'.

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Saliency-based outlier scores of the training data. Higher is more abnormal.

threshold_float

Score threshold derived from contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels (0: inlier, 1: outlier).

Examples

>>> from pyod.models.ts_spectral_residual import SpectralResidual
>>> import numpy as np
>>> X_train = np.random.randn(500)
>>> clf = SpectralResidual(contamination=0.1)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))

References

[1]

Ren, H., Xu, B., Wang, Y., Yi, C., Huang, C., Kou, X., Xing, T., Yang, M., Tong, J. and Zhang, Q., 2019. Time-series anomaly detection service at Microsoft. In Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining (pp. 3009-3017).

decision_function(X)

Predict raw anomaly scores for time series X.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Test time series data.

Returns

anomaly_scoresnumpy array of shape (n_timestamps,)

Saliency-based anomaly scores. Higher is more abnormal.

fit(X, y=None)

Fit detector on time series data.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → SpectralResidual

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → SpectralResidual

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.

pyod.models.ts_kshape module

KShape: k-Shape clustering-based time series anomaly detection.

Adapts the k-Shape clustering algorithm (Paparrizos & Gravano, SIGMOD 2015) for anomaly detection. Sliding-window subsequences are clustered using shape-based distance (SBD), and each subsequence is scored by its SBD to the nearest centroid. Subsequences far from all centroids are anomalous.

Reference:

Paparrizos, J. and Gravano, L., 2015. k-Shape: Efficient and accurate clustering of time series. In Proceedings of the 2015 ACM SIGMOD International Conference on Management of Data (pp. 1855-1870).

class pyod.models.ts_kshape.KShape(n_clusters=3, window_size=50, max_iter=100, contamination=0.1, channel_aggregation='max', random_state=42)

Bases: BaseDetector

k-Shape clustering-based time series anomaly detector.

Extracts sliding-window subsequences, clusters them using the k-Shape algorithm (shape-based distance + eigenvalue centroid update), and scores each subsequence by its SBD to the nearest centroid. Subsequences far from all centroids are considered anomalous.

This is an inductive detector: after fitting on training data, decision_function can score new time series.

Parameters

n_clustersint, optional (default=3)

Number of clusters for k-Shape.

window_sizeint, optional (default=50)

Size of the sliding window for extracting subsequences.

max_iterint, optional (default=100)

Maximum number of Lloyd’s iterations for k-Shape.

contaminationfloat in (0., 0.5), optional (default=0.1)

Expected proportion of outliers in the dataset.

channel_aggregationstr, optional (default=’max’)

How to aggregate per-channel scores for multivariate input. One of 'max' or 'mean'.

random_stateint or None, optional (default=42)

Random seed for reproducible centroid initialization.

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Outlier scores of the training data. Higher is more abnormal.

threshold_float

Score threshold based on contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels of training data (0: inlier, 1: outlier).

centroids_list of numpy arrays

Per-channel cluster centroids learned during fit.

Examples

>>> from pyod.models.ts_kshape import KShape
>>> import numpy as np
>>> X_train = np.random.randn(300)
>>> clf = KShape(n_clusters=3, window_size=20, contamination=0.1)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))

References

[1]

Paparrizos, J. and Gravano, L., 2015. k-Shape: Efficient and accurate clustering of time series. In Proceedings of the 2015 ACM SIGMOD International Conference on Management of Data (pp. 1855-1870).

decision_function(X)

Predict raw anomaly scores for time series X.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Test time series data.

Returns

anomaly_scoresnumpy array of shape (n_timestamps,)

Anomaly scores. Higher is more abnormal.

fit(X, y=None)

Fit the k-Shape anomaly detector on time series data.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → KShape

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → KShape

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.

pyod.models.ts_sand module

SAND: Streaming Anomaly detection with Normalization and Drift adaptation.

Simplified PyOD adaptation of: Boniol, P., Paparrizos, J., Palpanas, T. and Franklin, M.J., 2021. SAND: Streaming subsequence anomaly detection. Proceedings of the VLDB Endowment, 14(10), pp. 1717-1729.

This implementation extracts z-normalized sliding-window subsequences, initializes k centroids using k-Shape on the first batch, then scores remaining subsequences by SBD (shape-based distance) to their nearest centroid. Centroids are updated every batch_size subsequences via exponential moving average with parameter alpha.

class pyod.models.ts_sand.SAND(window_size=50, n_clusters=5, alpha=0.5, batch_size=100, max_iter=50, contamination=0.1, channel_aggregation='max', random_state=42)

Bases: BaseDetector

SAND streaming anomaly detector for time series.

Extracts z-normalized sliding-window subsequences, initializes k centroids via k-Shape on the first batch, and scores each subsequence by its SBD to the nearest centroid. Centroids are updated every batch_size subsequences using an exponential moving average, enabling drift adaptation.

Parameters

window_sizeint, optional (default=50)

Subsequence length for the sliding window.

n_clustersint, optional (default=5)

Number of centroids for k-Shape clustering.

alphafloat, optional (default=0.5)

Smoothing factor for centroid updates. new = alpha * batch_centroid + (1 - alpha) * old_centroid.

batch_sizeint, optional (default=100)

Number of subsequences between centroid updates.

max_iterint, optional (default=50)

Maximum iterations for initial k-Shape clustering.

contaminationfloat, optional (default=0.1)

Expected proportion of outliers. Must be in (0, 0.5].

channel_aggregationstr, optional (default=’max’)

How to aggregate per-channel scores for multivariate input. One of 'max' or 'mean'.

random_stateint or None, optional (default=42)

Random seed for reproducible centroid initialization.

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Outlier scores of the training data. Higher is more abnormal.

threshold_float

Score threshold derived from contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels (0: inlier, 1: outlier).

centroids_list of numpy arrays

Per-channel centroids after processing all training data.

Examples

>>> from pyod.models.ts_sand import SAND
>>> import numpy as np
>>> X_train = np.random.randn(500)
>>> clf = SAND(n_clusters=3, window_size=20, contamination=0.1)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))

References

[1]

Boniol, P., Paparrizos, J., Palpanas, T. and Franklin, M.J., 2021. SAND: Streaming subsequence anomaly detection. Proceedings of the VLDB Endowment, 14(10), pp. 1717-1729.

decision_function(X)

Predict raw anomaly scores for a test time series.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Test time series data.

Returns

anomaly_scoresnumpy array of shape (n_timestamps,)

Anomaly scores. Higher is more abnormal.

fit(X, y=None)

Fit the SAND detector on time series data.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → SAND

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → SAND

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.

pyod.models.ts_lstm module

LSTMAD: LSTM-based time series anomaly detection using prediction error with Mahalanobis distance scoring.

Simplified PyOD adaptation of Malhotra et al., ESANN 2015. Single-step prediction (horizon=1). Error vector per timestamp has n_channels dimensions. Anomaly score = Mahalanobis distance of prediction errors from a fitted multivariate Gaussian.

class pyod.models.ts_lstm.LSTMAD(window_size=50, hidden_size=64, n_layers=2, epochs=50, lr=0.001, batch_size=32, contamination=0.1)

Bases: BaseDetector

LSTM-based anomaly detector for time series.

Trains a stacked LSTM to predict the next timestep, then scores each timestamp by the Mahalanobis distance of its prediction error from a multivariate Gaussian fitted on training errors.

Parameters

window_sizeint, optional (default=50)

Number of past timesteps used as input context for prediction.

hidden_sizeint, optional (default=64)

Number of hidden units in each LSTM layer.

n_layersint, optional (default=2)

Number of stacked LSTM layers.

epochsint, optional (default=50)

Number of training epochs.

lrfloat, optional (default=1e-3)

Learning rate for Adam optimizer.

batch_sizeint, optional (default=32)

Mini-batch size for training.

contaminationfloat, optional (default=0.1)

Expected proportion of outliers. Must be in (0, 0.5].

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Outlier scores of the training data. Higher is more abnormal. First window_size timestamps are filled with threshold_ (no lookback available).

threshold_float

Score threshold derived from contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels (0: inlier, 1: outlier).

Examples

>>> from pyod.models.ts_lstm import LSTMAD
>>> import numpy as np
>>> X_train = np.random.randn(500)
>>> clf = LSTMAD(window_size=20, epochs=5)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))

References

[1]

Malhotra, P., Vig, L., Shroff, G. and Agarwal, P., 2015. Long short term memory networks for anomaly detection in time series. In Proceedings of the European Symposium on Artificial Neural Networks (ESANN) (p. 89).

decision_function(X)

Predict raw anomaly scores for time series X.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Test time series data.

Returns

anomaly_scoresnumpy array of shape (n_timestamps,)

Mahalanobis-distance anomaly scores. Higher is more abnormal. First window_size timestamps are filled with threshold_.

fit(X, y=None)

Fit detector on time series data.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → LSTMAD

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → LSTMAD

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.

pyod.models.ts_anomaly_transformer module

AnomalyTransformer: Transformer-based time series anomaly detector with association discrepancy.

Implements the Anomaly Transformer (Xu et al., ICLR 2022) which uses anomaly-attention with series-association and prior-association to detect anomalies in time series via a minimax optimization strategy.

Reference:

Xu, J., Wu, H., Wang, J., & Long, M. (2022). Anomaly Transformer: Time Series Anomaly Detection with Association Discrepancy. In International Conference on Learning Representations.

class pyod.models.ts_anomaly_transformer.AnomalyTransformer(window_size=100, d_model=512, n_heads=8, n_layers=3, epochs=10, lr=0.0001, batch_size=32, lambda_=3.0, contamination=0.1, step=1, dropout=0.1, device='auto')

Bases: BaseDetector

Anomaly Transformer for time series anomaly detection.

Implements the Anomaly Transformer (Xu et al., ICLR 2022), a Transformer-based architecture with anomaly-attention that computes series-association and prior-association to detect anomalies via association discrepancy and minimax training.

Parameters

window_sizeint, optional (default=100)

Size of the sliding window.

d_modelint, optional (default=512)

Dimensionality of the Transformer model.

n_headsint, optional (default=8)

Number of attention heads. Must divide d_model evenly.

n_layersint, optional (default=3)

Number of Transformer encoder layers.

epochsint, optional (default=10)

Number of training epochs.

lrfloat, optional (default=1e-4)

Learning rate.

batch_sizeint, optional (default=32)

Training batch size.

lambda_float, optional (default=3.0)

Weight for the association discrepancy term in the loss.

contaminationfloat, optional (default=0.1)

Expected proportion of outliers. Must be in (0, 0.5].

stepint, optional (default=1)

Step size between consecutive windows.

dropoutfloat, optional (default=0.1)

Dropout rate in the Transformer.

devicestr, optional (default=’auto’)

Device to use (‘cpu’, ‘cuda’, or ‘auto’).

Attributes

decision_scores_numpy array of shape (n_timestamps,)

Outlier scores of the training data. Higher is more abnormal.

threshold_float

Score threshold based on contamination.

labels_numpy array of shape (n_timestamps,)

Binary labels of training data (0: inlier, 1: outlier).

Examples

>>> from pyod.models.ts_anomaly_transformer import AnomalyTransformer
>>> import numpy as np
>>> X_train = np.random.randn(500)
>>> clf = AnomalyTransformer(window_size=50, d_model=32, n_heads=2,
...                           n_layers=1, epochs=2)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))

References

[1]

Xu, J., Wu, H., Wang, J., & Long, M. (2022). Anomaly Transformer: Time Series Anomaly Detection with Association Discrepancy. ICLR 2022.

decision_function(X)

Predict raw anomaly scores for time series X.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Test time series data.

Returns

anomaly_scoresnumpy array of shape (n_timestamps,)

Anomaly scores. Higher is more abnormal.

fit(X, y=None)

Fit the Anomaly Transformer on time series data.

Parameters

Xarray-like of shape (n_timestamps,) or (n_timestamps, n_channels)

Training time series data.

yIgnored

Not used, present for API consistency.

Returns

selfobject

Fitted estimator.

set_predict_proba_request(*, method: bool | None | str = '$UNCHANGED$', return_confidence: bool | None | str = '$UNCHANGED$') → AnomalyTransformer

Configure whether metadata should be requested to be passed to the predict_proba method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

methodstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for method parameter in predict_proba.

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, return_confidence: bool | None | str = '$UNCHANGED$') → AnomalyTransformer

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to predict.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters

return_confidencestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for return_confidence parameter in predict.

Returns

selfobject

The updated object.