Workflow:Online ml River Time Series Forecasting
| Knowledge Sources | |
|---|---|
| Domains | Online_ML, Time_Series, Forecasting, Streaming_Data |
| Last Updated | 2026-02-08 16:00 GMT |
Overview
End-to-end process for online time series forecasting using incremental models that learn from each new observation and produce multi-step-ahead predictions.
Description
This workflow covers the procedure for forecasting future values in a time series using models that update incrementally. River provides SNARIMAX (a generalized online ARIMA variant supporting Seasonal, Non-linear, Auto-Regressive, Integrated, Moving Average, and eXogenous components) and Holt-Winters exponential smoothing. The process includes data ingestion, model configuration with appropriate lag structure, incremental training, multi-horizon forecasting, and evaluation using time-series-specific metrics and evaluation protocols.
Usage
Execute this workflow when you have a time series (single variable observed over time) and need to predict future values in an online fashion. Typical applications include demand forecasting, sensor readings prediction, financial time series, and any sequential data where the model must adapt to new observations as they arrive. Use this when batch retraining is impractical or when the time series exhibits non-stationarity.
Execution Steps
Step 1: Load or Connect to a Time Series Stream
Obtain a time series as a sequence of (timestamp, value) or simply a sequence of values. River provides built-in time series datasets: AirlinePassengers (144 monthly counts with trend and seasonality) and WaterFlow (1,268 hourly flow measurements). For custom data, any iterable of numeric values can serve as input.
Key considerations:
- Time series datasets yield individual numeric values sequentially
- AirlinePassengers exhibits clear trend and seasonal patterns
- WaterFlow provides a longer series for testing adaptation
- External features (exogenous variables) can be included for SNARIMAX
Step 2: Select and Configure the Forecasting Model
Choose between SNARIMAX and Holt-Winters based on the time series characteristics. SNARIMAX is a flexible model that wraps any River regressor and creates features from lagged values, differences, moving average errors, seasonal components, and exogenous variables. Holt-Winters provides classical exponential smoothing with optional trend and seasonality components.
SNARIMAX configuration:
- p (order): Number of autoregressive lags
- d (differencing): Order of differencing for non-stationarity
- q (MA terms): Number of moving average error lags
- sp, sd, sq: Seasonal counterparts with configurable period (m)
- regressor: Any River regression model (default: LinearRegression)
Holt-Winters configuration:
- seasonality: Period of the seasonal component
- multiplicative: Whether trend/seasonality are multiplicative or additive
- alpha, beta, gamma: Smoothing parameters for level, trend, and seasonality
Step 3: Train the Model Incrementally
Feed each new observation to the model using learn_one(y) (or learn_one(y, x) when exogenous features are present). The model updates its internal state: autoregressive coefficients, moving average buffers, seasonal indices, and the underlying regressor weights. No batch reprocessing is needed.
Key considerations:
- learn_one(y) updates the model with a single new value
- The model maintains a buffer of recent values for autoregressive features
- Differencing is applied automatically based on the configured d and sd parameters
- Initial predictions are available after enough observations to fill the lag window
Step 4: Produce Multi-step Forecasts
Generate forecasts for one or more steps ahead using forecast(horizon=h). The model produces h future value predictions by iteratively applying the model, using its own predictions as future autoregressive inputs. This recursive forecasting naturally propagates uncertainty forward.
Key considerations:
- forecast(horizon=1) gives one-step-ahead prediction
- Multi-step forecasts use recursive prediction (predicted values become future lags)
- Forecast accuracy typically degrades with increasing horizon
- Exogenous features for future steps must be provided if using external regressors
Step 5: Evaluate Forecast Accuracy
Use time series-specific evaluation to assess model quality. River provides time_series.evaluate that implements a proper train-then-predict protocol: for each time step, forecast h steps ahead, then update the model. Metrics include MAE, MSE, RMSE, and SMAPE computed at each forecast horizon.
Key considerations:
- time_series.evaluate performs rolling-origin evaluation
- The evaluation protocol prevents data leakage in time-ordered data
- Horizon-specific errors reveal how accuracy degrades with forecast distance
- Compare against naive baselines (e.g., repeat last value)
Step 6: Adapt to Evolving Patterns
As new data arrives, the model continuously adapts its parameters. For SNARIMAX with online regressors, the underlying model weights track changing patterns. For Holt-Winters, exponential smoothing naturally down-weights older observations. Monitor forecast errors over time to detect if the model is capturing structural changes.
Key considerations:
- Online models naturally adapt to level shifts and trend changes
- Seasonal patterns are tracked through periodic lag features or Holt-Winters seasonality
- Sudden structural breaks may require resetting the model
- The learning rate of the underlying regressor controls adaptation speed