Package 'modeltime'

Description

Tuning Parameters for ADAM Models

Usage

use_constant(values = c(FALSE, TRUE))

regressors_treatment(values = c("use", "select", "adapt"))

outliers_treatment(values = c("ignore", "use", "select"))

probability_model(
  values = c("none", "auto", "fixed", "general", "odds-ratio", "inverse-odds-ratio",
    "direct")
)

distribution(
  values = c("default", "dnorm", "dlaplace", "ds", "dgnorm", "dlnorm", "dinvgauss",
    "dgamma")
)

information_criteria(values = c("AICc", "AIC", "BICc", "BIC"))

select_order(values = c(FALSE, TRUE))

Arguments

Details

The main parameters for ADAM models are:

• non_seasonal_ar: The order of the non-seasonal auto-regressive (AR) terms.

• non_seasonal_differences: The order of integration for non-seasonal differencing.

• non_seasonal_ma: The order of the non-seasonal moving average (MA) terms.

• seasonal_ar: The order of the seasonal auto-regressive (SAR) terms.

• seasonal_differences: The order of integration for seasonal differencing.

• seasonal_ma: The order of the seasonal moving average (SMA) terms.

• use_constant: Logical, determining, whether the constant is needed in the model or not.

• regressors_treatment: The variable defines what to do with the provided explanatory variables.

• outliers_treatment: Defines what to do with outliers.

• probability_model: The type of model used in probability estimation.

• distribution: What density function to assume for the error term.

• information_criteria: The information criterion to use in the model selection / combination procedure.

• select_order: If TRUE, then the function will select the most appropriate order.

Value

A dials parameter

A parameter

A parameter

A parameter

A parameter

A parameter

A parameter

A parameter

Examples

use_constant()

regressors_treatment()

distribution()

Description

adam_reg() is a way to generate a specification of an ADAM model before fitting and allows the model to be created using different packages. Currently the only package is smooth.

Usage

adam_reg(
  mode = "regression",
  ets_model = NULL,
  non_seasonal_ar = NULL,
  non_seasonal_differences = NULL,
  non_seasonal_ma = NULL,
  seasonal_ar = NULL,
  seasonal_differences = NULL,
  seasonal_ma = NULL,
  use_constant = NULL,
  regressors_treatment = NULL,
  outliers_treatment = NULL,
  outliers_ci = NULL,
  probability_model = NULL,
  distribution = NULL,
  loss = NULL,
  information_criteria = NULL,
  seasonal_period = NULL,
  select_order = NULL
)

Arguments

Details

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

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

• "auto_adam" (default) - Connects to smooth::auto.adam()

• "adam" - Connects to smooth::adam()

Main Arguments

The main arguments (tuning parameters) for the model are:

• seasonal_period: The periodic nature of the seasonality. Uses "auto" by default.

• non_seasonal_ar: The order of the non-seasonal auto-regressive (AR) terms.

• non_seasonal_differences: The order of integration for non-seasonal differencing.

• non_seasonal_ma: The order of the non-seasonal moving average (MA) terms.

• seasonal_ar: The order of the seasonal auto-regressive (SAR) terms.

• seasonal_differences: The order of integration for seasonal differencing.

• seasonal_ma: The order of the seasonal moving average (SMA) terms.

• ets_model: The type of ETS model.

• use_constant: Logical, determining, whether the constant is needed in the model or not.

• regressors_treatment: The variable defines what to do with the provided explanatory variables.

• outliers_treatment: Defines what to do with outliers.

• probability_model: The type of model used in probability estimation.

• distribution: what density function to assume for the error term.

• loss: The type of Loss Function used in optimization.

• information_criteria: The information criterion to use in the model selection / combination procedure.

These arguments are converted to their specific names at the time that the model is fit.

Other options and argument can be set using set_engine() (See Engine Details below).

If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

auto_adam (default engine)

The engine uses smooth::auto.adam().

Function Parameters:

#> function (data, model = "ZXZ", lags = c(frequency(data)), orders = list(ar = c(3, 
#>     3), i = c(2, 1), ma = c(3, 3), select = TRUE), formula = NULL, regressors = c("use", 
#>     "select", "adapt"), occurrence = c("none", "auto", "fixed", "general", 
#>     "odds-ratio", "inverse-odds-ratio", "direct"), distribution = c("dnorm", 
#>     "dlaplace", "ds", "dgnorm", "dlnorm", "dinvgauss", "dgamma"), outliers = c("ignore", 
#>     "use", "select"), level = 0.99, h = 0, holdout = FALSE, persistence = NULL, 
#>     phi = NULL, initial = c("optimal", "backcasting", "complete"), arma = NULL, 
#>     ic = c("AICc", "AIC", "BIC", "BICc"), bounds = c("usual", "admissible", 
#>         "none"), silent = TRUE, parallel = FALSE, ...)

The MAXIMUM nonseasonal ARIMA terms (max.p, max.d, max.q) and seasonal ARIMA terms (max.P, max.D, max.Q) are provided to forecast::auto.arima() via arima_reg() parameters. Other options and argument can be set using set_engine().

Parameter Notes:

• All values of nonseasonal pdq and seasonal PDQ are maximums. The smooth::auto.adam() model will select a value using these as an upper limit.

• xreg - This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

adam

The engine uses smooth::adam().

Function Parameters:

#> function (data, model = "ZXZ", lags = c(frequency(data)), orders = list(ar = c(0), 
#>     i = c(0), ma = c(0), select = FALSE), constant = FALSE, formula = NULL, 
#>     regressors = c("use", "select", "adapt"), occurrence = c("none", "auto", 
#>         "fixed", "general", "odds-ratio", "inverse-odds-ratio", "direct"), 
#>     distribution = c("default", "dnorm", "dlaplace", "ds", "dgnorm", "dlnorm", 
#>         "dinvgauss", "dgamma"), loss = c("likelihood", "MSE", "MAE", "HAM", 
#>         "LASSO", "RIDGE", "MSEh", "TMSE", "GTMSE", "MSCE"), outliers = c("ignore", 
#>         "use", "select"), level = 0.99, h = 0, holdout = FALSE, persistence = NULL, 
#>     phi = NULL, initial = c("optimal", "backcasting", "complete"), arma = NULL, 
#>     ic = c("AICc", "AIC", "BIC", "BICc"), bounds = c("usual", "admissible", 
#>         "none"), silent = TRUE, ...)

The nonseasonal ARIMA terms (orders) and seasonal ARIMA terms (orders) are provided to smooth::adam() via adam_reg() parameters. Other options and argument can be set using set_engine().

Parameter Notes:

• xreg - This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

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.

Multivariate (xregs, Exogenous Regressors)

The xreg parameter is populated using the fit() 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 arima_reg() using fit():

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

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

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(parsnip)
library(rsample)
library(timetk)
library(smooth)

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

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

# ---- AUTO ADAM ----

# Model Spec
model_spec <- adam_reg() %>%
    set_engine("auto_adam")

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


# ---- STANDARD ADAM ----

# Model Spec
model_spec <- adam_reg(
        seasonal_period          = 12,
        non_seasonal_ar          = 3,
        non_seasonal_differences = 1,
        non_seasonal_ma          = 3,
        seasonal_ar              = 1,
        seasonal_differences     = 0,
        seasonal_ma              = 1
    ) %>%
    set_engine("adam")

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

Description

Add a Model into a Modeltime Table

Usage

add_modeltime_model(object, model, location = "bottom")

Arguments

See Also

• combine_modeltime_tables(): Combine 2 or more Modeltime Tables together

• add_modeltime_model(): Adds a new row with a new model to a Modeltime Table

• drop_modeltime_model(): Drop one or more models from a Modeltime Table

• update_modeltime_description(): Updates a description for a model inside a Modeltime Table

• update_modeltime_model(): Updates a model inside a Modeltime Table

• pull_modeltime_model(): Extracts a model from a Modeltime Table

Examples

library(tidymodels)

model_fit_ets <- exp_smoothing() %>%
    set_engine("ets") %>%
    fit(value ~ date, training(m750_splits))

m750_models %>%
    add_modeltime_model(model_fit_ets)

Description

arima_boost() is a way to generate a specification of a time series model that uses boosting to improve modeling errors (residuals) on Exogenous Regressors. It works with both "automated" ARIMA (auto.arima) and standard ARIMA (arima). The main algorithms are:

• Auto ARIMA + XGBoost Errors (engine = auto_arima_xgboost, default)

• ARIMA + XGBoost Errors (engine = arima_xgboost)

Usage

arima_boost(
  mode = "regression",
  seasonal_period = NULL,
  non_seasonal_ar = NULL,
  non_seasonal_differences = NULL,
  non_seasonal_ma = NULL,
  seasonal_ar = NULL,
  seasonal_differences = NULL,
  seasonal_ma = NULL,
  mtry = NULL,
  trees = NULL,
  min_n = NULL,
  tree_depth = NULL,
  learn_rate = NULL,
  loss_reduction = NULL,
  sample_size = NULL,
  stop_iter = NULL
)

Arguments

Details

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

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

