Skip to content

Explanatory Variables

Jump to bottom
Ivan Svetunkov edited this page Jan 30, 2026 · 7 revisions

Explanatory Variables

This page documents how to include external regressors (explanatory variables) in smooth models.

Note: This is not yet supported in Python.

Read more about the implementation in ADAM and different options in Chapter 10 of Svetunkov (2023).

Overview

Smooth models support explanatory variables (exogenous regressors) that can improve forecasts when external factors influence the time series. This creates models like ETSX (ETS with regressors) or ARIMAX (ARIMA with regressors).

Parameters for Explanatory Variables

Parameter Type (R) Type (Python) Description
formula formula - R formula for variable relationships
xreg matrix/data.frame - External regressors matrix
regressors character - How to handle regressors: "use", "select", "adapt"

Using formula (R)

The formula parameter allows specifying relationships between the response and explanatory variables using R's formula syntax. This only works with adam().

Basic Usage

# Data with explanatory variables
data <- cbind(y, x1, x2, x3)

# Use all variables
model <- adam(data, model="AAN", formula=y ~ x1 + x2 + x3)

# Use subset of variables
model <- adam(data, model="AAN", formula=y ~ x1 + x2)

# Include deterministic trend. Generated automatically, no need to have it in the data.
model <- adam(data, model="AAN", formula=y ~ x1 + x2 + trend)

Special Terms

Term Description
trend Adds a global deterministic trend to the model
. All variables in the data
-1 Remove intercept 
# All variables plus trend
model <- adam(data, model="AAN", formula=y ~ . + trend)

# Without specific variable
model <- adam(data, model="AAN", formula=y ~ . - x3)

Using xreg

For simpler cases, the xreg parameter accepts a matrix of explanatory variables directly. This is implemented in es(), ssarima(), msarima(), ces(), and gum().

R Usage

# Create regressor matrix
X <- cbind(promo=promo_data, holiday=holiday_dummy)

# ETS with regressors
model <- es(y, model="AAN", xreg=X)

# ARIMA with regressors
model <- ssarima(y, orders=c(1,1,1), xreg=X)

Notes on xreg

  • Columns should contain variables, rows should contain observations
  • Number of rows should equal either in-sample size or total series length
  • If xreg has only in-sample observations, holdout values are extrapolated using ES during the forecasting step
  • For forecasting, new xreg values must be provided via newdata parameter in forecast()

The regressors Parameter

The regressors parameter controls how explanatory variables are treated:

Value Description Use Case
"use" Use all provided regressors as-is When you're confident in your variable selection
"select" Select regressors based on information criterion When unsure which variables are useful
"adapt" Make regressor coefficients time-varying When relationships change over time

Regressor Selection

# Automatic selection of regressors
model <- adam(data, model="AAN", formula=y ~ x1 + x2 + x3, regressors="select")

# Check which were selected
coef(model)

Adaptive Regressors

With regressors="adapt", the coefficients of explanatory variables are updated over time using a smoothing mechanism similar to ETS states:

# Time-varying coefficients
model <- adam(data, model="AAN", formula=y ~ x1 + x2, regressors="adapt")

This is useful when the effect of a regressor changes over time (e.g., price elasticity varying with market conditions).

Providing Initial Values

In R

# Provide initial values for regressor coefficients
model <- adam(data, model="AAN", formula=y ~ x1 + x2,
              initial=list(xreg=c(0.5, -0.3)))

For ES

# Initial values for xreg in ES
model <- es(y, model="AAN", xreg=X, initialX=c(0.5, -0.3))

formula() Method

The formula() method extracts the formula used for explanatory variables.

R Usage

model <- adam(data, model="AAN", formula=y ~ x1 + x2)
formula(model)
# y ~ x1 + x2

For models without explicit formula, a decorative formula showing the measurement equation is returned.

Forecasting with Explanatory Variables

When forecasting, future values of explanatory variables must be provided:

R

# Fit model
model <- adam(data, model="AAN", formula=y ~ x1 + x2)

# Forecast with new regressor values
new_data <- data.frame(x1=new_x1, x2=new_x2)
fc <- forecast(model, h=12, newdata=new_data)

Support by Function

Function formula xreg regressors
ADAM Yes NA ("use", "select", "adapt")
ES NA Yes ("use", "select")
SSARIMA NA Yes ("use", "select", "adapt")
MSARIMA NA Yes ("use", "select", "adapt")
CES NA Yes ("use", "select")
GUM NA Yes ("use", "select", "adapt", "integrate")

GUM Special Option

GUM supports an additional regressors="integrate" option, which applies integrated updating to the explanatory variables parameters. In that case, the transition matrix for the regressors will be estimated.

Python Support

Feature R Python
formula Yes TBA
xreg Yes TBA
regressors Yes TBA
Forecasting with X Yes TBA

Best Practices

  1. Variable selection: Start with regressors="select" if unsure which variables are useful
  2. Adaptive coefficients: Use regressors="adapt" when relationships might change over time
  3. Future values: Ensure you have reliable forecasts or known values for regressors for the holdout period
  4. Multicollinearity: Check for correlation among regressors; selection can help here

References

  • Svetunkov, I. (2023). Forecasting and Analytics with the Augmented Dynamic Adaptive Model (ADAM). Online book: https://openforecast.org/adam/
  • Hyndman, R.J., et al. (2008). Forecasting with Exponential Smoothing: The State Space Approach. Springer.

See Also

Clone this wiki locally