# Quantile Forecasts

    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)
    #>   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)