Implementation:Online ml River Time Series HoltWinters

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

Overview

Concrete tool for performing online Holt-Winters (Triple Exponential Smoothing) time series forecasting in River.

Description

The time_series.HoltWinters class implements the Holt-Winters exponential smoothing method for online time series forecasting. It decomposes the series into level, trend, and seasonal components, each updated incrementally as new observations arrive. The class supports both additive and multiplicative seasonality formulations.

Internally, each component is represented as a specialized deque subclass:

• AdditiveLevel / MultiplicativeLevel: Tracks the smoothed baseline
• Trend: Tracks the smoothed slope (optional, controlled by beta)
• AdditiveSeason / MultiplicativeSeason: Tracks per-period seasonal factors (optional, controlled by gamma and seasonality)

The first k = max(2, seasonality) observations are used for initialization. After initialization, each call to learn_one performs constant-time updates of all active components.

Usage

Import time_series.HoltWinters when you need an online exponential smoothing forecaster with configurable trend and seasonal components.

Code Reference

Source Location

river/time_series/holt_winters.py:L72-L222

Signature

class HoltWinters(Forecaster):
    def __init__(
        self,
        alpha,
        beta=None,
        gamma=None,
        seasonality=0,
        multiplicative=False,
    )

Key Parameters

Parameter	Type	Default	Description
alpha	float	(required)	Smoothing parameter for the level component (0 < alpha < 1)
beta	float or None	None	Smoothing parameter for the trend component; None disables trend
gamma	float or None	None	Smoothing parameter for the seasonal component; None disables seasonality
seasonality	int	0	Number of periods in one season (e.g., 12 for monthly data with yearly cycle)
multiplicative	bool	False	If True, uses multiplicative seasonality; otherwise additive

Methods

def learn_one(self, y: float, x: dict | None = None) -> None
def forecast(self, horizon: int, xs: list[dict] | None = None) -> list[float]

Import

from river import time_series

I/O Contract

Inputs

Method	Parameter	Type	Description
learn_one	y	float	The current observation
learn_one	x	dict or None	Optional exogenous features (not used by HoltWinters but accepted for interface compatibility)
forecast	horizon	int	Number of steps ahead to forecast
forecast	xs	list[dict] or None	Optional future exogenous features (not used by HoltWinters)

Outputs

Method	Return Type	Description
learn_one	None	Updates level, trend, and seasonal components in-place
forecast	list[float]	Predicted values for each of the horizon future steps

Usage Examples

Multiplicative HoltWinters on AirlinePassengers

from river import datasets
from river import metrics
from river import time_series

dataset = datasets.AirlinePassengers()

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

metric = metrics.MAE()

time_series.evaluate(
    dataset,
    model,
    metric,
    horizon=12,
)
# +1  MAE: 25.899087
# +2  MAE: 26.26131
# ...
# +12 MAE: 33.975057

Simple Exponential Smoothing (no trend, no seasonality)

from river import time_series

model = time_series.HoltWinters(alpha=0.1)

# Only level component is active
for y in [112, 118, 132, 129, 121, 135, 148, 148]:
    model.learn_one(y)

forecast = model.forecast(horizon=3)
# Returns a flat forecast since there is no trend or seasonality

Holt's Linear Trend (no seasonality)

from river import time_series

model = time_series.HoltWinters(alpha=0.3, beta=0.1)

for y in [112, 118, 132, 129, 121, 135, 148, 148]:
    model.learn_one(y)

forecast = model.forecast(horizon=5)
# Returns a linearly increasing/decreasing forecast based on trend

Related Pages

• Principle:Online_ml_River_Holt_Winters_Forecasting