Utils for Anomaly Detection¶

Common functions used throughout the Anomaly Detection module.

darts.ad.utils.eval_metric_from_binary_prediction(anomalies, pred_anomalies, window=1, metric='recall')[source]¶

Computes a score/metric between predicted anomalies against true anomalies.

pred_anomalies and anomalies must have:

identical dimensions (number of time steps and number of components/columns),

binary values belonging to the two classes (1 if it is an anomaly and 0 if not)

If one series is given for anomalies and pred_anomalies contains more than one series, the function will consider anomalies as the true anomalies for all scores in pred_scores.

Parameters

anomalies (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) ground truth binary anomaly series (1 if it is an anomaly and 0 if not).
pred_anomalies (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) predicted binary anomaly series.
window (Union[int, Sequence[int]]) – Integer value indicating the number of past samples each point represents in the pred_scores. The parameter will be used to transform anomalies. If a list of integers, the length must match the number of series in pred_scores. If an integer, the value will be used for every series in pred_scores and anomalies.
metric (Literal[‘recall’, ‘precision’, ‘f1’, ‘accuracy’]) – The name of the metric function to use. Must be one of “recall”, “precision”, “f1”, and “accuracy”. Default: “recall”.

Return type

Union[float, Sequence[float], Sequence[Sequence[float]]]

Returns

float – A single score for univariate pred_anomalies series (with only one component/column).
Sequence[float] – A sequence (list) of scores for:
- multivariate pred_anomalies series (multiple components). Gives a score for each component.
- a sequence (list) of univariate pred_anomalies series. Gives a score for each series.
Sequence[Sequence[float]] – A sequence of sequences of scores for a sequence of multivariate pred_anomalies series. Gives a score for each series (outer sequence) and component (inner sequence).

darts.ad.utils.eval_metric_from_scores(anomalies, pred_scores, window=1, metric='AUC_ROC')[source]¶

Computes a score/metric between anomaly scores against true anomalies.

anomalies and pred_scores must have the same shape. anomalies must be binary and have values belonging to the two classes (0 and 1).

If one series is given for anomalies and pred_scores contains more than one series, the function will consider anomalies as the ground truth anomalies for all scores in pred_scores.

Parameters

anomalies (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) ground truth binary anomaly series (1 if it is an anomaly and 0 if not).
pred_scores (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) of estimated anomaly score series indicating how anomalous each window of size w is.
window (Union[int, Sequence[int]]) – Integer value indicating the number of past samples each point represents in the pred_scores. The parameter will be used to transform anomalies. If a list of integers, the length must match the number of series in pred_scores. If an integer, the value will be used for every series in pred_scores and anomalies.
metric (Literal[‘AUC_ROC’, ‘AUC_PR’]) – The name of the metric function to use. Must be one of “AUC_ROC” (Area Under the Receiver Operating Characteristic Curve) and “AUC_PR” (Average Precision from scores). Default: “AUC_ROC”.

Return type

Union[float, Sequence[float], Sequence[Sequence[float]]]

Returns

float – A single score/metric for univariate pred_scores series (with only one component/column).
Sequence[float] – A sequence (list) of scores for:
- multivariate pred_scores series (multiple components). Gives a score for each component.
- a sequence (list) of univariate pred_scores series. Gives a score for each series.
Sequence[Sequence[float]] – A sequence of sequences of scores for a sequence of multivariate pred_scores series. Gives a score for each series (outer sequence) and component (inner sequence).

darts.ad.utils.show_anomalies_from_scores(series, anomalies=None, pred_series=None, pred_scores=None, window=1, names_of_scorers=None, title=None, metric=None)[source]¶

Plot the results generated by an anomaly model.

The plot will be composed of the following:

the actual series itself with the output of the model (if given)
the anomaly score of each scorer. The scorer with different windows will be separated.
the actual anomalies, if given.

If pred_series is stochastic (i.e., if it has multiple samples), the function will plot:

the mean per timestamp
the quantile 0.95 for an upper bound
the quantile 0.05 for a lower bound

Possible to:

add a title to the figure with the parameter title
give personalized names for the scorers with names_of_scorers
show the results of a metric for each anomaly score (AUC_ROC or AUC_PR), if the actual anomalies is given

Parameters

series (TimeSeries) – The actual series to visualize anomalies from.
anomalies (Optional[TimeSeries]) – The ground truth of the anomalies (1 if it is an anomaly and 0 if not).
pred_series (Optional[TimeSeries]) – Output of the model given as input the series (can be stochastic).
pred_scores (Union[TimeSeries, Sequence[TimeSeries], None]) – Output of the scorers given the output of the model and series.
window (Union[int, Sequence[int]]) – Window parameter for each anomaly scores. Default: 1. If a list of anomaly scores is given, the same default window will be used for every score.
names_of_scorers (Union[str, Sequence[str], None]) – Name of the scores. Must be a list of length equal to the number of scorers in the anomaly_model. Only effective when pred_scores is not None.
title (Optional[str]) – Title of the figure
metric (Optional[Literal[‘AUC_ROC’, ‘AUC_PR’]]) – Optionally, the name of the metric function to use. Must be one of “AUC_ROC” (Area Under the Receiver Operating Characteristic Curve) and “AUC_PR” (Average Precision from scores). Only effective when pred_scores is not None. Default: “AUC_ROC”.

Wasserstein Scorer

Data Processing