​
Quantile Forecasts

Forecasting often goes beyond a single point estimate. Quantile forecasts offer a distribution that communicates uncertainty, allowing for better decision-making and planning.

In forecasting, users are frequently interested in a range of possible future values rather than one “best guess.” Quantile forecasts achieve this by estimating specific percentiles of the forecast distribution. For example, saying “We predict that 90% of air passenger observations will be greater than 100” makes the uncertainty around forecasts more transparent.

TimeGPT uses conformal prediction to generate a complete distribution of forecasts. By extracting specific quantiles—like 25th and 75th percentiles—we can gain insights into where the forecast may lie. The 50th quantile (median) is a central estimate which can also help in planning while considering uncertainty.

Distribution of predictions

Going beyond a point forecast means planning with high and low scenarios in mind.

Conformal prediction

This method helps generate reliable intervals for forecasts by wrapping model outputs in a predictive distribution.

Quantile utility

Different quantiles can answer questions about worst- or best-case scenarios.

1

1. Import Packages

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

Initialize Nixtla Client
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")
)
2

2. Load Data

Load the air passengers dataset and do a quick preview to confirm it’s loaded correctly.

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

3. Forecast with Quantiles

Specify the quantiles you would like to retrieve, and perform a forecast with TimeGPT.

Forecast Quantiles with TimeGPT
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()

TimeGPT returns columns in the form TimeGPT-q-... for each requested quantile.

Choose quantiles based on the range of uncertainty you want to capture for your planning or decision-making needs.

Plot the forecasts:

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

An example quantile forecast visualization

4

4. Historical Forecast

Add historical forecasts to analyze past performance at various quantiles.

Historical Forecast with Added History
timegpt_quantile_fcst_df = nixtla_client.forecast(
    df=df,
    h=12,
    quantiles=quantiles,
    time_col='timestamp',
    target_col='value',
    add_history=True
)

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

Example historical forecast visualization

5

5. Cross Validation

Compute quantile forecasts using cross-validation to evaluate how forecasts perform across multiple time windows.

Cross-validation Quantile Forecasts
cv_df = nixtla_client.cross_validation(
    df=df,
    h=12,
    n_windows=5,
    quantiles=quantiles,
    time_col='timestamp',
    target_col='value'
)

Then visualize forecasts for each cross-validation cutoff:

Visualize Cross-val Forecasts
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)

Cross-validation plot for a single cutoff

Repeat for each cutoff to compare forecasts across multiple windows.

Congratulations! You have successfully generated quantile forecasts using TimeGPT, visualized historical predictions, and performed cross-validation. You now have a flexible framework to capture prediction uncertainty for better decision-making.