Principle:Online ml River Incremental Forecasting Interface

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

Overview

Abstract interface for online time series forecasters defining the learn_one contract for incrementally updating model state with each new observation.

Description

All River time series forecasters inherit from the base Forecaster class, which defines the core contract for online forecasting. The learn_one(y, x) method is the central abstraction: it accepts a single new observation y (the endogenous variable) and an optional dictionary x of exogenous features, and updates the model's internal state accordingly.

This interface ensures that:

• All forecasters share a uniform API: Whether the underlying model is SNARIMAX, HoltWinters, or a custom forecaster, the calling code uses the same learn_one / forecast interface
• Models are truly online: State is updated incrementally without reprocessing historical data
• Memory is bounded: Models only maintain the minimal internal buffers needed (e.g., recent lags, error history, smoothing components)
• Composition is possible: The standard interface enables forecasters to be used interchangeably within evaluation pipelines and feature-engineering pipelines

The Forecaster class inherits from base.Estimator and marks itself as supervised (_supervised = True), placing it within River's broader estimator taxonomy.

Usage

Understand this interface when:

• You are implementing a new online forecasting model in River
• You want to understand the contract that all forecasters must satisfy
• You are building evaluation or composition pipelines that operate on arbitrary forecasters
• You need to switch between different forecasting models without changing calling code

Theoretical Basis

The Online Learning Paradigm for Time Series

In batch time series forecasting, a model is trained on an entire historical dataset and then used to produce forecasts. In contrast, online time series forecasting processes data one observation at a time:

for t = 1, 2, 3, ...:
    1. (Optional) Produce forecast: hat{y}_{t+1}, ..., hat{y}_{t+h} = model.forecast(h)
    2. Observe true value: y_t (and optional features x_t)
    3. Update model: model.learn_one(y_t, x_t)

This paradigm has several advantages:

• Constant-time updates: Each learn_one call performs O(1) work (or at worst O(p + q) for SNARIMAX with lag orders p and q)
• Bounded memory: The model never stores the full history, only a fixed-size buffer
• Continuous adaptation: The model naturally tracks changes in the data distribution (concept drift) without explicit retraining

The learn_one Contract

The abstract method signature is:

@abc.abstractmethod
def learn_one(self, y: float, x: dict | None = None) -> None:
    """Updates the model.

    Parameters
    ----------
    y
        In the literature this is called the endogenous variable.
    x
        Optional additional features to learn from. In the literature these
        are called the exogenous variables.
    """
    raise NotImplementedError

Key aspects of this contract:

• y is a scalar float: Time series forecasters operate on univariate series
• x is optional: Exogenous features are supported but not required
• Returns None: The method modifies internal state in-place; there is no return value
• Must be called in temporal order: The caller is responsible for providing observations sequentially

How Concrete Implementations Satisfy the Contract

Each forecaster implements learn_one differently based on its internal model:

• SNARIMAX.learn_one: Differences the series, constructs lag/error features, computes prediction error, updates error buffer, and trains the internal regressor via regressor.learn_one(features, y_diff)
• HoltWinters.learn_one: Updates level, trend, and seasonal components using exponential smoothing equations; during the warmup phase, accumulates initial values for component initialization

Related Pages

• Implementation:Online_ml_River_Forecaster_Learn_One