• "auto_arima_xgboost" (default) - Connects to forecast::auto.arima() and xgboost::xgb.train

• "arima_xgboost" - Connects to forecast::Arima() and xgboost::xgb.train

Main Arguments

The main arguments (tuning parameters) for the ARIMA model are:

• seasonal_period: The periodic nature of the seasonality. Uses "auto" by default.

• non_seasonal_ar: The order of the non-seasonal auto-regressive (AR) terms.

• non_seasonal_differences: The order of integration for non-seasonal differencing.

• non_seasonal_ma: The order of the non-seasonal moving average (MA) terms.

• seasonal_ar: The order of the seasonal auto-regressive (SAR) terms.

• seasonal_differences: The order of integration for seasonal differencing.

• seasonal_ma: The order of the seasonal moving average (SMA) terms.

The main arguments (tuning parameters) for the model XGBoost model are:

• mtry: The number of predictors that will be randomly sampled at each split when creating the tree models.

• trees: The number of trees contained in the ensemble.

• min_n: The minimum number of data points in a node that are required for the node to be split further.

• tree_depth: The maximum depth of the tree (i.e. number of splits).

• learn_rate: The rate at which the boosting algorithm adapts from iteration-to-iteration.

• loss_reduction: The reduction in the loss function required to split further.

• sample_size: The amount of data exposed to the fitting routine.

• stop_iter: The number of iterations without improvement before stopping.

These arguments are converted to their specific names at the time that the model is fit.

Other options and argument can be set using set_engine() (See Engine Details below).

If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

Engine Details

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

Model 1: ARIMA:

Model 2: XGBoost:

Other options can be set using set_engine().

auto_arima_xgboost (default engine)

Model 1: Auto ARIMA (forecast::auto.arima):

#> function (y, d = NA, D = NA, max.p = 5, max.q = 5, max.P = 2, max.Q = 2, 
#>     max.order = 5, max.d = 2, max.D = 1, start.p = 2, start.q = 2, start.P = 1, 
#>     start.Q = 1, stationary = FALSE, seasonal = TRUE, ic = c("aicc", "aic", 
#>         "bic"), stepwise = TRUE, nmodels = 94, trace = FALSE, approximation = (length(x) > 
#>         150 | frequency(x) > 12), method = NULL, truncate = NULL, xreg = NULL, 
#>     test = c("kpss", "adf", "pp"), test.args = list(), seasonal.test = c("seas", 
#>         "ocsb", "hegy", "ch"), seasonal.test.args = list(), allowdrift = TRUE, 
#>     allowmean = TRUE, lambda = NULL, biasadj = FALSE, parallel = FALSE, 
#>     num.cores = 2, x = y, ...)

Parameter Notes:

• All values of nonseasonal pdq and seasonal PDQ are maximums. The auto.arima will select a value using these as an upper limit.

• xreg - This should not be used since XGBoost will be doing the regression

Model 2: XGBoost (xgboost::xgb.train):

#> function (params = list(), data, nrounds, watchlist = list(), obj = NULL, 
#>     feval = NULL, verbose = 1, print_every_n = 1L, early_stopping_rounds = NULL, 
#>     maximize = NULL, save_period = NULL, save_name = "xgboost.model", xgb_model = NULL, 
#>     callbacks = list(), ...)

Parameter Notes:

• XGBoost uses a params = list() to capture. Parsnip / Modeltime automatically sends any args provided as ... inside of set_engine() to the params = list(...).

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 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 (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 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 arima_boost() 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.

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(lubridate)
library(parsnip)
library(rsample)
library(timetk)


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

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

# MODEL SPEC ----

# Set engine and boosting parameters
model_spec <- arima_boost(

    # ARIMA args
    seasonal_period = 12,
    non_seasonal_ar = 0,
    non_seasonal_differences = 1,
    non_seasonal_ma = 1,
    seasonal_ar     = 0,
    seasonal_differences = 1,
    seasonal_ma     = 1,

    # XGBoost Args
    tree_depth = 6,
    learn_rate = 0.1
) %>%
    set_engine(engine = "arima_xgboost")

# FIT ----


# Boosting - Happens by adding numeric date and month features
model_fit_boosted <- model_spec %>%
    fit(value ~ date + as.numeric(date) + month(date, label = TRUE),
        data = training(splits))

model_fit_boosted

Description

Tuning Parameters for ARIMA Models

Usage

non_seasonal_ar(range = c(0L, 5L), trans = NULL)

non_seasonal_differences(range = c(0L, 2L), trans = NULL)

non_seasonal_ma(range = c(0L, 5L), trans = NULL)

seasonal_ar(range = c(0L, 2L), trans = NULL)

seasonal_differences(range = c(0L, 1L), trans = NULL)

seasonal_ma(range = c(0L, 2L), trans = NULL)

Arguments

Details

The main parameters for ARIMA models are:

• non_seasonal_ar: The order of the non-seasonal auto-regressive (AR) terms.

• non_seasonal_differences: The order of integration for non-seasonal differencing.

• non_seasonal_ma: The order of the non-seasonal moving average (MA) terms.

• seasonal_ar: The order of the seasonal auto-regressive (SAR) terms.

• seasonal_differences: The order of integration for seasonal differencing.

• seasonal_ma: The order of the seasonal moving average (SMA) terms.

Examples

non_seasonal_ar()

non_seasonal_differences()

non_seasonal_ma()

Description

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

Usage

arima_reg(
  mode = "regression",
  seasonal_period = NULL,
  non_seasonal_ar = NULL,
  non_seasonal_differences = NULL,
  non_seasonal_ma = NULL,
  seasonal_ar = NULL,
  seasonal_differences = NULL,
  seasonal_ma = NULL
)

Arguments

Details

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

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

• "auto_arima" (default) - Connects to forecast::auto.arima()

• "arima" - Connects to forecast::Arima()

Main Arguments

The main arguments (tuning parameters) for the model are:

• seasonal_period: The periodic nature of the seasonality. Uses "auto" by default.

• non_seasonal_ar: The order of the non-seasonal auto-regressive (AR) terms.

• non_seasonal_differences: The order of integration for non-seasonal differencing.

• non_seasonal_ma: The order of the non-seasonal moving average (MA) terms.

• seasonal_ar: The order of the seasonal auto-regressive (SAR) terms.

• seasonal_differences: The order of integration for seasonal differencing.

• seasonal_ma: The order of the seasonal moving average (SMA) terms.

These arguments are converted to their specific names at the time that the model is fit.

Other options and argument can be set using set_engine() (See Engine Details below).

If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

Engine Details

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

Other options can be set using set_engine().

auto_arima (default engine)

The engine uses forecast::auto.arima().

Function Parameters:

#> function (y, d = NA, D = NA, max.p = 5, max.q = 5, max.P = 2, max.Q = 2, 
#>     max.order = 5, max.d = 2, max.D = 1, start.p = 2, start.q = 2, start.P = 1, 
#>     start.Q = 1, stationary = FALSE, seasonal = TRUE, ic = c("aicc", "aic", 
#>         "bic"), stepwise = TRUE, nmodels = 94, trace = FALSE, approximation = (length(x) > 
#>         150 | frequency(x) > 12), method = NULL, truncate = NULL, xreg = NULL, 
#>     test = c("kpss", "adf", "pp"), test.args = list(), seasonal.test = c("seas", 
#>         "ocsb", "hegy", "ch"), seasonal.test.args = list(), allowdrift = TRUE, 
#>     allowmean = TRUE, lambda = NULL, biasadj = FALSE, parallel = FALSE, 
#>     num.cores = 2, x = y, ...)

The MAXIMUM nonseasonal ARIMA terms (max.p, max.d, max.q) and seasonal ARIMA terms (max.P, max.D, max.Q) are provided to forecast::auto.arima() via arima_reg() parameters. Other options and argument can be set using set_engine().

Parameter Notes:

• All values of nonseasonal pdq and seasonal PDQ are maximums. The forecast::auto.arima() model will select a value using these as an upper limit.

• xreg - This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

arima

The engine uses forecast::Arima().

Function Parameters:

#> function (y, order = c(0, 0, 0), seasonal = c(0, 0, 0), xreg = NULL, include.mean = TRUE, 
#>     include.drift = FALSE, include.constant, lambda = model$lambda, biasadj = FALSE, 
#>     method = c("CSS-ML", "ML", "CSS"), model = NULL, x = y, ...)

The nonseasonal ARIMA terms (order) and seasonal ARIMA terms (seasonal) are provided to forecast::Arima() via arima_reg() parameters. Other options and argument can be set using set_engine().

Parameter Notes:

• xreg - This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

• method - The default is set to "ML" (Maximum Likelihood). This method is more robust at the expense of speed and possible selections may fail unit root inversion testing. Alternatively, you can add method = "CSS-ML" to evaluate Conditional Sum of Squares for starting values, then Maximium Likelihood.

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 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 arima_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.

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(parsnip)
library(rsample)
library(timetk)

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

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

# ---- AUTO ARIMA ----

# Model Spec
model_spec <- arima_reg() %>%
    set_engine("auto_arima")

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


# ---- STANDARD ARIMA ----

# Model Spec
model_spec <- arima_reg(
        seasonal_period          = 12,
        non_seasonal_ar          = 3,
        non_seasonal_differences = 1,
        non_seasonal_ma          = 3,
        seasonal_ar              = 1,
        seasonal_differences     = 0,
        seasonal_ma              = 1
    ) %>%
    set_engine("arima")

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

Description

Combine multiple Modeltime Tables into a single Modeltime Table

Usage

combine_modeltime_tables(...)

Arguments

Details

This function combines multiple Modeltime Tables.

• The .model_id will automatically be renumbered to ensure each model has a unique ID.

• Only the .model_id, .model, and .model_desc columns will be returned.

Re-Training Models on the Same Datasets

One issue can arise if your models are trained on different datasets. If your models have been trained on different datasets, you can run modeltime_refit() to train all models on the same data.

Re-Calibrating Models

If your data has been calibrated using modeltime_calibrate(), the .test and .calibration_data columns will be removed. To re-calibrate, simply run modeltime_calibrate() on the newly combined Modeltime Table.

See Also

• combine_modeltime_tables(): Combine 2 or more Modeltime Tables together

• add_modeltime_model(): Adds a new row with a new model to a Modeltime Table

• drop_modeltime_model(): Drop one or more models from a Modeltime Table

• update_modeltime_description(): Updates a description for a model inside a Modeltime Table

• update_modeltime_model(): Updates a model inside a Modeltime Table

• pull_modeltime_model(): Extracts a model from a Modeltime Table

Examples

library(tidymodels)
library(timetk)
library(dplyr)
library(lubridate)

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

splits <- time_series_split(m750, assess = "3 years", cumulative = TRUE)

model_fit_arima <- arima_reg() %>%
    set_engine("auto_arima") %>%
    fit(value ~ date, training(splits))

model_fit_prophet <- prophet_reg() %>%
    set_engine("prophet") %>%
    fit(value ~ date, training(splits))

# Multiple Modeltime Tables
model_tbl_1 <- modeltime_table(model_fit_arima)
model_tbl_2 <- modeltime_table(model_fit_prophet)

# Combine
combine_modeltime_tables(model_tbl_1, model_tbl_2)

Description

These functions are matched to the associated training functions:

• control_refit(): Used with modeltime_refit()

• control_fit_workflowset(): Used with modeltime_fit_workflowset()

• control_nested_fit(): Used with modeltime_nested_fit()

• control_nested_refit(): Used with modeltime_nested_refit()

• control_nested_forecast(): Used with modeltime_nested_forecast()

Usage

control_refit(verbose = FALSE, allow_par = FALSE, cores = 1, packages = NULL)

control_fit_workflowset(
  verbose = FALSE,
  allow_par = FALSE,
  cores = 1,
  packages = NULL
)

control_nested_fit(
  verbose = FALSE,
  allow_par = FALSE,
  cores = 1,
  packages = NULL
)

control_nested_refit(
  verbose = FALSE,
  allow_par = FALSE,
  cores = 1,
  packages = NULL
)

control_nested_forecast(
  verbose = FALSE,
  allow_par = FALSE,
  cores = 1,
  packages = NULL
)

Arguments

Value

A List with the control settings.

See Also

• Setting Up Parallel Processing: parallel_start(), [parallel_stop())]

