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:
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 ifallow_model_training
is set toTrue
upon callingfit()
. In addition, callingfit()
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 scoreTimeSeries
. 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 scoresTimeSeries
.
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)[source]¶
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)[source]¶
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: Falsefilter_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)[source]¶
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: Falsefilter_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)[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 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 figuremetric (
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