View source: R/modeltimeforecast.R
modeltime_forecast  R Documentation 
The goal of modeltime_forecast()
is to simplify the process of
forecasting future data.
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,
...
)
object 
A Modeltime Table 
new_data 
A 
h 
The forecast horizon (can be used instead of 
actual_data 
Reference data that is combined with the output tibble and given a 
conf_interval 
An estimated confidence interval based on the calibration data. This is designed to estimate future confidence from outofsample prediction error. 
conf_by_id 
Whether or not to produce confidence interval estimates by an ID feature.

conf_method 
Algorithm used to produce confidence intervals. All CI's are Conformal Predictions. Choose one of:

keep_data 
Whether or not to keep the 
arrange_index 
Whether or not to sort the index in rowwise chronological order (oldest to newest) or to
keep the original order of the data.
Default: 
... 
Not currently used 
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 timestamp 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 outofsample 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 outofsample errors (residuals).
The confidence interval is meanadjusted, meaning that if the mean of the residuals is nonzero, 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 outofsample 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
.
A tibble with predictions and timestamp 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
Lei, Jing, et al. "Distributionfree predictive inference for regression." Journal of the American Statistical Association 113.523 (2018): 10941111.
library(tidyverse)
library(lubridate)
library(timetk)
library(parsnip)
library(rsample)
library(modeltime)
# 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
)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.