Implementation:Online ml River Forecaster Forecast

Knowledge Sources	Domains	Last Updated
River River Docs	Online Machine Learning, Time Series Forecasting	2026-02-08 16:00 GMT

Overview

Concrete tool documenting the forecast interface method of the time_series.base.Forecaster class used by all River time series forecasters. Pattern Doc.

Description

The Forecaster.forecast method is the abstract interface that all River time series forecasters must implement for producing multi-step predictions. Given a horizon h and optional future exogenous features, it returns a list of h predicted values. This pattern doc describes the interface and how it is concretely realized by SNARIMAX (recursive strategy) and HoltWinters (direct extrapolation).

Usage

Reference this pattern when you need to understand how multi-step forecasts are produced, or when implementing a custom forecaster's forecast method.

Code Reference

Source Location

river/time_series/base.py:L29-L43

Interface Signature

class Forecaster(base.Estimator):
    @abc.abstractmethod
    def forecast(self, horizon: int, xs: list[dict] | None = None) -> list:
        """Makes forecast at each step of the given horizon.

        Parameters
        ----------
        horizon
            The number of steps ahead to forecast.
        xs
            The set of optional additional features. If given, then its
            length should be equal to the horizon.
        """

Import

from river import time_series
# The base class is at time_series.base.Forecaster

SNARIMAX.forecast Implementation

Source: river/time_series/snarimax.py:L352-L375

def forecast(self, horizon, xs=None):
    if xs is None:
        xs = [{}] * horizon

    if len(xs) != horizon:
        raise ValueError("the length of xs should be equal to the specified horizon")

    y_hist = collections.deque(self.y_hist)
    y_diff = collections.deque(self.y_diff)
    errors = collections.deque(self.errors)
    forecasts = [None] * horizon

    for t, x in enumerate(xs):
        x = self._add_lag_features(x=x, Y=y_diff, errors=errors)

        y_pred = self.regressor.predict_one(x)
        y_diff.appendleft(y_pred)

        forecasts[t] = self.differencer.undiff(y_pred, y_hist)
        y_hist.appendleft(forecasts[t])

        errors.appendleft(0)

    return forecasts

HoltWinters.forecast Implementation

Source: river/time_series/holt_winters.py:L210-L222

def forecast(self, horizon, xs=None):
    op = operator.mul if self.multiplicative else operator.add
    return [
        op(
            self.level[-1] + ((h + 1) * self.trend[-1] if self.trend else 0),
            (
                self.season[-self.seasonality + h % self.seasonality]
                if self.season
                else (1 if self.multiplicative else 0)
            ),
        )
        for h in range(horizon)
    ]

I/O Contract

Inputs

Parameter	Type	Description
horizon	int	Number of steps ahead to forecast
xs	list[dict] or None	Optional exogenous features for each future step; length must equal horizon if provided

Outputs

Return Type	Description
list[float]	Predicted values for each horizon step, from t+1 through t+horizon

Usage Examples

Basic multi-step forecast

from river import datasets
from river import time_series

model = time_series.SNARIMAX(p=12, d=1, q=12, m=12, sd=1)

for x, y in datasets.AirlinePassengers():
    model.learn_one(y)

# Forecast 12 months ahead
forecast = model.forecast(horizon=12)
for i, value in enumerate(forecast, 1):
    print(f"Step +{i}: {value:.2f}")

HoltWinters direct forecast

from river import datasets
from river import time_series

model = time_series.HoltWinters(
    alpha=0.3, beta=0.1, gamma=0.6,
    seasonality=12, multiplicative=True,
)

for x, y in datasets.AirlinePassengers():
    model.learn_one(y)

# Each step is computed directly from level, trend, and seasonal components
forecast = model.forecast(horizon=6)

Forecast with exogenous features

import datetime as dt
from river import time_series

model = time_series.SNARIMAX(p=1, d=0, q=0, m=1)

# Train on some data with exogenous features
for y, x in [(100, {"temp": 70}), (110, {"temp": 75}), (105, {"temp": 72})]:
    model.learn_one(y, x)

# Provide future exogenous features for each horizon step
future_xs = [{"temp": 78}, {"temp": 80}, {"temp": 82}]
forecast = model.forecast(horizon=3, xs=future_xs)

Related Pages

• Principle:Online_ml_River_Multi_Step_Forecasting