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)

Bases: darts.ad.anomaly_model.anomaly_model.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

• filter – A filtering model from Darts that will be used to filter the actual time series

• scorer (Union[AnomalyScorer, Sequence[AnomalyScorer]]) – One or multiple scorer(s) that will be used to compare the actual and predicted time series in order to obtain an anomaly score TimeSeries. If a list of N scorer is given, the anomaly model will call each one of the scorers and output a list of N anomaly scores TimeSeries.

Methods

eval_accuracy(actual_anomalies, series[, metric])	Compute the accuracy of 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.
score(series[, return_model_prediction])	Compute the anomaly score(s) for the given series.
show_anomalies(series[, actual_anomalies, ...])	Plot the results of the anomaly model.

eval_accuracy(actual_anomalies, series, metric='AUC_ROC', **filter_kwargs)

Compute the accuracy of 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

• actual_anomalies (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) ground truth of the anomalies (1 if it is an anomaly and 0 if not)

• series (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) series to predict anomalies on.

• metric (str) – Optionally, Scoring function to use. Must be one of “AUC_ROC” and “AUC_PR”. Default: “AUC_ROC”

• filter_kwargs – parameters of the Darts .filter() filtering model

Return type

Union[Dict[str, float], Dict[str, Sequence[float]], Sequence[Dict[str, float]], Sequence[Dict[str, Sequence[float]]]]

Returns

• Union[Dict[str, float], Dict[str, Sequence[float]], Sequence[Dict[str, float]],

• Sequence[Dict[str, Sequence[float]]]] – Score for the time series. A (sequence of) dictionary with the keys being the name of the scorers, and the values being the metric results on the (sequence of) series. If the scorer treats every dimension independently (by nature of the scorer or if its component_wise is set to True), the values of the dictionary will be a Sequence containing the score for each dimension.

fit(series, allow_model_training=False, **filter_fit_kwargs)

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

Train the filter (if not already fitted and allow_filter_training is set to True) and the 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 be trained on.

• allow_model_training (bool) – Boolean value that indicates if the filtering model needs to be fitted on the given series. If set to False, the model needs to be already fitted. Default: False

• filter_fit_kwargs – Parameters to be passed on to the filtering model fit() method.

Returns

Fitted model

Return type

self

score(series, return_model_prediction=False, **filter_kwargs)

Compute the anomaly score(s) for the given 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.

Outputs the anomaly score(s) of the provided time series.

Parameters

• series (Union[TimeSeries, Sequence[TimeSeries]]) – The (sequence of) series to score.

• return_model_prediction (bool) – Boolean value indicating if the prediction of the model should be returned along the anomaly score Default: False

• filter_kwargs – parameters of the Darts .filter() filtering model

Returns

Anomaly scores series generated by the anomaly model scorers

• TimeSeries if series is a series, and the anomaly model contains one scorer.

• Sequence[TimeSeries]

  • If series is a series, and the anomaly model contains multiple scorers,

  returns one series per scorer. * If series is a sequence, and the anomaly model contains one scorer, returns one series per series in the sequence.

• Sequence[Sequence[TimeSeries]] if series is a sequence, and the anomaly

model contains multiple scorers. The outer sequence is over the series, and inner sequence is over the scorers.

Return type

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

show_anomalies(series, actual_anomalies=None, names_of_scorers=None, title=None, metric=None, **score_kwargs)

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 filtering model

• the anomaly score of each scorer. The scorer 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 given

Parameters

• series (TimeSeries) – The series to visualize anomalies from.

• actual_anomalies (Optional[TimeSeries]) – 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 scorers. Must be a list of length equal to the number of scorers in the anomaly_model.

• title (Optional[str]) – Title of the figure

• metric (Optional[str]) – Optionally, Scoring function to use. Must be one of “AUC_ROC” and “AUC_PR”. Default: “AUC_ROC”

• score_kwargs – parameters for the .score() function

previous

<no title>

next

Forecasting Anomaly Model