Median Method

class dtaianomaly.anomaly_detection.MedianMethod(neighborhood_size_before: int, neighborhood_size_after: int | None = None)[source]

Anomaly detection based on the Two-sided Median Method.

The Median Method [basu2007automatic] computes the deviation of a sample compared to its neighborhood. This neighborhood is computed as a window around the sample. The deviation is consequently measured as the number of standard deviations the observations deviates from the mean of its neighborhood.

In contrast to the original paper, this implementation allows to define a different neighborhood size before and after the sample, to fine tune how much lookahead is allowed. In the ultimate case, if neighborhood_size_after = 0, then the Median Method is a purely online anomaly detector. Note, however, that this case differs from the One-Sided Median Method discussed in the original paper, which also uses the first order difference to detect anomalies.

Parameters:

neighborhood_size_before (int) – The number of observations before the sample to include in the neighborhood.
neighborhood_size_after (int, default=None) – The number of observations after the sample to include in the neighborhood. If None, the same value as window_size_before will be used.

Examples

>>> from dtaianomaly.anomaly_detection import MedianMethod
>>> from dtaianomaly.data import demonstration_time_series
>>> x, y = demonstration_time_series()
>>> median_method = MedianMethod(10).fit(x)
>>> median_method.decision_function(x)
array([1.1851476 , 0.68191703, 1.05125284, ..., 0.81373386, 1.86097851,
       0.05852008])

References

[basu2007automatic]

Basu, Sabyasachi, and Martin Meckesheimer. “Automatic outlier detection for time series: an application to sensor data.” Knowledge and Information Systems 11 (2007), 137-154, doi: 10.1007/s10115-006-0026-6.

decision_function(X: ndarray) → ndarray[source]

Abstract method, compute anomaly scores.

Parameters:: X (array-like of shape (n_samples, n_attributes)) – Input time series.
Returns:: decision_scores – The computed anomaly scores.
Return type:: array-like of shape (n_samples)

fit(X: ndarray, y: ndarray | None = None, **kwargs) → BaseDetector[source]

Abstract method, fit this detector to the given data.

Parameters:

X (array-like of shape (n_samples, n_attributes)) – Input time series.
y (array-like, default=None) – Ground-truth information.

Returns:

self – Returns the instance itself.

Return type:

BaseDetector

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.