Implementation:Online ml River Time Series SNARIMAX

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

Overview

Concrete tool for performing online SNARIMAX (Seasonal Non-linear AutoRegressive Integrated Moving Average with eXogenous inputs) time series forecasting in River.

Description

The time_series.SNARIMAX class implements a fully online version of the ARIMA model family with seasonal and exogenous extensions. It constructs feature vectors from lagged target values (AR), past forecast errors (MA), and their seasonal counterparts, then feeds these features to an online regressor. Differencing is applied before learning and undone during forecasting.

The model maintains three internal deques:

y_hist: Raw target history for differencing/undifferencing
y_diff: Differenced target history for AR features
errors: Past prediction errors for MA features

The default regressor is preprocessing.StandardScaler() | linear_model.LinearRegression(), but any River regressor or pipeline can be substituted.

Usage

Import time_series.SNARIMAX when you need an online ARIMA-family forecaster that can handle trend, seasonality, and exogenous inputs in a streaming setting.

Code Reference

Source Location

river/time_series/snarimax.py:L98-L375

Signature

class SNARIMAX(Forecaster):
    def __init__(
        self,
        p: int,
        d: int,
        q: int,
        m: int = 1,
        sp: int = 0,
        sd: int = 0,
        sq: int = 0,
        regressor: base.Regressor | compose.Pipeline | None = None,
    )

Key Parameters

Parameter	Type	Default	Description
p	int	(required)	Order of the autoregressive part (number of past target lags)
d	int	(required)	Differencing order for stationarity
q	int	(required)	Order of the moving average part (number of past error lags)
m	int	1	Seasonal period length (e.g., 12 for monthly data with yearly seasonality)
sp	int	0	Seasonal autoregressive order
sd	int	0	Seasonal differencing order
sq	int	0	Seasonal moving average order
regressor	Regressor / Pipeline / None	LinearRegression	Online regressor for learning the mapping from features to differenced target

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 (endogenous variable)
learn_one	x	dict or None	Optional exogenous features
forecast	horizon	int	Number of steps ahead to forecast
forecast	xs	list[dict] or None	Optional exogenous features for each future step (length must equal horizon)

Outputs

Method	Return Type	Description
learn_one	None	Updates internal state in-place
forecast	list[float]	Predicted values for each of the horizon future steps

Usage Examples

Basic SNARIMAX on AirlinePassengers

import datetime as dt
from river import datasets
from river import time_series

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

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

horizon = 12
forecast = model.forecast(horizon=horizon)
for m in range(1, horizon + 1):
    print(f"1961-{m:02d}-01: {forecast[m-1]:.3f}")

SNARIMAX with custom regressor and exogenous features

import calendar
import math
from river import compose, datasets, linear_model, optim, preprocessing, time_series

def get_month_distances(x):
    return {
        calendar.month_name[month]: math.exp(-(x["month"].month - month) ** 2)
        for month in range(1, 13)
    }

def get_ordinal_date(x):
    return {"ordinal_date": x["month"].toordinal()}

extract_features = compose.TransformerUnion(get_ordinal_date, get_month_distances)

model = (
    extract_features
    | time_series.SNARIMAX(
        p=1,
        d=0,
        q=0,
        m=12,
        sp=3,
        sq=6,
        regressor=(
            preprocessing.StandardScaler()
            | linear_model.LinearRegression(
                intercept_init=110,
                optimizer=optim.SGD(0.01),
                intercept_lr=0.3,
            )
        ),
    )
)

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

forecast = model.forecast(horizon=12)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment