Histogram Based Outlier Score

class dtaianomaly.anomaly_detection.HistogramBasedOutlierScore(window_size: str | int, stride: int = 1, **kwargs)

Anomaly detector based on the Histogram Based Outlier Score (HBOS) algorithm.

Histogram Based Outlier Score (HBOS) [goldstein2012histogram] constructs for each feature a univariate histogram. Bins with a small height (for static bin widths) or wider bins (for dynamic bin widths) correspond to sparse regions of the feature space. Thus, values falling in these bins lay in sparse regions of the feature space and are considered more anomalous.

In this implementation, it is possible to set a window size to take the past observations into account. However, HBOS assumes feature independence. Therefore, for a time series with \(D\) attributes and a window size \(w\), HBOS constructs \(D \times w\) independent histograms, from which the anomaly score is computed.

Notes

The HBOS 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 histogram based outlier score.

window_size_

The effectively used window size for this anomaly detector

Type:

int

pyod_detector_

An HBOS detector of PyOD

Type:

HBOS

Examples

>>> from dtaianomaly.anomaly_detection import HistogramBasedOutlierScore
>>> from dtaianomaly.data import demonstration_time_series
>>> x, y = demonstration_time_series()
>>> hbos = HistogramBasedOutlierScore(1).fit(x)
>>> hbos.decision_function(x)
array([0.51808795, 0.51808795, 0.51808795, ..., 0.48347552, 0.48347552,
       0.48347552])

References

[goldstein2012histogram]

Goldstein, Markus, and Andreas Dengel. “Histogram-based outlier score (hbos): A fast unsupervised anomaly detection algorithm.” KI-2012: poster and demo track 1 (2012): 59-63.

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_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.