Skip to content

GUM

Jump to bottom
Ivan Svetunkov edited this page Jun 16, 2026 · 7 revisions

GUM - Generalised Univariate Model

GUM (Generalised Univariate Model) is a flexible state-space model that allows custom specification of the transition matrix F, measurement vector w, and persistence vector g.

R-only. GUM is not yet ported to Python — see Roadmap.

Function signature (R)

gum(y, orders = c(1, 1), lags = c(1, frequency(y)),
    type = c("additive", "multiplicative"),
    initial = c("backcasting", "optimal", "two-stage", "complete"),
    persistence = NULL, transition = NULL,
    measurement = rep(1, sum(orders)),
    loss = c("likelihood", "MSE", "MAE", "HAM",
             "MSEh", "TMSE", "GTMSE", "MSCE", "GPL"),
    h = 0, holdout = FALSE,
    bounds = c("usual", "admissible", "none"),
    silent = TRUE,
    model = NULL, xreg = NULL,
    regressors = c("use", "select", "adapt", "integrate"),
    initialX = NULL, ...)

Overview

GUM provides maximum flexibility for state-space modeling when standard ETS or CES specifications are too restrictive. You can specify:

  • Custom orders (number of states per lag)
  • Custom lags
  • Custom transition, measurement, and persistence matrices values (or leave them to the estimator)

Mathematical Form

This is formulated as an additive SSOE state space model, in the ADAM framework:

yₜ = wₜ' vₜ₋ₗ + εₜ
vₜ = F vₜ₋ₗ + gₜ εₜ

Where:

  • vₜ: State vector (defined by orders)
  • l: Vector of lags
  • wₜ: Measurement vector (can include fixed elements and regressors)
  • F: Transition matrix (by default, estimated)
  • gₜ: Persistence vector (by default, estimated)
  • εₜ: Error term

The multiplicative GUM is just the additive one applied to the data in logarithms.

R Usage

library(smooth)

# Basic GUM with default settings
gum(BJsales, h=8, holdout=TRUE)

# Custom orders and lags
gum(y, orders=c(2,1), lags=c(1,4), h=18, holdout=TRUE)

# More complex structure
gum(y, orders=c(1,1,1), lags=c(1,3,5), h=18, holdout=TRUE)

# Reuse previous model on new data
model1 <- gum(y1, orders=c(2,1), lags=c(1,4))
gum(y2, model=model1, h=18)

# With trace forecast error loss
gum(y, orders=c(1), lags=c(1), h=18, holdout=TRUE, loss="TMSE")

Automatic Order Selection

Note: This is currently implemented for testing purposes. The proper selection might require more work, which has not been yet done for the GUM.

# Automatic selection
auto.gum(y, h=12, holdout=TRUE)

# With maximum order and lag
auto.gum(y, orders=3, lags=12)

# Select between additive and multiplicative
auto.gum(y, type="select")

Parameters

R-only. GUM is not yet ported to Python — see Roadmap. All parameters below are R-side only.

Parameter Type Default Description
y vector/ts — Time series data.
orders numeric vector c(1, 1) Number of states per lag.
lags numeric vector c(1, frequency(y)) Lags for each order.
type character "additive" Model type.
persistence numeric vector NULL Fixed persistence g.
transition matrix NULL Fixed transition F.
measurement numeric vector rep(1, sum(orders)) Measurement vector w.
initial character "backcasting" Initialisation method.
loss character "likelihood" Loss function.
h integer 0 Forecast horizon.
holdout logical FALSE Use holdout validation.
bounds character "admissible" Parameter bounds.
xreg matrix NULL Explanatory variables (regressors).
regressors character "use" How to handle regressors.

Orders and Lags

The orders vector specifies how many states to use for each lag:

# 2 states at lag 1, 1 state at lag 12
orders = c(2, 1)
lags = c(1, 12)
# Total states: 2 + 1 = 3

Model Types

  • "additive": Standard additive model
  • "multiplicative": Model fitted on log-transformed data

For auto.gum(), use type="select" for automatic selection.

Custom Components

You can provide custom transition, measurement, and persistence:

# Custom persistence
gum(y, orders=c(2), lags=c(1), persistence=c(0.5, 0.3))

# Custom transition matrix
F <- matrix(c(1, 0, 1, 1), 2, 2)
gum(y, orders=c(2), lags=c(1), transition=F)

# Custom measurement vector
gum(y, orders=c(2), lags=c(1), measurement=c(1, 0.5))

With Explanatory Variables

# Basic GUMX
gum(y, orders=c(1,1), lags=c(1,4), xreg=X)

# Automatic regressor selection
gum(y, orders=c(1,1), lags=c(1,4), xreg=X, regressors="select")

# Adaptive regressors
gum(y, orders=c(1,1), lags=c(1,4), xreg=X, regressors="adapt")

# Integrated regressors
gum(y, orders=c(1,1), lags=c(1,4), xreg=X, regressors="integrate")

Output

Returns an object of class "adam" containing (R only):

Element Type (R) Description
model character Model name
orders numeric vector Order specification
lags numeric vector Lag specification
transition matrix Transition matrix F
persistence numeric vector Persistence vector g
measurement numeric vector Measurement vector w
states matrix State matrix
fitted vector Fitted values
forecast vector Point forecasts
residuals vector Model residuals
logLik numeric Log-likelihood value
initial vector Initial state values

Optimization Details

GUM uses two optimizers sequentially:

  1. Initial optimization: BOBYQA (algorithm0="NLOPT_LN_BOBYQA")
  2. Refinement: Nelder-Mead (algorithm="NLOPT_LN_NELDERMEAD")

Custom settings:

gum(y, orders=c(1,1), lags=c(1,4),
    algorithm0="NLOPT_LN_BOBYQA",
    algorithm="NLOPT_LN_SBPLX",
    maxeval0=200,
    maxeval=400)

Relationship to Other Models

GUM underlies several dynamic models:

  • ETS
  • ARIMA
  • CES

Use GUM when:

  • Standard models don't fit well
  • You have domain knowledge about state structure
  • You need non-standard lag structures
  • You have long histories of data and enough time to fool around

References

See Also

Related Functions

  • ADAM - Unified framework
  • CES - Complex Exponential Smoothing
  • ES - Standard Exponential Smoothing

Parameter Documentation

Clone this wiki locally