Implementation:Online ml River Time Series HorizonMetric Impl
| Knowledge Sources | Domains | Last Updated |
|---|---|---|
| River River Docs | Online Machine Learning, Time Series Forecasting, Model Evaluation | 2026-02-08 16:00 GMT |
Overview
Concrete tool for maintaining separate per-horizon-step evaluation metrics for multi-step time series forecasting in River.
Description
The time_series.HorizonMetric class wraps a base regression metric and maintains independent copies for each step of the forecast horizon. When update is called with parallel lists of true and predicted values, each position's metric is updated independently. The get method returns a list of per-step metric values.
The time_series.HorizonAggMetric class extends HorizonMetric by applying an aggregation function to the per-step values, producing a single scalar result. Both classes inherit from ForecastingMetric, the abstract base for all forecasting evaluation metrics.
Usage
Import time_series.HorizonMetric when you need per-horizon-step metric tracking. Typically this is used internally by time_series.evaluate, but it can also be used directly for custom evaluation loops.
Code Reference
Source Location
river/time_series/metrics.py:L35-L94(HorizonMetric)river/time_series/metrics.py:L97-L145(HorizonAggMetric)
Signature
class HorizonMetric(ForecastingMetric):
def __init__(self, metric: metrics.base.RegressionMetric)
class HorizonAggMetric(HorizonMetric):
def __init__(
self,
metric: metrics.base.RegressionMetric,
agg_func: typing.Callable[[list[float]], float],
)
Methods
# HorizonMetric
def update(self, y_true: list, y_pred: list) -> None
def get(self) -> list[float]
# HorizonAggMetric (overrides get)
def get(self) -> float
Import
from river import time_series
I/O Contract
Inputs
| Method | Parameter | Type | Description |
|---|---|---|---|
| __init__ | metric | RegressionMetric | Base metric to clone for each horizon step (e.g., metrics.MAE()) |
| __init__ (HorizonAggMetric) | agg_func | Callable | Function to aggregate per-step values (e.g., statistics.mean) |
| update | y_true | list[Number] | True values at each horizon step |
| update | y_pred | list[Number] | Predicted values at each horizon step |
Outputs
| Method | Return Type | Description |
|---|---|---|
| HorizonMetric.get() | list[float] | Metric value for each horizon step |
| HorizonAggMetric.get() | float | Single aggregated metric value across all horizon steps |
| __repr__ | str | Formatted string showing per-step metric values (e.g., "+1 MAE: 25.9") |
Usage Examples
Direct usage of HorizonMetric
from river import metrics
from river import time_series
horizon_metric = time_series.HorizonMetric(metric=metrics.MAE())
# Simulate forecast evaluation
y_true = [100, 110, 120]
y_pred = [98, 115, 118]
horizon_metric.update(y_true, y_pred)
y_true = [105, 112, 125]
y_pred = [103, 108, 130]
horizon_metric.update(y_true, y_pred)
# Get per-step metric values
values = horizon_metric.get()
# values is a list of 3 MAE values, one per horizon step
print(horizon_metric)
# +1 MAE: 2.0
# +2 MAE: 4.5
# +3 MAE: 3.5
Using HorizonAggMetric
import statistics
from river import metrics
from river import time_series
agg_metric = time_series.HorizonAggMetric(
metric=metrics.MAE(),
agg_func=statistics.mean,
)
agg_metric.update([100, 110, 120], [98, 115, 118])
agg_metric.update([105, 112, 125], [103, 108, 130])
# Returns a single float: mean of per-step MAE values
print(agg_metric.get())
Used internally by time_series.evaluate
from river import datasets
from river import metrics
from river import time_series
# evaluate() creates and returns a HorizonMetric internally
result = time_series.evaluate(
dataset=datasets.AirlinePassengers(),
model=time_series.HoltWinters(alpha=0.1),
metric=metrics.MAE(),
horizon=4,
)
# result is a HorizonMetric
per_step_values = result.get() # list of 4 MAE values
print(result)
# +1 MAE: 40.931286
# +2 MAE: 42.667998
# +3 MAE: 44.158092
# +4 MAE: 43.849617