• Training Functions: [modeltime_refit()], [modeltime_fit_workflowset()], [modeltime_nested_fit()], [modeltime_nested_refit()]

[parallel_stop())]: R:parallel_stop()) [modeltime_refit()]: R:modeltime_refit() [modeltime_fit_workflowset()]: R:modeltime_fit_workflowset() [modeltime_nested_fit()]: R:modeltime_nested_fit() [modeltime_nested_refit()]: R:modeltime_nested_refit()

Examples

# No parallel processing by default
control_refit()

# Allow parallel processing and use all cores
control_refit(allow_par = TRUE, cores = -1)

# Set verbosity to show additional training information
control_refit(verbose = TRUE)

# Add additional packages used during modeling in parallel processing
# - This is useful if your namespace does not load all needed packages
#   to run models.
# - An example is if I use `temporal_hierarchy()`, which depends on the `thief` package
control_refit(allow_par = TRUE, packages = "thief")

Description

Helper to make parsnip model specs from a dials parameter grid

Usage

create_model_grid(grid, f_model_spec, engine_name, ..., engine_params = list())

Arguments

Details

This is a helper function that combines dials grids with parsnip model specifications. The intent is to make it easier to generate workflowset objects for forecast evaluations with modeltime_fit_workflowset().

The process follows:

1. Generate a grid (hyperparemeter combination)

2. Use create_model_grid() to apply the parameter combinations to a parsnip model spec and engine.

The output contains ".model" column that can be used as a list of models inside the workflow_set() function.

Value

Tibble with a new colum named .models

See Also

• dials::grid_regular(): For making parameter grids.

• workflowsets::workflow_set(): For creating a workflowset from the .models list stored in the ".models" column.

• modeltime_fit_workflowset(): For fitting a workflowset to forecast data.

Examples

library(tidymodels)

# Parameters that get optimized
grid_tbl <- grid_regular(
    learn_rate(),
    levels = 3
)

# Generate model specs
grid_tbl %>%
    create_model_grid(
        f_model_spec = boost_tree,
        engine_name  = "xgboost",
        # Static boost_tree() args
        mode = "regression",
        # Static set_engine() args
        engine_params = list(
            max_depth = 5
        )
    )

Description

These functions are designed to assist developers in extending the modeltime package. create_xregs_recipe() makes it simple to automate conversion of raw un-encoded features to machine-learning ready features.

Usage

create_xreg_recipe(
  data,
  prepare = TRUE,
  clean_names = TRUE,
  dummy_encode = TRUE,
  one_hot = FALSE
)

Arguments

Details

The default recipe contains steps to:

1. Remove date features

2. Clean the column names removing spaces and bad characters

3. Convert ordered factors to regular factors

4. Convert factors to dummy variables

5. Remove any variables that have zero variance

Value

A recipe in either prepared or un-prepared format.

Examples

library(dplyr)
library(timetk)
library(recipes)
library(lubridate)

predictors <- m4_monthly %>%
    filter(id == "M750") %>%
    select(-value) %>%
    mutate(month = month(date, label = TRUE))
predictors

# Create default recipe
xreg_recipe_spec <- create_xreg_recipe(predictors, prepare = TRUE)

# Extracts the preprocessed training data from the recipe (used in your fit function)
juice_xreg_recipe(xreg_recipe_spec)

# Applies the prepared recipe to new data (used in your predict function)
bake_xreg_recipe(xreg_recipe_spec, new_data = predictors)

Description

Drop a Model from a Modeltime Table

Usage

drop_modeltime_model(object, .model_id)

Arguments

See Also

• combine_modeltime_tables(): Combine 2 or more Modeltime Tables together

• add_modeltime_model(): Adds a new row with a new model to a Modeltime Table

• drop_modeltime_model(): Drop one or more models from a Modeltime Table

• update_modeltime_description(): Updates a description for a model inside a Modeltime Table

• update_modeltime_model(): Updates a model inside a Modeltime Table

• pull_modeltime_model(): Extracts a model from a Modeltime Table

Examples

library(tidymodels)


m750_models %>%
    drop_modeltime_model(.model_id = c(2,3))

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. Several algorithms are implemented:

• ETS - Automated Exponential Smoothing

• CROSTON - Croston's forecast is a special case of Exponential Smoothing for intermittent demand

• Theta - A special case of Exponential Smoothing with Drift that performed well in the M3 Competition

Usage

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

Arguments

Details

Models can be created using the following engines:

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

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

• "theta" - Connects to forecast::thetaf()

• "smooth_es" - Connects to smooth::es()

Engine Details

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

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

• smooth_level(), smooth_trend(), and smooth_seasonal() are automatically determined if not provided. They are mapped to "alpha", "beta" and "gamma", respectively.

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.

croston

The engine uses forecast::croston().

Function Parameters:

#> function (y, h = 10, alpha = 0.1, x = y)

The main arguments are defined using:

• smooth_level(): The "alpha" parameter

Parameter Notes:

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

theta

The engine uses forecast::thetaf()

Parameter Notes:

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

smooth_es

The engine uses smooth::es().

Function Parameters:

#> function (y, model = "ZZZ", lags = c(frequency(y)), persistence = NULL, 
#>     phi = NULL, initial = c("optimal", "backcasting", "complete"), initialSeason = NULL, 
#>     ic = c("AICc", "AIC", "BIC", "BICc"), loss = c("likelihood", "MSE", 
#>         "MAE", "HAM", "MSEh", "TMSE", "GTMSE", "MSCE"), h = 10, holdout = FALSE, 
#>     bounds = c("usual", "admissible", "none"), silent = TRUE, xreg = NULL, 
#>     regressors = c("use", "select"), initialX = NULL, ...)

The main arguments model and phi are defined using:

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

