Historical Forecast

library(nixtlar)
#> Registered S3 method overwritten by 'tsibble':
#>   method               from 
#>   as_tibble.grouped_df dplyr

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. The key parameters of this method are:

• df: The dataframe or tsibble with the time series data. It should include at least a column with the datestamps and a column with the observations. Default names for these columns are ds and y. If different, please specify their names.
• id_col: If the data contains multiple ids, as in this case, please specify the column that contains them. If working with a single series, leave it as it is by default (NULL).
• level: The prediction intervals for the forecast.

nixtla_client_fitted_values <- nixtla_client_historic(df, id_col = "unique_id", level = c(80,95))
#> Frequency chosen: H
head(nixtla_client_fitted_values)
#>   unique_id                  ds  TimeGPT TimeGPT-lo-80 TimeGPT-lo-95
#> 1        BE 2016-10-27 00:00:00 56.07623      13.95557     -8.341764
#> 2        BE 2016-10-27 01:00:00 52.41973      10.29907    -11.998258
#> 3        BE 2016-10-27 02:00:00 52.81474      10.69408    -11.603250
#> 4        BE 2016-10-27 03:00:00 52.59026      10.46960    -11.827729
#> 5        BE 2016-10-27 04:00:00 52.67297      10.55231    -11.745015
#> 6        BE 2016-10-27 05:00:00 54.10659      11.98593    -10.311399
#>   TimeGPT-hi-80 TimeGPT-hi-95
#> 1      98.19688      120.4942
#> 2      94.54039      116.8377
#> 3      94.93540      117.2327
#> 4      94.71092      117.0082
#> 5      94.79363      117.0910
#> 6      96.22725      118.5246

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 reliable forecasts.

All the fitted values are generated using a rolling window, meaning that the fitted value for observation $T$ is generated using the first $T-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 $h$ future observations.

4. Plot historical forecast

nixtlar includes a function to plot the historical data and any output from nixtla_client_forecast, nixtla_client_historic, nixtla_client_anomaly_detection and nixtla_client_cross_validation. If you have long series, you can use max_insample_length to only plot the last N historical values (the forecast will always be plotted in full).

nixtla_client_plot(df, nixtla_client_fitted_values, id_col = "unique_id", max_insample_length = 200)
#> Frequency chosen: H