Copula-based outlier detector

class dtaianomaly.anomaly_detection.CopulaBasedOutlierDetector(window_size: str | int, stride: int = 1, **kwargs)[source]

Copula-based outlier detector (COPD) algorithm.

COPOD [li2020copod] is based on modeling multivariate data distributions using Copula models. Copula functions separate the marginal distributions from the dependency structure of a multivariate distribution. This allows a copula to describe the joint distribution over the features using only the independent marginals, offering high flexibility when modeling high dimensional data. Outliers are consequently detected by measuring the tail probabilities. COPOD is parameter-free because the copula function does not involve learning or stochastic training.

Notes

The COPOD detector inherets from PyODAnomalyDetector.

Parameters:

  • window_size (int or str) – The window size to use for extracting sliding windows from the time series. This value will be passed to compute_window_size().

  • stride (int, default=1) – The stride, i.e., the step size for extracting sliding windows from the time series.

  • **kwargs – Arguments to be passed to the PyOD COPOD detector.

window_size_

The effectively used window size for this anomaly detector

Type:

int

pyod_detector_

A COPOD detector of PyOD

Type:

COPOD

Examples

>>> from dtaianomaly.anomaly_detection import CopulaBasedOutlierDetector
>>> from dtaianomaly.data import demonstration_time_series
>>> x, y = demonstration_time_series()
>>> copod = CopulaBasedOutlierDetector(10).fit(x)
>>> copod.decision_function(x)
array([ 9.90110663,  9.67868282,  9.51525285, ..., 25.00182389,
       24.60594424, 24.30393026])

References

[li2020copod]

Li, Z., Zhao, Y., Botta, N., Ionescu, C. and Hu, X. COPOD: Copula-Based Outlier Detection. IEEE International Conference on Data Mining (ICDM), 2020.

decision_function(X: ndarray) → ndarray

Compute decision scores.

Parameters:

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

Returns:

decision_scores – The decision scores of the anomaly detector. Higher indicates more anomalous.

Return type:

array-like of shape (n_samples)

Raises:

  • ValueError – If X is not a valid array.

  • NotFittedError – If this method is called before fitting the anomaly detector.

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

Fit this PyOD anomaly detector on the given data.

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:

PyODAnomalyDetector

Raises:

ValueError – If X is not a valid array.

predict_confidence(X: ndarray, X_train: ndarray = None, contamination: float = 0.05, decision_scores_given: bool = False)

Predict the confidence of the anomaly scores on the test given test data.

This method implements ExCeeD [perini2020quantifying] (Example-wise Confidence of anomaly Detectors) to estimate the confidence. ExCeed transforms the predicted decision scores to probability estimates using a Bayesian approach, which enables to assign a confidence score to each prediction which captures the uncertainty of the anomaly detector in that prediction.

Parameters:

  • X (array-like of shape (n_samples, n_attributes)) – The test time series for which the confidence of anomaly scores should be predicted.

  • X_train (array-like of shape (n_samples_train, n_attributes), default=None) – The training time series, which can be used as reference. If X_train=None, the test set is used as reference set.

  • contamination (float, default=0.05) – The (estimated) contamination rate for the data, i.e., the expected percentage of anomalies.

  • decision_scores_given (bool, default=False) – Whether the given X and X_train represent time series data or decision scores. If decision_scores_given=False (default), then the given arrays are interpreted as time series. Otherwise, they are interpreted as decision scores, as computed by decision_function().

Returns:

confidence – The confidence of this anomaly detector in each prediction in the given test time series.

Return type:

array-like of shape (n_samples)

References

[perini2020quantifying]

Perini, L., Vercruyssen, V., Davis, J. Quantifying the Confidence of Anomaly Detectors in Their Example-Wise Predictions. In: Machine Learning and Knowledge Discovery in Databases. ECML PKDD 2020. Springer, Cham, doi: 10.1007/978-3-030-67664-3_14.

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.