Quantile Forecasts

1. Uncertainty quantification via quantiles

For uncertainty quantification, TimeGPT can generate both prediction intervals and quantiles, offering a measure of the range of potential outcomes rather than just a single point forecast. In real-life scenarios, forecasting often requires considering multiple alternatives, not just one prediction. This vignette will explain how to use quantiles with TimeGPT via the nixtlar package.

Quantiles represent the cumulative proportion of the forecast distribution. For instance, the 90th quantile is the value below which 90% of the data points are expected to fall. Notably, the 50th quantile corresponds to the median forecast value provided by TimeGPT. The quantiles are produced using conformal prediction, a framework for creating distribution-free uncertainty intervals for predictive models.

This vignette 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 will 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 with quantiles

TimeGPT can generate quantiles when using the following functions:

- nixtlar::nixtla_client_forecast()
- nixtlar::nixtla_client_historic() 
- nixtlar::nixtla_client_cross_validation()

For any of these functions, simply set the quantiles argument to the desired values as a vector. Keep in mind that quantiles should all be numbers between 0 and 1. You can use either quantiles or level for uncertainty quantification, but not both.

fcst <- nixtla_client_forecast(df, h = 8, quantiles = c(0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9))
#> Frequency chosen: h
head(fcst)
#>   unique_id                  ds  TimeGPT TimeGPT-q-10 TimeGPT-q-20 TimeGPT-q-30
#> 1        BE 2016-12-31 00:00:00 45.19045     35.50842     38.47870     40.71582
#> 2        BE 2016-12-31 01:00:00 43.24445     35.37463     37.77037     39.31913
#> 3        BE 2016-12-31 02:00:00 41.95839     35.34079     37.21802     39.44543
#> 4        BE 2016-12-31 03:00:00 39.79649     32.32625     34.98683     35.96071
#> 5        BE 2016-12-31 04:00:00 39.20454     30.99895     32.74554     34.72325
#> 6        BE 2016-12-31 05:00:00 40.10878     32.43504     34.25011     35.10687
#>   TimeGPT-q-40 TimeGPT-q-50 TimeGPT-q-60 TimeGPT-q-70 TimeGPT-q-80 TimeGPT-q-90
#> 1     43.92545     45.19045     46.45545     49.66508     51.90221     54.87248
#> 2     42.58400     43.24445     43.90489     47.16976     48.71852     51.11427
#> 3     40.85600     41.95839     43.06078     44.47135     46.69876     48.57599
#> 4     37.46390     39.79649     42.12907     43.63226     44.60614     47.26672
#> 5     36.01405     39.20454     42.39502     43.68583     45.66353     47.41012
#> 6     38.76697     40.10878     41.45059     45.11069     45.96745     47.78252

4. Plot quantiles

nixtlar includes a function to plot the historical data and any output from nixtlar::nixtla_client_forecast, nixtlar::nixtla_client_historic, nixtlar::nixtla_client_detect_anomalies and nixtlar::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).

When available, nixtlar::nixtla_client_plot will automatically plot the quantiles.

nixtla_client_plot(df, fcst, max_insample_length = 100)