• trend() = "auto", "additive", "multiplicative", "additive_damped", "multiplicative_damped" and "none" are converted to "Z", "A", "M", "Ad", "Md" and "N".

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

• damping() - Value of damping parameter. If NULL, then it is estimated.

• smooth_level(), smooth_trend(), and smooth_seasonal() are automatically determined if not provided. They are mapped to "persistence"("alpha", "beta" and "gamma", respectively).

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

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

Parameter Notes:

• xreg - This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

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)

Just for smooth engine.

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 arima_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.

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(parsnip)
library(rsample)
library(timetk)
library(smooth)

# 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


# ---- CROSTON ----

# Model Spec
model_spec <- exp_smoothing(
        smooth_level = 0.2
    ) %>%
    set_engine("croston")

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




# ---- THETA ----

#' # Model Spec
model_spec <- exp_smoothing() %>%
    set_engine("theta")

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





#' # ---- SMOOTH ----

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

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

Description

Tuning Parameters for Exponential Smoothing Models

Usage

error(values = c("additive", "multiplicative"))

trend(values = c("additive", "multiplicative", "none"))

trend_smooth(
  values = c("additive", "multiplicative", "none", "additive_damped",
    "multiplicative_damped")
)

season(values = c("additive", "multiplicative", "none"))

damping(values = c("none", "damped"))

damping_smooth(range = c(0, 2), trans = NULL)

smooth_level(range = c(0, 1), trans = NULL)

smooth_trend(range = c(0, 1), trans = NULL)

smooth_seasonal(range = c(0, 1), trans = NULL)

Arguments

Details

The main parameters for Exponential Smoothing models are:

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

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

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

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

• smooth_level: This is often called the "alpha" parameter used as the base level smoothing factor for exponential smoothing models.

• smooth_trend: This is often called the "beta" parameter used as the trend smoothing factor for exponential smoothing models.

• smooth_seasonal: This is often called the "gamma" parameter used as the seasonal smoothing factor for exponential smoothing models.

Examples

error()

trend()

season()

Description

Get model descriptions for Arima objects

Usage

get_arima_description(object, padding = FALSE)

Arguments

Source

• Forecast R Package, forecast:::arima.string()

Examples

library(forecast)

arima_fit <- forecast::Arima(1:10)

get_arima_description(arima_fit)

Description

Get model descriptions for parsnip, workflows & modeltime objects

Usage

get_model_description(object, indicate_training = FALSE, upper_case = TRUE)

Arguments

Examples

library(dplyr)
library(timetk)
library(parsnip)

# Model Specification ----

arima_spec <- arima_reg() %>%
    set_engine("auto_arima")

get_model_description(arima_spec, indicate_training = TRUE)

# Fitted Model ----

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

arima_fit <- arima_spec %>%
    fit(value ~ date, data = m750)

get_model_description(arima_fit, indicate_training = TRUE)

Description

Get model descriptions for TBATS objects

Usage

get_tbats_description(object)

Arguments

Source

• Forecast R Package, forecast:::as.character.tbats()

Description

Extract logged information calculated during the modeltime_nested_fit(), modeltime_nested_select_best(), and modeltime_nested_refit() processes.

Usage

extract_nested_test_accuracy(object)

extract_nested_test_forecast(object, .include_actual = TRUE, .id_subset = NULL)

extract_nested_error_report(object)

extract_nested_best_model_report(object)

extract_nested_future_forecast(
  object,
  .include_actual = TRUE,
  .id_subset = NULL
)

extract_nested_modeltime_table(object, .row_id = 1)

extract_nested_train_split(object, .row_id = 1)

extract_nested_test_split(object, .row_id = 1)

Arguments

Description

The 750th Monthly Time Series used in the M4 Competition

Usage

m750

Format

A tibble with 306 rows and 3 variables:

• id Factor. Unique series identifier

• date Date. Timestamp information. Monthly format.

• value Numeric. Value at the corresponding timestamp.

Source

• M4 Competition Website: https://www.unic.ac.cy/iff/research/forecasting/m-competitions/m4/

Examples

m750

Description

Three (3) Models trained on the M750 Data (Training Set)

Usage

m750_models

Format

An time_series_cv object with 6 slices of Time Series Cross Validation resamples made on the training(m750_splits)

Details

m750_models <- modeltime_table(
    wflw_fit_arima,
    wflw_fit_prophet,
    wflw_fit_glmnet
)

Examples

m750_models

Description

The results of train/test splitting the M750 Data

Usage

m750_splits

Format

An rsplit object split into approximately 23.5-years of training data and 2-years of testing data

Details

library(timetk)
m750_splits <- time_series_split(m750, assess = "2 years", cumulative = TRUE)

Examples

library(rsample)

m750_splits

training(m750_splits)

Description

The Time Series Cross Validation Resamples the M750 Data (Training Set)

Usage

m750_training_resamples

Format

An time_series_cv object with 6 slices of Time Series Cross Validation resamples made on the training(m750_splits)

Details

library(timetk)
m750_training_resamples <- time_series_cv(
    data        = training(m750_splits),
    assess      = "2 years",
    skip        = "2 years",
    cumulative  = TRUE,
    slice_limit = 6
)

Examples

library(rsample)

m750_training_resamples

Description

Useful when MAPE returns Inf typically due to intermittent data containing zeros. This is a wrapper to the function of TSrepr::maape().

Usage

maape(data, ...)

Arguments

Description

This is basically a wrapper to the function of TSrepr::maape().

Usage

maape_vec(truth, estimate, na_rm = TRUE, ...)

Arguments

Description

This is a wrapper for metric_set() with several common forecast / regression accuracy metrics included. These are the default time series accuracy metrics used with modeltime_accuracy().

Usage

default_forecast_accuracy_metric_set(...)

extended_forecast_accuracy_metric_set(...)

Arguments

Default Forecast Accuracy Metric Set

The primary purpose is to use the default accuracy metrics to calculate the following forecast accuracy metrics using modeltime_accuracy():

• MAE - Mean absolute error, mae()

• MAPE - Mean absolute percentage error, mape()

• MASE - Mean absolute scaled error, mase()

• SMAPE - Symmetric mean absolute percentage error, smape()

• RMSE - Root mean squared error, rmse()

• RSQ - R-squared, rsq()

Adding additional metrics is possible via ....

Extended Forecast Accuracy Metric Set

Extends the default metric set by adding:

• MAAPE - Mean Arctangent Absolute Percentage Error, maape(). MAAPE is designed for intermittent data where MAPE returns Inf.

See Also

• yardstick::metric_tweak() - For modifying yardstick metrics

Examples

library(tibble)
library(dplyr)
library(timetk)
library(yardstick)

fake_data <- tibble(
    y    = c(1:12, 2*1:12),
    yhat = c(1 + 1:12, 2*1:12 - 1)
)

# ---- HOW IT WORKS ----

# Default Forecast Accuracy Metric Specification
default_forecast_accuracy_metric_set()

# Create a metric summarizer function from the metric set
calc_default_metrics <- default_forecast_accuracy_metric_set()

# Apply the metric summarizer to new data
calc_default_metrics(fake_data, y, yhat)

# ---- ADD MORE PARAMETERS ----

# Can create a version of mase() with seasonality = 12 (monthly)
mase12 <- metric_tweak(.name = "mase12", .fn = mase, m = 12)

# Add it to the default metric set
my_metric_set <- default_forecast_accuracy_metric_set(mase12)
my_metric_set

# Apply the newly created metric set
my_metric_set(fake_data, y, yhat)

Description

This is a wrapper for yardstick that simplifies time series regression accuracy metric calculations from a fitted workflow (trained workflow) or model_fit (trained parsnip model).

Usage

modeltime_accuracy(
  object,
  new_data = NULL,
  metric_set = default_forecast_accuracy_metric_set(),
  acc_by_id = FALSE,
  quiet = TRUE,
  ...
)

Arguments

Details

The following accuracy metrics are included by default via default_forecast_accuracy_metric_set():

• MAE - Mean absolute error, mae()

• MAPE - Mean absolute percentage error, mape()

• MASE - Mean absolute scaled error, mase()

• SMAPE - Symmetric mean absolute percentage error, smape()

• RMSE - Root mean squared error, rmse()

• RSQ - R-squared, rsq()

Value

A tibble with accuracy estimates.

Examples

library(tidymodels)
library(dplyr)
library(lubridate)
library(timetk)


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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- ACCURACY ----

models_tbl %>%
    modeltime_calibrate(new_data = testing(splits)) %>%
    modeltime_accuracy(
        metric_set = metric_set(mae, rmse, rsq)
    )

Description

Calibration sets the stage for accuracy and forecast confidence by computing predictions and residuals from out of sample data.

Usage

modeltime_calibrate(object, new_data, id = NULL, quiet = TRUE, ...)

Arguments

Details

The results of calibration are used for:

• Forecast Confidence Interval Estimation: The out of sample residual data is used to calculate the confidence interval. Refer to modeltime_forecast().

• Accuracy Calculations: The out of sample actual and prediction values are used to calculate performance metrics. Refer to modeltime_accuracy()

The calibration steps include:

