deep_ar: General Interface for DeepAR Time Series Models

Description Usage Arguments Details Engine Details Engine Fit Details See Also Examples

View source: R/parsnip-deepar.R

Description

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

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
deep_ar(
  mode = "regression",
  id,
  freq,
  prediction_length,
  lookback_length = NULL,
  cell_type = NULL,
  num_layers = NULL,
  num_cells = NULL,
  dropout = NULL,
  epochs = NULL,
  batch_size = NULL,
  num_batches_per_epoch = NULL,
  learn_rate = NULL,
  learn_rate_decay_factor = NULL,
  learn_rate_min = NULL,
  patience = NULL,
  clip_gradient = NULL,
  penalty = NULL
)

Arguments

mode

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

id

A quoted column name that tracks the GluonTS FieldName "item_id"

freq

A pandas timeseries frequency such as "5min" for 5-minutes or "D" for daily. Refer to Pandas Offset Aliases.

prediction_length

Numeric value indicating the length of the prediction horizon

lookback_length

Number of steps to unroll the RNN for before computing predictions (default: NULL, in which case context_length = prediction_length)

cell_type

Type of recurrent cells to use (available: 'lstm' or 'gru'; default: 'lstm')

num_layers

Number of RNN layers (default: 2)

num_cells

Number of RNN cells for each layer (default: 40)

dropout

Dropout regularization parameter (default: 0.1)

epochs

Number of epochs that the network will train (default: 5).

batch_size

Number of examples in each batch (default: 32).

num_batches_per_epoch

Number of batches at each epoch (default: 50).

learn_rate

Initial learning rate (default: 10-3).

learn_rate_decay_factor

Factor (between 0 and 1) by which to decrease the learning rate (default: 0.5).

learn_rate_min

Lower bound for the learning rate (default: 5x10-5 ).

patience

The patience to observe before reducing the learning rate, nonnegative integer (default: 10).

clip_gradient

Maximum value of gradient. The gradient is clipped if it is too large (default: 10).

penalty

The weight decay (or L2 regularization) coefficient. Modifies objective by adding a penalty for having large weights (default 10-8 ).

Details

These arguments are converted to their specific names at the time that the model is fit. Other options and arguments can be set using set_engine(). If left to their defaults here (see above), the values are taken from the underlying model functions. If parameters need to be modified, update() can be used in lieu of recreating the object from scratch.

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

Engine Details

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

modeltime DeepAREstimator
id NA
freq freq
prediction_length prediction_length
lookback_length context_length (= prediction_length)
epochs epochs (5)
batch_size batch_size (32)
num_batches_per_epoch num_batches_per_epoch (50)
learn_rate learning_rate (0.001)
learn_rate_decay_factor learning_rate_decay_factor (0.5)
learn_rate_min minimum_learning_rate (5e-5)
patience patience (10)
clip_gradient clip_gradient (10)
penalty weight_decay (1e-8)
cell_type cell_type ('lstm')
num_layers num_layers (2)
num_cells num_cells (40)
dropout dropout_rate (0.1)

Other options can be set using set_engine().

Engine

gluonts_deepar

The engine uses gluonts.model.deepar.DeepAREstimator(). Default values that have been changed to prevent long-running computations:

Required Parameters

The gluonts implementation has several Required Parameters, which are user-defined.

1. ID Variable (Required):

An important difference between other parsnip models is that each time series (even single time series) must be uniquely identified by an ID variable.

2. Frequency (Required):

The GluonTS models use a Pandas Timestamp Frequency freq to generate features internally. Examples:

The Pandas Timestamps are quite flexible. Refer to Pandas Offset Aliases.

3. Prediction Length (Required):

Unlike other parsnip models, a prediction_length is required during the model specification and fitting process.

Fit Details

The following features are REQUIRED to be available in the incoming data for the fitting process.

ID Variable

An ID feature must be included in the recipe or formula fitting process. This assists with cataloging the time series inside GluonTS ListDataset. The column name must match the quoted feature name specified in the deep_ar(id = "id") expects a column inside your data named "id".

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.

See Also

fit.model_spec(), set_engine()

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
library(tidymodels)
library(tidyverse)
library(timetk)


# ---- MODEL SPEC ----
# - Important: Make sure *required* parameters are provided
model_spec <- deep_ar(

    # User Defined (Required) Parameters
    id                    = "id",
    freq                  = "M",
    prediction_length     = 24,

    # Hyper Parameters
    epochs                = 1,
    num_batches_per_epoch = 4
) %>%
    set_engine("gluonts_deepar")

model_spec

# ---- TRAINING ----
# Important: Make sure the date and id features are included as regressors
#  and do NOT dummy the id feature.
model_fitted <- model_spec %>%
    fit(value ~ date + id, m750)

model_fitted

# ---- PREDICT ----
# - IMPORTANT: New Data must have id and date features
new_data <- tibble(
    id   = factor("M750"),
    date = as.Date("2015-07-01")
)

predict(model_fitted, new_data)

modeltime.gluonts documentation built on Jan. 8, 2021, 2:23 a.m.