Implementation:Online ml River Anomaly PAD
| Knowledge Sources | |
|---|---|
| Domains | Online_Learning, Anomaly_Detection, Time_Series, Predictive_Methods |
| Last Updated | 2026-02-08 16:00 GMT |
Overview
Predictive Anomaly Detection uses a predictive model to learn normal behavior and scores anomalies based on prediction error relative to a dynamic threshold.
Description
PAD (PredictiveAnomalyDetection) employs any predictive model (forecaster, regressor, or classifier) to learn normal data patterns. It compares predictions with actual values using squared error and maintains running statistics of these errors (mean and variance). The dynamic threshold is computed as mean + n_std * sqrt(variance). Anomaly scores are linearly scaled: errors below the threshold receive scores in [0,1), while errors exceeding the threshold receive a score of 1.0. A warm-up period prevents unreliable scores during initial learning.
Usage
Use PAD when you can model normal behavior with a predictive model. It's particularly effective for time series anomaly detection with forecasters. Choose n_std based on desired sensitivity (higher values = less sensitive). Set warmup_period to allow the model to stabilize before scoring.
Code Reference
Source Location
- Repository: Online_ml_River
- File: river/anomaly/pad.py
Signature
class PredictiveAnomalyDetection(anomaly.base.SupervisedAnomalyDetector):
def __init__(
self,
predictive_model: base.Estimator | None = None,
horizon: int = 1,
n_std: float = 3.0,
warmup_period: int = 0,
):
...
def learn_one(self, x: dict | None, y: base.typing.Target | float):
...
def score_one(self, x: dict, y: base.typing.Target):
...
Import
from river import anomaly
I/O Contract
| Parameter | Type | Description |
|---|---|---|
| predictive_model | Estimator (optional) | Model to predict normal behavior |
| horizon | int (default: 1) | Forecast horizon for time series models |
| n_std | float (default: 3.0) | Number of standard deviations for threshold |
| warmup_period | int (default: 0) | Samples before scoring (returns 0.0 during warmup) |
Usage Examples
from river import datasets
from river import time_series
from river import anomaly
from river import preprocessing
from river import linear_model
from river import optim
period = 12
predictive_model = time_series.SNARIMAX(
p=period,
d=1,
q=period,
m=period,
sd=1,
regressor=(
preprocessing.StandardScaler()
| linear_model.LinearRegression(
optimizer=optim.SGD(0.005),
)
),
)
PAD = anomaly.PredictiveAnomalyDetection(
predictive_model,
horizon=1,
n_std=3.5,
warmup_period=15
)
scores = []
for t, (x, y) in enumerate(datasets.AirlinePassengers()):
score = PAD.score_one(None, y)
PAD.learn_one(None, y)
scores.append(score)
if score > 0.9:
print(f"Anomaly at {t}: y={y}, score={score:.3f}")
print(f"Final score: {scores[-1]}") # 0.053
# Use with regression model
from river import compose
reg_model = (
preprocessing.StandardScaler() |
linear_model.LinearRegression()
)
PAD_reg = anomaly.PredictiveAnomalyDetection(
predictive_model=reg_model,
n_std=2.5,
warmup_period=20
)