1. If not a Modeltime Table, objects are converted to Modeltime Tables internally

2. Two Columns are added:

• .type: Indicates the sample type. This is:

  • "Test" if predicted, or

  • "Fitted" if residuals were stored during modeling.

• .calibration_data:

  • Contains a tibble with Timestamps, Actual Values, Predictions and Residuals calculated from new_data (Test Data)

  • If id is provided, will contain a 5th column that is the identifier variable.

Value

A Modeltime Table (mdl_time_tbl) with nested .calibration_data added

Examples

library(dplyr)
library(lubridate)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- CALIBRATE ----

calibration_tbl <- models_tbl %>%
    modeltime_calibrate(
        new_data = testing(splits)
    )

# ---- ACCURACY ----

calibration_tbl %>%
    modeltime_accuracy()

# ---- FORECAST ----

calibration_tbl %>%
    modeltime_forecast(
        new_data    = testing(splits),
        actual_data = m750
    )

Description

This is a wrapper for fit() that takes a workflowset object and fits each model on one or multiple time series either sequentially or in parallel.

Usage

modeltime_fit_workflowset(
  object,
  data,
  ...,
  control = control_fit_workflowset()
)

Arguments

Value

A Modeltime Table containing one or more fitted models.

See Also

control_fit_workflowset()

Examples

library(tidymodels)
library(workflowsets)
library(dplyr)
library(lubridate)
library(timetk)

data_set <- m4_monthly

# SETUP WORKFLOWSETS

rec1 <- recipe(value ~ date + id, data_set) %>%
    step_mutate(date_num = as.numeric(date)) %>%
    step_mutate(month_lbl = lubridate::month(date, label = TRUE)) %>%
    step_dummy(all_nominal(), one_hot = TRUE)

mod1 <- linear_reg() %>% set_engine("lm")

mod2 <- prophet_reg() %>% set_engine("prophet")

wfsets <- workflowsets::workflow_set(
    preproc = list(rec1 = rec1),
    models  = list(
        mod1 = mod1,
        mod2 = mod2
    ),
    cross   = TRUE
)

# FIT WORKFLOWSETS
# - Returns a Modeltime Table with fitted workflowsets

wfsets %>% modeltime_fit_workflowset(data_set)

Description

The goal of modeltime_forecast() is to simplify the process of forecasting future data.

Usage

modeltime_forecast(
  object,
  new_data = NULL,
  h = NULL,
  actual_data = NULL,
  conf_interval = 0.95,
  conf_by_id = FALSE,
  conf_method = "conformal_default",
  keep_data = FALSE,
  arrange_index = FALSE,
  ...
)

Arguments

Details

The modeltime_forecast() function prepares a forecast for visualization with with plot_modeltime_forecast(). The forecast is controlled by new_data or h, which can be combined with existing data (controlled by actual_data). Confidence intervals are included if the incoming Modeltime Table has been calibrated using modeltime_calibrate(). Otherwise confidence intervals are not estimated.

New Data

When forecasting you can specify future data using new_data. This is a future tibble with date column and columns for xregs extending the trained dates and exogonous regressors (xregs) if used.

• Forecasting Evaluation Data: By default, the new_data will use the .calibration_data if new_data is not provided. This is the equivalent of using rsample::testing() for getting test data sets.

• Forecasting Future Data: See timetk::future_frame() for creating future tibbles.

• Xregs: Can be used with this method

H (Horizon)

When forecasting, you can specify h. This is a phrase like "1 year", which extends the .calibration_data (1st priority) or the actual_data (2nd priority) into the future.

• Forecasting Future Data: All forecasts using h are extended after the calibration data or actual_data.

• Extending .calibration_data - Calibration data is given 1st priority, which is desirable after refitting with modeltime_refit(). Internally, a call is made to timetk::future_frame() to expedite creating new data using the date feature.

• Extending actual_data - If h is provided, and the modeltime table has not been calibrated, the "actual_data" will be extended into the future. This is useful in situations where you want to go directly from modeltime_table() to modeltime_forecast() without calibrating or refitting.

• Xregs: Cannot be used because future data must include new xregs. If xregs are desired, build a future data frame and use new_data.

Actual Data

This is reference data that contains the true values of the time-stamp data. It helps in visualizing the performance of the forecast vs the actual data.

When h is used and the Modeltime Table has not been calibrated, then the actual data is extended into the future periods that are defined by h.

Confidence Interval Estimation

Confidence intervals (.conf_lo, .conf_hi) are estimated based on the normal estimation of the testing errors (out of sample) from modeltime_calibrate(). The out-of-sample error estimates are then carried through and applied to applied to any future forecasts.

The confidence interval can be adjusted with the conf_interval parameter. The algorithm used to produce confidence intervals can be changed with the conf_method parameter.

Conformal Default Method:

When conf_method = "conformal_default" (default), this method uses qnorm() to produce a 95% confidence interval by default. It estimates a normal (Gaussian distribution) based on the out-of-sample errors (residuals).

The confidence interval is mean-adjusted, meaning that if the mean of the residuals is non-zero, the confidence interval is adjusted to widen the interval to capture the difference in means.

Conformal Split Method:

When ⁠conf_method = "conformal_split⁠, this method uses the split conformal inference method described by Lei et al (2018). This is also implemented in the probably R package's int_conformal_split() function.

What happens to the confidence interval after refitting models?

Refitting has no affect on the confidence interval since this is calculated independently of the refitted model. New observations typically improve future accuracy, which in most cases makes the out-of-sample confidence intervals conservative.

Keep Data

Include the new data (and actual data) as extra columns with the results of the model forecasts. This can be helpful when the new data includes information useful to the forecasts. An example is when forecasting Panel Data and the new data contains ID features related to the time series group that the forecast belongs to.

Arrange Index

By default, modeltime_forecast() keeps the original order of the data. If desired, the user can sort the output by .key, .model_id and .index.

Value

A tibble with predictions and time-stamp data. For ease of plotting and calculations, the column names are transformed to:

• .key: Values labeled either "prediction" or "actual"

• .index: The timestamp index.

• .value: The value being forecasted.

Additionally, if the Modeltime Table has been previously calibrated using modeltime_calibrate(), you will gain confidence intervals.

• .conf_lo: The lower limit of the confidence interval.

• .conf_hi: The upper limit of the confidence interval.

Additional descriptive columns are included:

• .model_id: Model ID from the Modeltime Table

• .model_desc: Model Description from the Modeltime Table

Unnecessary columns are dropped to save space:

• .model

• .calibration_data

References

Lei, Jing, et al. "Distribution-free predictive inference for regression." Journal of the American Statistical Association 113.523 (2018): 1094-1111.

Examples

library(dplyr)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- CALIBRATE ----

calibration_tbl <- models_tbl %>%
    modeltime_calibrate(new_data = testing(splits))

# ---- ACCURACY ----

calibration_tbl %>%
    modeltime_accuracy()

# ---- FUTURE FORECAST ----

calibration_tbl %>%
    modeltime_forecast(
        new_data    = testing(splits),
        actual_data = m750
    )

# ---- ALTERNATIVE: FORECAST WITHOUT CONFIDENCE INTERVALS ----
# Skips Calibration Step, No Confidence Intervals

models_tbl %>%
    modeltime_forecast(
        new_data    = testing(splits),
        actual_data = m750
    )

# ---- KEEP NEW DATA WITH FORECAST ----
# Keeps the new data. Useful if new data has information
#  like ID features that should be kept with the forecast data

calibration_tbl %>%
    modeltime_forecast(
        new_data      = testing(splits),
        keep_data     = TRUE
    )

Description

Fits one or more tidymodels workflow objects to nested time series data using the following process:

1. Models are iteratively fit to training splits.

2. Accuracy is calculated on testing splits and is logged. Accuracy results can be retrieved with extract_nested_test_accuracy()

3. Any model that returns an error is logged. Error logs can be retrieved with extract_nested_error_report()

4. Forecast is predicted on testing splits and is logged. Forecast results can be retrieved with extract_nested_test_forecast()

Usage

modeltime_nested_fit(
  nested_data,
  ...,
  model_list = NULL,
  metric_set = default_forecast_accuracy_metric_set(),
  conf_interval = 0.95,
  conf_method = "conformal_default",
  control = control_nested_fit()
)

Arguments

Details

Preparing Data for Nested Forecasting

Use extend_timeseries(), nest_timeseries(), and split_nested_timeseries() for preparing data for Nested Forecasting. The structure must be a nested data frame, which is suppplied in modeltime_nested_fit(nested_data).

Fitting Models

Models must be in the form of ⁠tidymodels workflow⁠ objects. The models can be provided in two ways:

1. Using ... (dots): The workflow objects can be provided as dots.

2. Using model_list parameter: You can supply one or more workflow objects that are wrapped in a list().

Controlling the fitting process

A control object can be provided during fitting to adjust the verbosity and parallel processing. See control_nested_fit().

Description

Make a new forecast from a Nested Modeltime Table.

Usage

