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.

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

mode A single character string for the type of model. The only possible value for this model is "regression". A seasonal frequency. Uses "auto" by default. A character phrase of "auto" or time-based phrase of "2 weeks" can be used if a date or date-time variable is provided. See Fit Details below. The order of the non-seasonal auto-regressive (AR) terms. Often denoted "p" in pdq-notation. The order of the seasonal auto-regressive (SAR) terms. Often denoted "P" in PDQ-notation. An integer for the number of units in the hidden model. Number of networks to fit with different random starting weights. These are then averaged when producing forecasts. A non-negative numeric value for the amount of weight decay. An integer for the number of training iterations.

## 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:

 modeltime forecast::nnetar seasonal_period ts(frequency) non_seasonal_ar p (1) seasonal_ar P (1) hidden_units size (10) num_networks repeats (20) epochs maxit (100) penalty decay (0)

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.

fit.model_spec(), set_engine()

## Examples

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

# Data
m750 <- m4_monthly %>% filter(id == "M750")
m750
#> # A tibble: 306 × 3
#>    id    date       value
#>    <fct> <date>     <dbl>
#>  1 M750  1990-01-01  6370
#>  2 M750  1990-02-01  6430
#>  3 M750  1990-03-01  6520
#>  4 M750  1990-04-01  6580
#>  5 M750  1990-05-01  6620
#>  6 M750  1990-06-01  6690
#>  7 M750  1990-07-01  6000
#>  8 M750  1990-08-01  5450
#>  9 M750  1990-09-01  6480
#> 10 M750  1990-10-01  6820
#> # … with 296 more rows
# 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))
#> frequency = 12 observations per 1 yearmodel_fit
#> parsnip model object
#>
#> Fit time:  251ms
#> Series: outcome
#> Model:  NNAR(1,1,10)[12]
#> Call:   forecast::nnetar(y = outcome, p = p, P = P, size = size, repeats = repeats,
#>     xreg = xreg_matrix, decay = decay, maxit = maxit)
#>
#> Average of 20 networks, each of which is
#> a 2-10-1 network with 41 weights
#> options were - linear output units
#>
#> sigma^2 estimated as 0.0005868