Filtering Anomaly Model¶

A FilteringAnomalyModel wraps around a Darts filtering model and one or several anomaly scorer(s) to compute anomaly scores by comparing how actuals deviate from the model’s predictions (filtered series).

class darts.ad.anomaly_model.filtering_am.FilteringAnomalyModel(model, scorer)[source]¶

Bases: AnomalyModel

Filtering-based Anomaly Detection Model

The filtering model may or may not be already fitted. The underlying assumption is that this model should be able to adequately filter the series in the absence of anomalies. For this reason, it is recommended to either provide a model that has already been fitted and evaluated to work appropriately on a series without anomalies, or to ensure that a simple call to the fit() function of the model will be sufficient to train it to satisfactory performance on series without anomalies.

Calling fit() on the anomaly model will fit the underlying filtering model only if allow_model_training is set to True upon calling fit(). In addition, calling fit() will also fit the fittable scorers, if any.

Parameters

model (FilteringModel) – A Darts FilteringModel used to filter the actual time series.
scorer (Union[AnomalyScorer, Sequence[AnomalyScorer]]) – One or multiple scorer(s) used to compare the actual and predicted time series in order to obtain an anomaly score TimeSeries. If a list of scorers, score() will output anomaly scores for each scorer.

Attributes

`scorers_are_trainable`	Whether any of the Scorers is trainable.
`scorers_are_univariate`	Whether any of the Scorers is univariate.

Methods

`eval_metric`(anomalies, series[, metric])	Compute a metric for the anomaly scores computed by the model.
`fit`(series[, allow_model_training])	Fit the underlying filtering model (if applicable) and the fittable scorers, if any.
`predict_series`(series, **kwargs)	Filters the given sequence of target time series with the filtering model.
`score`(series[, return_model_prediction])	Compute the anomaly score(s) for the given (sequence of) series.
`show_anomalies`(series[, anomalies, ...])	Plot the results of the anomaly model.

eval_metric(anomalies, series, metric='AUC_ROC', **filter_kwargs)[source]¶

Compute a metric for the anomaly scores computed by the model.

Predicts the series with the filtering model, and applies the scorer(s) on the filtered time series and the given target time series. Returns the score(s) of an agnostic threshold metric, based on the anomaly score given by the scorer(s).

Parameters

anomalies (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) ground truth binary anomaly series (1 if it is an anomaly and 0 if not).
series (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) series to predict anomalies on.
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”.
**filter_kwargs – Additional parameters passed to the filtering model’s filter() method.

Return type

Union[dict[str, float], dict[str, Sequence[float]], Sequence[dict[str, float]], Sequence[dict[str, Sequence[float]]]]

Returns

Dict[str, float] – A dictionary with the resulting metrics for single univariate series, with keys representing the anomaly scorer(s), and values representing the metric values.
Dict[str, Sequence[float]] – Same as for Dict[str, float] but for multivariate series, and anomaly scorers that treat series components/columns independently (by nature of the scorer or if component_wise=True).
Sequence[Dict[str, float]] – Same as for Dict[str, float] but for a sequence of univariate series.
Sequence[Dict[str, Sequence[float]]] – Same as for Dict[str, float] but for a sequence of multivariate series.

fit(series, allow_model_training=False, **filter_fit_kwargs)[source]¶

Fit the underlying filtering model (if applicable) and the fittable scorers, if any.

Train the filter (if not already fitted and allow_model_training is True) and the fittable scorer(s) on the given time series.

The filter model will be applied to the given series, and the results will be used to train the scorer(s).

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) series to train on (generally assumed to be anomaly-free).
allow_model_training (bool) – Whether the filtering model should be fitted on the given series. If False, the model must already be fitted.
**filter_fit_kwargs – Additional parameters passed to the filtering model’s fit() method.

Returns

Fitted model.

Return type

self

predict_series(series, **kwargs)[source]¶

Filters the given sequence of target time series with the filtering model.

Parameters

series (Sequence[TimeSeries]) – The sequence of series to filter.
**kwargs – Additional parameters passed to the filtering model’s filter() method.

Return type

Sequence[TimeSeries]

score(series, return_model_prediction=False, **filter_kwargs)[source]¶

Compute the anomaly score(s) for the given (sequence of) series.

Predicts the given target time series with the filtering model, and applies the scorer(s) to compare the predicted (filtered) series and the provided series.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) series to score on.
return_model_prediction (bool) – Whether to return the filtering model prediction along with the anomaly scores.
**filter_kwargs – Additional parameters passed to the filtering model’s filter() method.

Return type

Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]]]

Returns

TimeSeries – A single TimeSeries for a single series with a single anomaly scorers.
Sequence[TimeSeries] – A sequence of TimeSeries for:
- a single series with multiple anomaly scorers.
- a sequence of series with a single anomaly scorer.
Sequence[Sequence[TimeSeries]] – A sequence of sequences of TimeSeries for a sequence of series and multiple anomaly scorers. The outer sequence is over the series, and inner sequence is over the scorers.

property scorers_are_trainable¶: Whether any of the Scorers is trainable.

property scorers_are_univariate¶: Whether any of the Scorers is univariate.

show_anomalies(series, anomalies=None, names_of_scorers=None, title=None, metric=None, **score_kwargs)[source]¶

Plot the results of the anomaly model.

Computes the score on the given series input and shows the different anomaly scores with respect to time.

The plot will be composed of the following:

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

It is 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 are provided.

Parameters

series (TimeSeries) – The series to visualize anomalies from.
anomalies (Optional[TimeSeries, None]) – The ground truth of the anomalies (1 if it is an anomaly and 0 if not).
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.
title (Optional[str, None]) – Title of the figure.
metric (Optional[Literal[‘AUC_ROC’, ‘AUC_PR’], None]) – 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). Default: “AUC_ROC”.
score_kwargs – parameters for the score() method.

Forecasting Anomaly Model