modeltime_nested_forecast(
  object,
  h = NULL,
  include_actual = TRUE,
  conf_interval = 0.95,
  conf_method = "conformal_default",
  id_subset = NULL,
  control = control_nested_forecast()
)

Arguments

Details

This function is designed to help users that want to make new forecasts other than those that are created during the logging process as part of the Nested Modeltime Workflow.

Logged Forecasts

The logged forecasts can be extracted using:

• extract_nested_future_forecast(): Extracts the future forecast created after refitting with modeltime_nested_refit().

• extract_nested_test_forecast(): Extracts the test forecast created after initial fitting with modeltime_nested_fit().

The problem is that these forecasts are static. The user would need to redo the fitting, model selection, and refitting process to obtain new forecasts. This is why modeltime_nested_forecast() exists. So you can create a new forecast without retraining any models.

Nested Forecasts

The main arguments is h, which is a horizon that specifies how far into the future to make the new forecast.

• If h = NULL, a logged forecast will be returned

• If h = 12, a new forecast will be generated that extends each series 12-periods into the future.

• If h = "2 years", a new forecast will be generated that extends each series 2-years into the future.

Use the id_subset to filter the Nested Modeltime Table object to just the time series of interest.

Use the conf_interval to override the logged confidence interval. Note that this will have no effect if h = NULL as logged forecasts are returned. So be sure to provide h if you want to update the confidence interval.

Use the control argument to apply verbosity during the forecasting process and to run forecasts in parallel. Generally, parallel is better if many forecasts are being generated.

Description

Refits a Nested Modeltime Table to actual data using the following process:

1. Models are iteratively refit to .actual_data.

2. Any model that returns an error is logged. Errors can be retrieved with extract_nested_error_report()

3. Forecast is predicted on future_data and is logged. Forecast can be retrieved with extract_nested_future_forecast()

Usage

modeltime_nested_refit(object, control = control_nested_refit())

Arguments

Description

Finds the best models for each time series group in a Nested Modeltime Table using a metric that the user specifies.

• Logs the best results, which can be accessed with extract_nested_best_model_report()

• If filter_test_forecasts = TRUE, updates the test forecast log, which can be accessed extract_nested_test_forecast()

Usage

modeltime_nested_select_best(
  object,
  metric = "rmse",
  minimize = TRUE,
  filter_test_forecasts = TRUE
)

Arguments

Description

This is a wrapper for fit() that takes a Modeltime Table and retrains each model on new data re-using the parameters and preprocessing steps used during the training process.

Usage

modeltime_refit(object, data, ..., control = control_refit())

Arguments

Details

Refitting is an important step prior to forecasting time series models. The modeltime_refit() function makes it easy to recycle models, retraining on new data.

Recycling Parameters

Parameters are recycled during retraining using the following criteria:

• Automated models (e.g. "auto arima") will have parameters recalculated.

• Non-automated models (e.g. "arima") will have parameters preserved.

• All preprocessing steps will be reused on the data

Refit

The modeltime_refit() function is used to retrain models trained with fit().

Refit XY

The XY format is not supported at this time.

Value

A Modeltime Table containing one or more re-trained models.

See Also

control_refit()

Examples

library(dplyr)
library(lubridate)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- CALIBRATE ----
# - Calibrate on training data set

calibration_tbl <- models_tbl %>%
    modeltime_calibrate(new_data = testing(splits))


# ---- REFIT ----
# - Refit on full data set

refit_tbl <- calibration_tbl %>%
    modeltime_refit(m750)

Description

This is a convenience function to unnest model residuals

Usage

modeltime_residuals(object, new_data = NULL, quiet = TRUE, ...)

Arguments

Value

A tibble with residuals.

Examples

library(dplyr)
library(lubridate)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- RESIDUALS ----

# In-Sample
models_tbl %>%
    modeltime_calibrate(new_data = training(splits)) %>%
    modeltime_residuals() %>%
    plot_modeltime_residuals(.interactive = FALSE)

# Out-of-Sample
models_tbl %>%
    modeltime_calibrate(new_data = testing(splits)) %>%
    modeltime_residuals() %>%
    plot_modeltime_residuals(.interactive = FALSE)

Description

This is a convenience function to calculate some statistical tests on the residuals models. Currently, the following statistics are calculated: the shapiro.test to check the normality of the residuals, the box-pierce and ljung-box tests and the durbin watson test to check the autocorrelation of the residuals. In all cases the p-values are returned.

Usage

modeltime_residuals_test(object, new_data = NULL, lag = 1, fitdf = 0, ...)

Arguments

Details

Shapiro-Wilk Test

The Shapiro-Wilk tests the Normality of the residuals. The Null Hypothesis is that the residuals are normally distributed. A low P-Value below a given significance level indicates the values are NOT Normally Distributed.

If the p-value > 0.05 (good), this implies that the distribution of the data are not significantly different from normal distribution. In other words, we can assume the normality.

Box-Pierce and Ljung-Box Tests Tests

The Ljung-Box and Box-Pierce tests are methods that test for the absense of autocorrelation in residuals. A low p-value below a given significance level indicates the values are autocorrelated.

If the p-value > 0.05 (good), this implies that the residuals of the data are are independent. In other words, we can assume the residuals are not autocorrelated.

For more information about the parameters associated with the Box Pierce and Ljung Box tests check ?Box.Test

Durbin-Watson Test

The Durbin-Watson test is a method that tests for the absense of autocorrelation in residuals. The Durbin Watson test reports a test statistic, with a value from 0 to 4, where:

• 2 is no autocorrelation (good)

• From 0 to <2 is positive autocorrelation (common in time series data)

• From >2 to 4 is negative autocorrelation (less common in time series data)

Value

A tibble with with the p-values of the calculated statistical tests.

See Also

stats::shapiro.test(), stats::Box.test()

Examples

library(dplyr)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- RESIDUALS ----

# In-Sample
models_tbl %>%
    modeltime_calibrate(new_data = training(splits)) %>%
    modeltime_residuals() %>%
    modeltime_residuals_test()

# Out-of-Sample
models_tbl %>%
    modeltime_calibrate(new_data = testing(splits)) %>%
    modeltime_residuals() %>%
    modeltime_residuals_test()

Description

Designed to perform forecasts at scale using models created with modeltime, parsnip, workflows, and regression modeling extensions in the tidymodels ecosystem.

Usage

modeltime_table(...)

as_modeltime_table(.l)

Arguments

Details

modeltime_table():

1. Creates a table of models

2. Validates that all objects are models (parsnip or workflows objects) and all models have been fitted (trained)

3. Provides an ID and Description of the models

as_modeltime_table():

Converts a list of models to a modeltime table. Useful if programatically creating Modeltime Tables from models stored in a list.

Examples

library(dplyr)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

# Make a Modeltime Table
models_tbl <- modeltime_table(
    model_fit_prophet
)

# Can also convert a list of models
list(model_fit_prophet) %>%
    as_modeltime_table()

# ---- CALIBRATE ----

calibration_tbl <- models_tbl %>%
    modeltime_calibrate(new_data = testing(splits))

# ---- ACCURACY ----

calibration_tbl %>%
    modeltime_accuracy()

# ---- FORECAST ----

calibration_tbl %>%
    modeltime_forecast(
        new_data    = testing(splits),
        actual_data = m750
    )

Description

naive_reg() is a way to generate a specification of an NAIVE or SNAIVE model before fitting and allows the model to be created using different packages.

Usage

naive_reg(mode = "regression", id = NULL, seasonal_period = NULL)

Arguments

Details

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

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

• "naive" (default) - Performs a NAIVE forecast

• "snaive" - Performs a Seasonal NAIVE forecast

Engine Details

naive (default engine)

• The engine uses naive_fit_impl()

• The NAIVE implementation uses the last observation and forecasts this value forward.

• The id can be used to distinguish multiple time series contained in the data

• The seasonal_period is not used but provided for consistency with the SNAIVE implementation

snaive (default engine)

• The engine uses snaive_fit_impl()

• The SNAIVE implementation uses the last seasonal series in the data and forecasts this sequence of observations forward

• The id can be used to distinguish multiple time series contained in the data

• The seasonal_period is used to determine how far back to define the repeated series. This can be a numeric value (e.g. 28) or a period (e.g. "1 month")

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)

ID features (Multiple Time Series, Panel Data)

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

ID Example: Suppose you have 3 features:

1. y (target)

2. date (time stamp),

3. series_id (a unique identifer that identifies each time series in your data).

The series_id can be passed to the naive_reg() using fit():

• naive_reg(id = "series_id") specifes that the series_id column should be used to identify each time series.

• fit(y ~ date + series_id) will pass series_id on to the underlying naive or snaive functions.

Seasonal Period Specification (snaive)

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.

External Regressors (Xregs)

These models are univariate. No xregs are used in the modeling process.

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(parsnip)
library(rsample)
library(timetk)

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

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

# ---- NAIVE ----

# Model Spec
model_spec <- naive_reg() %>%
    set_engine("naive")

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


# ---- SEASONAL NAIVE ----

# Model Spec
model_spec <- naive_reg(
        id = "id",
        seasonal_period = 12
    ) %>%
    set_engine("snaive")

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

