Implementation:Online ml River Linear Model LinearRegression
| Knowledge Sources | Domains | Last Updated |
|---|---|---|
| River River Docs | Online Machine Learning, Linear Models, Stochastic Gradient Descent | 2026-02-08 16:00 GMT |
Overview
Concrete tool for performing online linear regression via stochastic gradient descent, used as the default internal regressor for SNARIMAX time series forecasting. Wrapper Doc documenting LinearRegression in the context of SNARIMAX usage.
Description
The linear_model.LinearRegression class implements an online linear regression model that updates its weights incrementally using stochastic gradient descent. It inherits from linear_model.base.GLM (Generalized Linear Model) and base.MiniBatchRegressor, supporting both single-instance and mini-batch learning.
In the SNARIMAX context, this class is the default regressor (wrapped in a StandardScaler pipeline). It receives feature vectors constructed from AR lags, MA errors, seasonal AR lags, and seasonal MA errors, and learns to predict the differenced target series. The weights of the linear regression directly correspond to the autoregressive and moving average coefficients of the SNARIMAX model.
The model supports L1/L2 regularization, configurable optimizers, gradient clipping, and custom weight initialization schemes.
Usage
Import linear_model.LinearRegression when you need an online regressor for SNARIMAX (or any other River model that requires an incremental regressor). The default SNARIMAX configuration creates one automatically, but you can provide a custom-configured instance.
Code Reference
Source Location
river/linear_model/lin_reg.py:L9-L175
Signature
class LinearRegression(linear_model.base.GLM, base.MiniBatchRegressor):
def __init__(
self,
optimizer: optim.base.Optimizer | None = None,
loss: optim.losses.RegressionLoss | None = None,
l2=0.0,
l1=0.0,
intercept_init=0.0,
intercept_lr: float | optim.base.Scheduler = 0.01,
clip_gradient=1e12,
initializer: optim.base.Initializer | None = None,
)
Key Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| optimizer | Optimizer or None | SGD(0.01) | Sequential optimizer for weight updates |
| loss | RegressionLoss or None | Squared() | Loss function to optimize (squared error by default) |
| l2 | float | 0.0 | L2 (Ridge) regularization strength |
| l1 | float | 0.0 | L1 (Lasso) regularization strength |
| intercept_init | float | 0.0 | Initial value for the intercept term |
| intercept_lr | float or Scheduler | 0.01 | Learning rate for the intercept; set to 0 to disable intercept updates |
| clip_gradient | float | 1e12 | Maximum absolute value for gradient clipping |
| initializer | Initializer or None | Zeros() | Weight initialization scheme |
Methods
def learn_one(self, x: dict, y: float) -> None
def predict_one(self, x: dict) -> float
def learn_many(self, X: pd.DataFrame, y: pd.Series) -> None
def predict_many(self, X: pd.DataFrame) -> pd.Series
def debug_one(self, x: dict, decimals: int = 5) -> str
Import
from river import linear_model
I/O Contract
Inputs
| Method | Parameter | Type | Description |
|---|---|---|---|
| learn_one | x | dict | Feature dictionary mapping feature names to numeric values |
| learn_one | y | float | Target value |
| predict_one | x | dict | Feature dictionary for prediction |
Outputs
| Method | Return Type | Description |
|---|---|---|
| learn_one | None | Updates weights in-place via SGD |
| predict_one | float | Predicted value: w^T * x + intercept |
In SNARIMAX Context
| Role | Features (x) | Target (y) |
|---|---|---|
| Default SNARIMAX regressor | Constructed lags and errors: {"y-1": ..., "y-2": ..., "e-1": ..., "sy-12": ..., "se-12": ...} |
Differenced series value y'_t
|
Usage Examples
Default SNARIMAX regressor (implicit)
from river import time_series
# LinearRegression is used internally as the default regressor
# The actual default is: StandardScaler() | LinearRegression()
model = time_series.SNARIMAX(p=12, d=1, q=12, m=12, sd=1)
Custom LinearRegression for SNARIMAX
from river import linear_model, optim, preprocessing, time_series
# Customize the regressor with different learning rate and regularization
custom_regressor = (
preprocessing.StandardScaler()
| linear_model.LinearRegression(
optimizer=optim.SGD(0.005),
l2=0.001,
intercept_lr=0.1,
)
)
model = time_series.SNARIMAX(
p=12, d=1, q=12, m=12, sd=1,
regressor=custom_regressor,
)
Standalone LinearRegression
from river import linear_model, preprocessing
model = preprocessing.StandardScaler() | linear_model.LinearRegression(intercept_lr=0.1)
# Single-instance learning
model.learn_one({"feature_a": 1.0, "feature_b": 2.0}, 3.5)
prediction = model.predict_one({"feature_a": 1.5, "feature_b": 2.5})
Inspecting weights with debug_one
from river import datasets, evaluate, linear_model, metrics, preprocessing
dataset = datasets.TrumpApproval()
model = preprocessing.StandardScaler() | linear_model.LinearRegression(intercept_lr=0.1)
metric = metrics.MAE()
evaluate.progressive_val_score(dataset, model, metric)
# Inspect how each feature contributes to a prediction
x, y = next(iter(dataset))
report = model.debug_one(x)
print(report)