Skip to contents

Historical Forecast

Source: vignettes/historical-forecast.Rmd
historical-forecast.Rmd
library(nixtlar)
#> Error in get(paste0(generic, ".", class), envir = get_method_env()) : 
#>   object 'type_sum.accel' not found

1. TimeGPT Historical Forecast

When generating a forecast, sometimes you might be interested in forecasting the historical observations. These predictions, known as fitted values, can help you better understand and evaluate a model’s performance over time.

TimeGPT has a method for generating fitted values, and users can call it from nixtlar. This vignette will explain how to do this. It assumes you have already set up your API key. If you haven’t done this, please read the Get Started vignette first.

2. Load data

For this vignette, we’ll use the electricity consumption dataset that is included in nixtlar, which contains the hourly prices of five different electricity markets.

df <- nixtlar::electricity
head(df)
#>   unique_id                  ds     y
#> 1        BE 2016-10-22 00:00:00 70.00
#> 2        BE 2016-10-22 01:00:00 37.10
#> 3        BE 2016-10-22 02:00:00 37.10
#> 4        BE 2016-10-22 03:00:00 44.75
#> 5        BE 2016-10-22 04:00:00 37.10
#> 6        BE 2016-10-22 05:00:00 35.61

3. Forecast historical data

To generate a forecast for the historical data, use nixtlar::nixtla_client_historic, which should include the following parameters:

  • df: The time series data, provided as a data frame, tibble, or tsibble. It must include at least two columns: one for the timestamps and one for the observations. The default names for these columns are ds and y. If your column names are different, specify them with time_col and target_col, respectively. If you are working with multiple series, you must also include a column with unique identifiers. The default name for this column is unique_id; if different, specify it with id_col.
  • level: The prediction intervals for the forecast.
nixtla_client_fitted_values <- nixtla_client_historic(df, level = c(80,95))
#> Frequency chosen: h
head(nixtla_client_fitted_values)
#>                    ds  TimeGPT TimeGPT-lo-80 TimeGPT-lo-95 TimeGPT-hi-80
#> 1 2016-10-27 00:00:00 56.07256      25.26870      8.962123      86.87642
#> 2 2016-10-27 01:00:00 52.41305      21.60919      5.302611      83.21690
#> 3 2016-10-27 02:00:00 52.80585      22.00199      5.695414      83.60971
#> 4 2016-10-27 03:00:00 52.58125      21.77739      5.470816      83.38511
#> 5 2016-10-27 04:00:00 52.66716      21.86330      5.556719      83.47102
#> 6 2016-10-27 05:00:00 54.10136      23.29750      6.990920      84.90521
#>   TimeGPT-hi-95
#> 1     103.18300
#> 2      99.52348
#> 3      99.91629
#> 4      99.69169
#> 5      99.77760
#> 6     101.21179

Notice that there are no fitted values for some of the initial observations. This is because TimeGPT requires a minimum number of values to generate a forecast for the historical data.

All the fitted values are generated using a rolling window, meaning that the fitted value for observation TT is generated using the first T−1T-1 observations.

3.1 Fitted values from nixtlar::nixtla_client_forecast

nixtlar::nixtla_client_historic is the dedicated function that calls TimeGPT’s method for generating fitted values. However, you can also use nixtlar::nixtla_client_forecast with add_history=TRUE. This will generate both a forecast for the historical data and for the next hh future observations.