Refactor/anomaly detection api

[julien12234]

Summary

Edit, @dennisbader (2024-05-10 15:19:00)

• Improvements to the Anomaly Detection Module through major refactor. The refactor includes major performance optimization for the majority of the processes and improvements to the API, consistency, reliability, and the documentation. Some of these necessary changes come at the cost of breaking changes:
  • 🚀 Added an example notebook that showcases how to use Darts for Time Series Anomaly Detection
  • Added a new dataset for anomaly detection with the number of taxi passengers in New York from the year 2014 to 2015.
  • FittableWindowScorer (KMeans, PyOD, and Wasserstein Scorers) now accept any of darts "per-time" step metrics as difference function diff_fn.
  • ForecastingAnomalyModel is now much faster thanks to optimized historical forecasts to generate the prediction input for the scorers. We also added more control over the historical forecasts generation through additional parameters in all model methods.
  • 🔴 Breaking changes:
    • FittableWindowScorer (KMeans, PyOD, and Wasserstein Scorers) now expects diff_fn to be one of Darts "per-time" step metrics
    • ForecastingAnomalyModel : model is now enforced to be a GlobalForecastingModel
    • *.eval_accuracy(): (Aggregators, Detectors, Filtering/Forecasting Anomaly Models, Scorers)
      • renamed method to eval_metric():
      • renamed params actual_anomalies to anomalies, and anomaly_score to pred_scores
    • *.show_anomalies(): (Filtering/Forecasting Anomaly Models, Scorers)
      • renamed params actual_anomalies to anomalies
    • *.fit() (Filtering/Forecasting Anomaly Models)
      • renamed params actual_anomalies to anomalies
    • Scorer.*_from_prediction() (Scorers)
      • renamed method eval_accuracy_from_prediction() to eval_metric_from_prediction()
      • renamed params actual_series to series, and actual_anomalies to anomalies
    • darts.ad.utils.eval_accuracy_from_scores :
      • renamed function to eval_metric_from_scores
      • renamed params actual_anoamlies to anomalies, and anomaly_score to pred_scores
    • darts.ad.utils.eval_accuracy_from_binary_prediction :
      • renamed function to eval_metric_from_binary_prediction
      • renamed params actual_anoamlies to anomalies, and binary_pred_anomalies to pred_anomalies
    • darts.ad.utils.show_anomalies_from_scores:
      • renamed params series to actual_series, actual_anomalies to anomalies, model_output to pred_series, and anomaly_scores to pred_scores
• Improvements to TimeSeries :
  • New method with_times_and_values(), which returns a new series with a new time index and new values but with identical columns and metadata as the series called from (static covariates, hierarchy).
  • New method slice_intersect_times(), which returns the sliced time index of a series, where the index has been intersected with another series.
  • Method with_values() now also acts on array-like values rather than only on numpy arrays.

Original description:

Some refactoring and upgrading of the anomaly detection API:

• code refactoring in tests/ad
• bug fix in utils.py for functions eval_accuracy_from_scores and eval_accuracy_from_binary_prediction
• Fix bug in NormScorer when passing a probabilistic time series
• Fix show_anomalies_from_scores when windows are not ordered in an increasing order
• Refactor/vectorize the windowing (series -> tabular data) for scorers Wasserstein, Kmeans and PyOD

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 94.44444% with 43 lines in your changes are missing coverage. Please review.

Project coverage is 93.71%. Comparing base (a162664) to head (d24a24d).

❗ Current head d24a24d differs from pull request most recent head 8a0a54f. Consider uploading reports for the commit 8a0a54f to get more accurate results

Files	Patch %	Lines
darts/ad/scorers/scorers.py	96.24%	8 Missing ⚠️
darts/ad/detectors/detectors.py	89.39%	7 Missing ⚠️
darts/ad/anomaly_model/filtering_am.py	78.57%	6 Missing ⚠️
darts/ad/utils.py	95.48%	6 Missing ⚠️
darts/ad/anomaly_model/anomaly_model.py	93.97%	5 Missing ⚠️
darts/ad/aggregators/aggregators.py	90.69%	4 Missing ⚠️
darts/ad/anomaly_model/forecasting_am.py	87.09%	4 Missing ⚠️
darts/timeseries.py	92.85%	2 Missing ⚠️
darts/datasets/__init__.py	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1477      +/-   ##
==========================================
- Coverage   93.79%   93.71%   -0.08%     
==========================================
  Files         138      138              
  Lines       14285    14295      +10     
==========================================
- Hits        13398    13396       -2     
- Misses        887      899      +12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[hrzn]

Thanks for this @julien12234 ! I only have minor comments. Would be great to merge sometime soon. You have a couple of merge conflicts to sort out first.

[madtoinou]

Some minor comments about the metric argument that should probably be a Literal, the order of the argument (notably for series and anomalie) might benefit from a slight change for some methods.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB