modeltime (version 0.4.0)

seasonal_reg: General Interface for Multiple Seasonality Regression Models (TBATS, STLM)

Description

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

Usage

seasonal_reg(
  mode = "regression",
  seasonal_period_1 = NULL,
  seasonal_period_2 = NULL,
  seasonal_period_3 = NULL
)

Arguments

mode

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

seasonal_period_1

(required) The primary 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.

seasonal_period_2

(optional) A second seasonal frequency. Is NULL 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.

seasonal_period_3

(optional) A third seasonal frequency. Is NULL 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.

Engine Details

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

modeltime	forecast::stlm	forecast::tbats
seasonal_period_1, seasonal_period_2, seasonal_period_3	msts(seasonal.periods)	msts(seasonal.periods)

Other options can be set using set_engine().

The engines use forecast::stlm().

Function Parameters:

## function (y, s.window = 13, robust = FALSE, method = c("ets", "arima"), 
##     modelfunction = NULL, model = NULL, etsmodel = "ZZN", lambda = NULL, 
##     biasadj = FALSE, xreg = NULL, allow.multiplicative.trend = FALSE, x = y, 
##     ...)

tbats

• Method: Uses method = "tbats", which by default is auto-TBATS.

• Xregs: Univariate. Cannot accept Exogenous Regressors (xregs). Xregs are ignored.

stlm_ets

• Method: Uses method = "stlm_ets", which by default is auto-ETS.

• Xregs: Univariate. Cannot accept Exogenous Regressors (xregs). Xregs are ignored.

stlm_arima

• Method: Uses method = "stlm_arima", which by default is auto-ARIMA.

• Xregs: Multivariate. Can accept Exogenous Regressors (xregs).

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 yearly seasonal (e.g. For monthly time stamps, seasonal_period = 12, seasonal_period = "12 months", or seasonal_period = "yearly"). There are 3 ways to specify:

1. seasonal_period = "auto": A seasonal 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 (No xregs, Exogenous Regressors):

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)

• The tbats engine cannot accept Xregs.

• The stlm_ets engine cannot accept Xregs.

• The stlm_arima engine can accept Xregs

The xreg parameter is populated using the fit() or fit_xy() function:

• Only factor, ordered factor, and numeric data will be used as xregs.

• Date and Date-time variables are not used as xregs

• character data should be converted to factor.

Xreg Example: Suppose you have 3 features:

1. y (target)

2. date (time stamp),

3. month.lbl (labeled month as a ordered factor).

The month.lbl is an exogenous regressor that can be passed to the seasonal_reg() using fit():

• fit(y ~ date + month.lbl) will pass month.lbl on as an exogenous regressor.

• fit_xy(data[,c("date", "month.lbl")], y = data$y) will pass x, where x is a data frame containing month.lbl and the date feature. Only month.lbl will be used as an exogenous regressor.

Note that date or date-time class values are excluded from xreg.

Details

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

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

• "tbats" - Connects to forecast::tbats()

• "stlm_ets" - Connects to forecast::stlm(), method = "ets"

• "stlm_arima" - Connects to forecast::stlm(), method = "arima"

See Also

fit.model_spec(), set_engine()

Examples

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

# Data
taylor_30_min

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

# ---- STLM ETS ----

# Model Spec
model_spec <- seasonal_reg() %>%
    set_engine("stlm_ets")

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


# ---- STLM ARIMA ----

# Model Spec
model_spec <- seasonal_reg() %>%
    set_engine("stlm_arima")

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

# }