Description

These functions are used to construct new modeltime bridge functions that connect the tidymodels infrastructure to time-series models containing date or date-time features.

Usage

new_modeltime_bridge(class, models, data, extras = NULL, desc = NULL)

Arguments

Examples

library(dplyr)
library(lubridate)
library(timetk)

lm_model <- lm(value ~ as.numeric(date) + hour(date) + wday(date, label = TRUE),
               data = taylor_30_min)

data = tibble(
    date        = taylor_30_min$date, # Important - The column name must match the modeled data
    # These are standardized names: .actual, .fitted, .residuals
    .actual     = taylor_30_min$value,
    .fitted     = lm_model$fitted.values %>% as.numeric(),
    .residuals  = lm_model$residuals %>% as.numeric()
)

new_modeltime_bridge(
    class  = "lm_time_series_impl",
    models = list(model_1 = lm_model),
    data   = data,
    extras = NULL
)

Description

Tuning Parameters for NNETAR Models

Usage

num_networks(range = c(1L, 100L), trans = NULL)

Arguments

Details

The main parameters for NNETAR models are:

• non_seasonal_ar: Number of non-seasonal auto-regressive (AR) lags. Often denoted "p" in pdq-notation.

• seasonal_ar: Number of seasonal auto-regressive (SAR) lags. Often denoted "P" in PDQ-notation.

• hidden_units: An integer for the number of units in the hidden model.

• num_networks: Number of networks to fit with different random starting weights. These are then averaged when producing forecasts.

• penalty: A non-negative numeric value for the amount of weight decay.

• epochs: An integer for the number of training iterations.

See Also

non_seasonal_ar(), seasonal_ar(), dials::hidden_units(), dials::penalty(), dials::epochs()

Examples

num_networks()

Description

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

Usage

nnetar_reg(
  mode = "regression",
  seasonal_period = NULL,
  non_seasonal_ar = NULL,
  seasonal_ar = NULL,
  hidden_units = NULL,
  num_networks = NULL,
  penalty = NULL,
  epochs = NULL
)

Arguments

Details

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

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

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

Main Arguments

The main arguments (tuning parameters) for the model are the parameters in nnetar_reg() function. These arguments are converted to their specific names at the time that the model is fit.

Other options and argument can be set using set_engine() (See Engine Details below).

If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

Engine Details

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

Other options can be set using set_engine().

nnetar

The engine uses forecast::nnetar().

Function Parameters:

#> function (y, p, P = 1, size, repeats = 20, xreg = NULL, lambda = NULL, 
#>     model = NULL, subset = NULL, scale.inputs = TRUE, x = y, ...)

Parameter Notes:

• xreg - This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

• size - Is set to 10 by default. This differs from the forecast implementation

• p and P - Are set to 1 by default.

• maxit and decay are nnet::nnet parameters that are exposed in the nnetar_reg() interface. These are key tuning parameters.

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 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 nnetar_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.

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(parsnip)
library(rsample)
library(timetk)

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

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

# ---- NNETAR ----

# Model Spec
model_spec <- nnetar_reg() %>%
    set_engine("nnetar")

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

Description

Filter the last N rows (Tail) for multiple time series

Usage

panel_tail(data, id, n)

Arguments

Value

A data frame

See Also

• recursive() - used to generate recursive autoregressive models

Examples

library(timetk)

# Get the last 6 observations from each group
m4_monthly %>%
    panel_tail(id = id, n = 6)

Description

Start parallel clusters using parallel package

Usage

parallel_start(..., .method = c("parallel", "spark"))

parallel_stop()

Arguments

Parallel (.method = "parallel")

Performs 3 Steps:

1. Makes clusters using parallel::makeCluster(...). The parallel_start(...) are passed to parallel::makeCluster(...).

2. Registers clusters using doParallel::registerDoParallel().

3. Adds .libPaths() using parallel::clusterCall().

Spark (.method = "spark")

• Important, make sure to create a spark connection using sparklyr::spark_connect().

• Pass the connection object as the first argument. For example, parallel_start(sc, .method = "spark").

• The parallel_start(...) are passed to sparklyr::registerDoSpark(...).

Examples

# Starts 2 clusters
parallel_start(2)

# Returns to sequential processing
parallel_stop()

Description

These functions are designed to assist developers in extending the modeltime package.

Usage

parse_index_from_data(data)

parse_period_from_index(data, period)

Arguments

Value

• parse_index_from_data(): Returns a tibble containing the date or date-time column.

• parse_period_from_index(): Returns the numeric period from a tibble containing the index.

Examples

library(dplyr)
library(timetk)

predictors <- m4_monthly %>%
    filter(id == "M750") %>%
    select(-value)

index_tbl <- parse_index_from_data(predictors)
index_tbl

period <- parse_period_from_index(index_tbl, period = "1 year")
period

Description

This is a wrapper for timetk::plot_time_series() that generates an interactive (plotly) or static (ggplot2) plot with the forecasted data.

Usage

plot_modeltime_forecast(
  .data,
  .conf_interval_show = TRUE,
  .conf_interval_fill = "grey20",
  .conf_interval_alpha = 0.2,
  .smooth = FALSE,
  .legend_show = TRUE,
  .legend_max_width = 40,
  .facet_ncol = 1,
  .facet_nrow = 1,
  .facet_scales = "free_y",
  .title = "Forecast Plot",
  .x_lab = "",
  .y_lab = "",
  .color_lab = "Legend",
  .interactive = TRUE,
  .plotly_slider = FALSE,
  .trelliscope = FALSE,
  .trelliscope_params = list(),
  ...
)

Arguments

Value

A static ggplot2 plot or an interactive plotly plot containing a forecast

Examples

library(dplyr)
library(lubridate)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- FORECAST ----

models_tbl %>%
    modeltime_calibrate(new_data = testing(splits)) %>%
    modeltime_forecast(
        new_data    = testing(splits),
        actual_data = m750
    ) %>%
    plot_modeltime_forecast(.interactive = FALSE)

Description

This is a wrapper for examining residuals using:

• Time Plot: timetk::plot_time_series()

• ACF Plot: timetk::plot_acf_diagnostics()

• Seasonality Plot: timetk::plot_seasonal_diagnostics()

Usage

plot_modeltime_residuals(
  .data,
  .type = c("timeplot", "acf", "seasonality"),
  .smooth = FALSE,
  .legend_show = TRUE,
  .legend_max_width = 40,
  .title = "Residuals Plot",
  .x_lab = "",
  .y_lab = "",
  .color_lab = "Legend",
  .interactive = TRUE,
  ...
)

Arguments

Value

A static ggplot2 plot or an interactive plotly plot containing residuals vs time

Examples

library(dplyr)
library(timetk)
library(parsnip)
library(rsample)

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

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

# --- MODELS ---

# Model 1: prophet ----
model_fit_prophet <- prophet_reg() %>%
    set_engine(engine = "prophet") %>%
    fit(value ~ date, data = training(splits))


# ---- MODELTIME TABLE ----

models_tbl <- modeltime_table(
    model_fit_prophet
)

# ---- RESIDUALS ----

residuals_tbl <- models_tbl %>%
    modeltime_calibrate(new_data = testing(splits)) %>%
    modeltime_residuals()

residuals_tbl %>%
    plot_modeltime_residuals(
        .type = "timeplot",
        .interactive = FALSE
    )

Description

The pull_modeltime_model() and pluck_modeltime_model() functions are synonymns.

Usage

pluck_modeltime_model(object, .model_id)

## S3 method for class 'mdl_time_tbl'
pluck_modeltime_model(object, .model_id)

pull_modeltime_model(object, .model_id)

Arguments

See Also

• combine_modeltime_tables(): Combine 2 or more Modeltime Tables together

• add_modeltime_model(): Adds a new row with a new model to a Modeltime Table

• drop_modeltime_model(): Drop one or more models from a Modeltime Table

• update_modeltime_description(): Updates a description for a model inside a Modeltime Table

• update_modeltime_model(): Updates a model inside a Modeltime Table

• pull_modeltime_model(): Extracts a model from a Modeltime Table

Examples

m750_models %>%
    pluck_modeltime_model(2)

Description

A set of functions to simplify preparation of nested data for iterative (nested) forecasting with Nested Modeltime Tables.

Usage

extend_timeseries(.data, .id_var, .date_var, .length_future, ...)

nest_timeseries(.data, .id_var, .length_future, .length_actual = NULL)

split_nested_timeseries(.data, .length_test, .length_train = NULL, ...)

Arguments

Details

Preparation of nested time series follows a 3-Step Process:

Step 1: Extend the Time Series

extend_timeseries(): A wrapper for timetk::future_frame() that extends a time series group-wise into the future.

• The group column is specified by .id_var.

• The date column is specified by .date_var.

• The length into the future is specified with .length_future.

• The ... are additional parameters that can be passed to timetk::future_frame()

Step 2: Nest the Time Series

nest_timeseries(): A helper for nesting your data into .actual_data and .future_data.

• The group column is specified by .id_var

• The .length_future defines the length of the .future_data.

