Quantile Forecasts

In nixtlar: A Software Development Kit for 'Nixtla''s 'TimeGPT'

---

library(httptest2)
.mockPaths("../tests/mocks")
start_vignette(dir = "../tests/mocks")

original_options <- options("NIXTLA_API_KEY"="dummy_api_key", digits=7)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", 
  fig.width = 12, 
  fig.height = 8
)

library(nixtlar)

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)

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))
head(fcst)

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)

options(original_options)
end_vignette()

nixtlar documentation built on Oct. 30, 2024, 5:07 p.m.