modeltime (version 0.4.0)

exp_smoothing: General Interface for Exponential Smoothing State Space Models

Description

exp_smoothing() is a way to generate a specification of an Exponential Smoothing model before fitting and allows the model to be created using different packages. Currently the only package is forecast.

Usage

exp_smoothing(
  mode = "regression",
  seasonal_period = NULL,
  error = NULL,
  trend = NULL,
  season = NULL,
  damping = NULL
)

Arguments

mode

A single character string for the type of model. The only possible value for this model is "regression".

seasonal_period

A seasonal frequency. Uses "auto" by default. A character phrase of "auto" or time-based phrase of "2 weeks" can be used if a date or date-time variable is provided. See Fit Details below.

error

The form of the error term: "auto", "additive", or "multiplicative". If the error is multiplicative, the data must be non-negative.

trend

The form of the trend term: "auto", "additive", "multiplicative" or "none".

season

The form of the seasonal term: "auto", "additive", "multiplicative" or "none"..

damping

Apply damping to a trend: "auto", "damped", or "none".

Engine Details

The standardized parameter names in modeltime can be mapped to their original names in each engine:

modeltime	forecast::ets
seasonal_period()	ts(frequency)
error(), trend(), season()	model ('ZZZ')
damping()	damped (NULL)

Other options can be set using set_engine().

ets (default engine)

The engine uses forecast::ets().

Function Parameters:

## function (y, model = "ZZZ", damped = NULL, alpha = NULL, beta = NULL, gamma = NULL, 
##     phi = NULL, additive.only = FALSE, lambda = NULL, biasadj = FALSE, 
##     lower = c(rep(1e-04, 3), 0.8), upper = c(rep(0.9999, 3), 0.98), opt.crit = c("lik", 
##         "amse", "mse", "sigma", "mae"), nmse = 3, bounds = c("both", "usual", 
##         "admissible"), ic = c("aicc", "aic", "bic"), restrict = TRUE, allow.multiplicative.trend = FALSE, 
##     use.initial.values = FALSE, na.action = c("na.contiguous", "na.interp", 
##         "na.fail"), ...)

The main arguments are model and damped are defined using:

• error() = "auto", "additive", and "multiplicative" are converted to "Z", "A", and "M"

• trend() = "auto", "additive", "multiplicative", and "none" are converted to "Z","A","M" and "N"

• season() = "auto", "additive", "multiplicative", and "none" are converted to "Z","A","M" and "N"

• damping() - "auto", "damped", "none" are converted to NULL, TRUE, FALSE

By default, all arguments are set to "auto" to perform automated Exponential Smoothing using in-sample data following the underlying forecast::ets() automation routine.

Other options and argument can be set using set_engine().

Parameter Notes:

• xreg - This model is not set up to use exogenous regressors. Only univariate models will be fit.

Fit Details

Date and Date-Time Variable

It's a requirement to have a date or date-time variable as a predictor. The fit() interface accepts date and date-time features and handles them internally.

• fit(y ~ date)

Seasonal Period Specification

The period can be non-seasonal (seasonal_period = 1 or "none") or seasonal (e.g. seasonal_period = 12 or seasonal_period = "12 months"). There are 3 ways to specify:

1. seasonal_period = "auto": A period is selected based on the periodicity of the data (e.g. 12 if monthly)

2. seasonal_period = 12: A numeric frequency. For example, 12 is common for monthly data

3. seasonal_period = "1 year": A time-based phrase. For example, "1 year" would convert to 12 for monthly data.

Univariate:

For univariate analysis, you must include a date or date-time feature. Simply use:

• Formula Interface (recommended): fit(y ~ date) will ignore xreg's.

• XY Interface: fit_xy(x = data[,"date"], y = data$y) will ignore xreg's.

Multivariate (xregs, Exogenous Regressors)

This model is not set up for use with exogenous regressors.

Details

The data given to the function are not saved and are only used to determine the mode of the model. For exp_smoothing(), the mode will always be "regression".

The model can be created using the fit() function using the following engines:

• "ets" (default) - Connects to forecast::ets()

See Also

fit.model_spec(), set_engine()

Examples

# NOT RUN {
library(dplyr)
library(parsnip)
library(rsample)
library(timetk)
library(modeltime)

# Data
m750 <- m4_monthly %>% filter(id == "M750")
m750

# Split Data 80/20
splits <- initial_time_split(m750, prop = 0.8)

# ---- AUTO ETS ----

# Model Spec - The default parameters are all set
# to "auto" if none are provided
model_spec <- exp_smoothing() %>%
    set_engine("ets")

# Fit Spec
model_fit <- model_spec %>%
    fit(log(value) ~ date, data = training(splits))
model_fit


# ---- STANDARD ETS ----

# Model Spec
model_spec <- exp_smoothing(
        seasonal_period  = 12,
        error            = "multiplicative",
        trend            = "additive",
        season           = "multiplicative"
    ) %>%
    set_engine("ets")

# Fit Spec
model_fit <- model_spec %>%
    fit(log(value) ~ date, data = training(splits))
model_fit

# }