• The remaining data is converted to the .actual_data.

• The .length_actual can be used to slice the .actual_data to a most recent number of observations.

The result is a "nested data frame".

Step 3: Split the Actual Data into Train/Test Splits

split_nested_timeseries(): A wrapper for timetk::time_series_split() that generates training/testing splits from the .actual_data column.

• The .length_test is the primary argument that identifies the size of the testing sample. This is typically the same size as the .future_data.

• The .length_train is an optional size of the training data.

• The ... (dots) are additional arguments that can be passed to timetk::time_series_split().

Helpers

extract_nested_train_split() and extract_nested_test_split() are used to simplify extracting the training and testing data from the actual data. This can be helpful when making preprocessing recipes using the recipes package.

Examples

library(dplyr)
library(timetk)


nested_data_tbl <- walmart_sales_weekly %>%
    select(id, date = Date, value = Weekly_Sales) %>%

    # Step 1: Extends the time series by id
    extend_timeseries(
        .id_var     = id,
        .date_var   = date,
        .length_future = 52
    ) %>%

    # Step 2: Nests the time series into .actual_data and .future_data
    nest_timeseries(
        .id_var     = id,
        .length_future = 52
    ) %>%

    # Step 3: Adds a column .splits that contains training/testing indices
    split_nested_timeseries(
        .length_test = 52
    )

nested_data_tbl

# Helpers: Getting the Train/Test Sets
extract_nested_train_split(nested_data_tbl, .row_id = 1)

Description

prophet_boost() is a way to generate a specification of a Boosted PROPHET model before fitting and allows the model to be created using different packages. Currently the only package is prophet.

Usage

prophet_boost(
  mode = "regression",
  growth = NULL,
  changepoint_num = NULL,
  changepoint_range = NULL,
  seasonality_yearly = NULL,
  seasonality_weekly = NULL,
  seasonality_daily = NULL,
  season = NULL,
  prior_scale_changepoints = NULL,
  prior_scale_seasonality = NULL,
  prior_scale_holidays = NULL,
  logistic_cap = NULL,
  logistic_floor = NULL,
  mtry = NULL,
  trees = NULL,
  min_n = NULL,
  tree_depth = NULL,
  learn_rate = NULL,
  loss_reduction = NULL,
  sample_size = NULL,
  stop_iter = NULL
)

Arguments

Details

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

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

• "prophet_xgboost" (default) - Connects to prophet::prophet() and xgboost::xgb.train()

Main Arguments

The main arguments (tuning parameters) for the PROPHET model are:

• growth: String 'linear' or 'logistic' to specify a linear or logistic trend.

• changepoint_num: Number of potential changepoints to include for modeling trend.

• changepoint_range: Range changepoints that adjusts how close to the end the last changepoint can be located.

• season: 'additive' (default) or 'multiplicative'.

• prior_scale_changepoints: Parameter modulating the flexibility of the automatic changepoint selection. Large values will allow many changepoints, small values will allow few changepoints.

• prior_scale_seasonality: Parameter modulating the strength of the seasonality model. Larger values allow the model to fit larger seasonal fluctuations, smaller values dampen the seasonality.

• prior_scale_holidays: Parameter modulating the strength of the holiday components model, unless overridden in the holidays input.

• logistic_cap: When growth is logistic, the upper-bound for "saturation".

• logistic_floor: When growth is logistic, the lower-bound for "saturation".

The main arguments (tuning parameters) for the model XGBoost model are:

• mtry: The number of predictors that will be randomly sampled at each split when creating the tree models.

• trees: The number of trees contained in the ensemble.

• min_n: The minimum number of data points in a node that are required for the node to be split further.

• tree_depth: The maximum depth of the tree (i.e. number of splits).

• learn_rate: The rate at which the boosting algorithm adapts from iteration-to-iteration.

• loss_reduction: The reduction in the loss function required to split further.

• sample_size: The amount of data exposed to the fitting routine.

• stop_iter: The number of iterations without improvement before stopping.

These arguments are converted to their specific names at the time that the model is fit.

Other options and argument can be set using set_engine() (See Engine Details below).

If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

Engine Details

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

Model 1: PROPHET:

Model 2: XGBoost:

Other options can be set using set_engine().

prophet_xgboost

Model 1: PROPHET (prophet::prophet):

#> function (df = NULL, growth = "linear", changepoints = NULL, n.changepoints = 25, 
#>     changepoint.range = 0.8, yearly.seasonality = "auto", weekly.seasonality = "auto", 
#>     daily.seasonality = "auto", holidays = NULL, seasonality.mode = "additive", 
#>     seasonality.prior.scale = 10, holidays.prior.scale = 10, changepoint.prior.scale = 0.05, 
#>     mcmc.samples = 0, interval.width = 0.8, uncertainty.samples = 1000, 
#>     fit = TRUE, ...)

Parameter Notes:

• df: This is supplied via the parsnip / modeltime fit() interface (so don't provide this manually). See Fit Details (below).

• holidays: A data.frame of holidays can be supplied via set_engine()

• uncertainty.samples: The default is set to 0 because the prophet uncertainty intervals are not used as part of the Modeltime Workflow. You can override this setting if you plan to use prophet's uncertainty tools.

Logistic Growth and Saturation Levels:

• For growth = "logistic", simply add numeric values for logistic_cap and / or logistic_floor. There is no need to add additional columns for "cap" and "floor" to your data frame.

Limitations:

• prophet::add_seasonality() is not currently implemented. It's used to specify non-standard seasonalities using fourier series. An alternative is to use step_fourier() and supply custom seasonalities as Extra Regressors.

Model 2: XGBoost (xgboost::xgb.train):

#> function (params = list(), data, nrounds, watchlist = list(), obj = NULL, 
#>     feval = NULL, verbose = 1, print_every_n = 1L, early_stopping_rounds = NULL, 
#>     maximize = NULL, save_period = NULL, save_name = "xgboost.model", xgb_model = NULL, 
#>     callbacks = list(), ...)

Parameter Notes:

• XGBoost uses a params = list() to capture. Parsnip / Modeltime automatically sends any args provided as ... inside of set_engine() to the params = list(...).

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)

Univariate (No Extra 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 (Extra Regressors)

Extra Regressors 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 arima_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.

See Also

fit.model_spec(), set_engine()

Examples

library(dplyr)
library(lubridate)
library(parsnip)
library(rsample)
library(timetk)

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

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

# ---- PROPHET ----

# Model Spec
model_spec <- prophet_boost(
    learn_rate = 0.1
) %>%
    set_engine("prophet_xgboost")

# Fit Spec

model_fit <- model_spec %>%
    fit(log(value) ~ date + as.numeric(date) + month(date, label = TRUE),
        data = training(splits))
model_fit

Description

Tuning Parameters for Prophet Models

Usage

growth(values = c("linear", "logistic"))

changepoint_num(range = c(0L, 50L), trans = NULL)

changepoint_range(range = c(0.6, 0.9), trans = NULL)

seasonality_yearly(values = c(TRUE, FALSE))

seasonality_weekly(values = c(TRUE, FALSE))

seasonality_daily(values = c(TRUE, FALSE))

prior_scale_changepoints(range = c(-3, 2), trans = log10_trans())

prior_scale_seasonality(range = c(-3, 2), trans = log10_trans())

prior_scale_holidays(range = c(-3, 2), trans = log10_trans())

Arguments

Details

The main parameters for Prophet models are:

• growth: The form of the trend: "linear", or "logistic".

• changepoint_num: The maximum number of trend changepoints allowed when modeling the trend

• changepoint_range: The range affects how close the changepoints can go to the end of the time series. The larger the value, the more flexible the trend.

• Yearly, Weekly, and Daily Seasonality:

  • Yearly: seasonality_yearly - Useful when seasonal patterns appear year-over-year

  • Weekly: seasonality_weekly - Useful when seasonal patterns appear week-over-week (e.g. daily data)

  • Daily: seasonality_daily - Useful when seasonal patterns appear day-over-day (e.g. hourly data)

• season:

  • The form of the seasonal term: "additive" or "multiplicative".

  • See season().

• "Prior Scale": Controls flexibility of

  • Changepoints: prior_scale_changepoints

  • Seasonality: prior_scale_seasonality

  • Holidays: prior_scale_holidays

  • The log10_trans() converts priors to a scale from 0.001 to 100, which effectively weights lower values more heavily than larger values.

Examples

growth()

changepoint_num()

season()

prior_scale_changepoints()

Description

prophet_reg() is a way to generate a specification of a PROPHET model before fitting and allows the model to be created using different packages. Currently the only package is prophet.

Usage

prophet_reg(
  mode = "regression",
  growth = NULL,
  changepoint_num = NULL,
  changepoint_range = NULL,
  seasonality_yearly = NULL,
  seasonality_weekly = NULL,
  seasonality_daily = NULL,
  season = NULL,
  prior_scale_changepoints = NULL,
  prior_scale_seasonality = NULL,
  prior_scale_holidays = NULL,
  logistic_cap = NULL,
  logistic_floor = NULL
)

Arguments