temporal_hierarchy: General Interface for Temporal Hierarchical Forecasting...

View source: R/parsnip-temporal_hierarchy.R

temporal_hierarchyR Documentation

General Interface for Temporal Hierarchical Forecasting (THIEF) Models


temporal_hierarchy() is a way to generate a specification of an Temporal Hierarchical Forecasting model before fitting and allows the model to be created using different packages. Currently the only package is thief. Note this function requires the thief package to be installed.


  mode = "regression",
  seasonal_period = NULL,
  combination_method = NULL,
  use_model = NULL



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.


Combination method of temporal hierarchies, taking one of the following values:

  • "struc" - Structural scaling: weights from temporal hierarchy

  • "mse" - Variance scaling: weights from in-sample MSE

  • "ols" - Unscaled OLS combination weights

  • "bu" - Bottom-up combination – i.e., all aggregate forecasts are ignored.

  • "shr" - GLS using a shrinkage (to block diagonal) estimate of residuals

  • "sam" - GLS using sample covariance matrix of residuals


Model used for forecasting each aggregation level:

  • "ets" - exponential smoothing

  • "arima" - arima

  • "theta" - theta

  • "naive" - random walk forecasts

  • "snaive" - seasonal naive forecasts, based on the last year of observed data


Models can be created using the following engines:

  • "thief" (default) - Connects to thief::thief()

Engine Details

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

modeltime thief::thief()
combination_method comb
use_model usemodel

Other options can be set using set_engine().

thief (default engine)

The engine uses thief::thief().

Function Parameters:

## function (y, m = frequency(y), h = m * 2, comb = c("struc", "mse", "ols", 
##     "bu", "shr", "sam"), usemodel = c("ets", "arima", "theta", "naive", 
##     "snaive"), forecastfunction = NULL, aggregatelist = NULL, ...)

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

Parameter Notes:

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

Fit Details

Date and Date-Time Variable

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

  • fit(y ~ date)


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

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

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

Multivariate (xregs, Exogenous Regressors)

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


  • For forecasting with temporal hierarchies see: Athanasopoulos G., Hyndman R.J., Kourentzes N., Petropoulos F. (2017) Forecasting with Temporal Hierarchies. European Journal of Operational research, 262(1), 60-74.

  • For combination operators see: Kourentzes N., Barrow B.K., Crone S.F. (2014) Neural network ensemble operators for time series forecasting. Expert Systems with Applications, 41(9), 4235-4244.

See Also

fit.model_spec(), set_engine()



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

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

# ---- HIERARCHICAL ----

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

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

modeltime documentation built on June 8, 2022, 1:07 a.m.