Quantile Forecasts

Learn how to generate quantile forecasts with TimeGPT

What Are Quantile Forecasts?

Quantile forecasts correspond to specific percentiles of the forecast distribution and provide a more complete representation of the range of possible outcomes.

• The 0.5 quantile (or 50th percentile) is the median forecast, meaning there is a 50% chance that the actual value will fall below or above this point.

• The 0.1 quantile (or 10th percentile) forecast represents a value that the actual observation is expected to fall below 10% of the time.

• The 0.9 quantile (or 90th percentile) forecast represents a value that the actual observation is expected to fall below 90% of the time.

TimeGPT supports quantile forecasts. In this tutorial, we will show you how to generate them.

Why Use Quantile Forecasts

• Quantile forecasts can provide information about best and worst-case scenarios, allowing you to make better decisions under uncertainty.

• In many real-world scenarios, being wrong in one direction is more costly than being wrong in the other. Quantile forecasts allow you to focus on the specific percentiles that matter most for your particular use case.

How to Generate Quantile Forecasts

Step 1: Import Packages

Import the required packages and initialize a Nixtla client to connect with TimeGPT.

import pandas as pd
from nixtla import NixtlaClient
from IPython.display import display

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'  # Defaults to os.environ.get("NIXTLA_API_KEY")
)

Step 2: Load Data

In this tutorial, we will use the Air Passengers dataset.

df = pd.read_csv(
    'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv'
)
df.head()

	timestamp	value
0	1949-01-01	112
1	1949-02-01	118
2	1949-03-01	132
3	1949-04-01	129
4	1949-05-01	121

Step 3: Forecast with Quantiles

To specify the desired quantiles, you need to pass a list of quantiles to the quantiles parameter. Choose quantiles between 0 and 1 based on your uncertainty analysis needs.

quantiles = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]

timegpt_quantile_fcst_df = nixtla_client.forecast(
    df=df,
    h=12,
    quantiles=quantiles,
    time_col='timestamp',
    target_col='value'
)

timegpt_quantile_fcst_df.head()

timestamp	TimeGPT	TimeGPT-q-10	TimeGPT-q-20	TimeGPT-q-30	TimeGPT-q-40	TimeGPT-q-50	TimeGPT-q-60	TimeGPT-q-70	TimeGPT-q-80	TimeGPT-q-90
1961-01-01	437.84	431.99	435.04	435.38	436.40	437.84	439.27	440.29	440.63	443.69
1961-02-01	426.06	412.70	414.83	416.04	421.72	426.06	430.41	436.08	437.29	439.42
1961-03-01	463.12	437.41	444.23	446.42	450.71	463.12	475.53	479.81	482.00	488.82
1961-04-01	478.24	448.72	455.43	465.57	469.88	478.24	486.61	490.92	501.06	507.76
1961-05-01	505.65	478.41	493.16	497.99	499.14	505.65	512.15	513.30	518.14	532.89

TimeGPT returns multiple columns in the forecast output:

• Each requested quantile gets its own column named in the format TimeGPT-q-...
• The TimeGPT column shows the mean forecast
• The mean forecast (TimeGPT) is identical to the 0.5 quantile (TimeGPT-q-50)

Step 4: Plot the Quantile Forecasts

To plot the quantile forecasts, you can use the plot method.

nixtla_client.plot(
    df,
    timegpt_quantile_fcst_df,
    time_col='timestamp',
    target_col='value'
)

The plot displays:

• The actual time series data in blue.
• Multiple forecast intervals represented by different quantiles:
  • The 0.5 quantile (50th percentile) represents the median forecast.
  • The 0.1 and 0.9 quantiles (10th and 90th percentiles) show the outer bounds of the forecast.
  • Additional quantiles (0.2, 0.3, 0.4, 0.6, 0.7, 0.8) are shown in between, creating a gradient of uncertainty.

This type of visualization is particularly useful because it:

• Shows the full distribution of possible outcomes rather than just a single point forecast.
• Helps identify best and worst-case scenarios.
• Allows decision-makers to understand the range of uncertainty in the predictions.

Step 5: Historical Forecast

You can also use quantile forecasts to forecast historical data by setting the add_history parameter to True.

timegpt_quantile_fcst_df = nixtla_client.forecast(
    df=df,
    h=12,
    quantiles=quantiles,
    time_col='timestamp',
    target_col='value',
    add_history=True, # Add historical data to the forecast
)

nixtla_client.plot(
    df,
    timegpt_quantile_fcst_df,
    time_col='timestamp',
    target_col='value'
)

The plot now includes quantile forecasts for the historical data. This allows you to evaluate how well the quantile forecasts capture the true variability and identify any systematic bias.

Step 6: Cross-Validation

To evaluate the performance of the quantile forecasts across multiple time windows, you can use the cross_validation method.

cv_df = nixtla_client.cross_validation(
    df=df,
    h=12,
    n_windows=4,
    quantiles=quantiles,
    time_col='timestamp',
    target_col='value'
)

After computing the forecasts, you can visualize the results for each cross-validation cutoff to better understand model performance over time.

cutoffs = cv_df['cutoff'].unique()

for cutoff in cutoffs:
    fig = nixtla_client.plot(
        df.tail(100),
        cv_df.query('cutoff == @cutoff').drop(columns=['cutoff', 'value']),
        time_col='timestamp',
        target_col='value'
    )
    display(fig)

Each plot shows a different cross-validation window (or cutoff) for the time series. This allows you to evaluate how well the predicted intervals capture the true values across multiple, independent forecast windows.

Congratulations! You have successfully generated quantile forecasts using TimeGPT. You also visualized historical quantile predictions and evaluated their performance through cross-validation.