​
What Are Prediction Intervals?

A prediction interval provides a range where a future observation of a time series is expected to fall, with a specific level of probability. For example, a 95% prediction interval means that the true future value is expected to lie within this range 95 times out of 100. Wider intervals reflect greater uncertainty, while narrower intervals indicate higher confidence in the forecast. With TimeGPT, you can easily generate prediction intervals for any confidence level between 0% and 100%. These intervals are constructed using conformal prediction, a distribution-free framework for uncertainty quantification. Prediction intervals differ from confidence intervals:
  • Prediction Intervals: Capture the uncertainty in future observations.
  • Confidence Intervals: Quantify the uncertainty in the estimated model parameters (e.g., the mean).
As a result, prediction intervals are typically wider, as they account for both model and data variability.

​
How to Generate Prediction Intervals

Open In Colab

​
Step 1: Import Packages

Import the required packages and initialize the Nixtla client. 
import pandas as pd
from nixtla import NixtlaClient

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()
timestampvalue
01949-01-01112
11949-02-01118
21949-03-01132
31949-04-01129
41949-05-01121

​
Step 3: Forecast with Prediction Intervals

To generate prediction intervals with TimeGPT, provide a list of desired confidence levels using the level argument. Note that accepted values are between 0 and 100.
  • Higher confidence levels provide more certainty that the true value will be captured, but result in wider, less precise intervals.
  • Lower confidence levels provide less certainty that the true value will be captured, but result in narrower, more precise intervals. 
timegpt_fcst_pred_int_df = nixtla_client.forecast(
    df=df,
    h=12,
    level=[80, 90, 99],
    time_col='timestamp',
    target_col='value',
)

timegpt_fcst_pred_int_df.head()
timestampTimeGPTTimeGPT-hi-80TimeGPT-hi-90TimeGPT-hi-99TimeGPT-lo-80TimeGPT-lo-90TimeGPT-lo-99
1961-01-01437.84443.69451.89459.28431.99423.78416.40
1961-02-01426.06439.42444.43448.94412.70407.70403.19
1961-03-01463.12488.83495.92502.31437.41430.31423.93
1961-04-01478.24507.77509.72511.47448.72446.77445.02
1961-05-01505.65532.89539.32545.12478.41471.97466.18
You can visualize the prediction intervals using the plot method. To do so, specify the confidence levels to display using the level argument. 
nixtla_client.plot(
  df, 
  timegpt_fcst_pred_int_df, 
  time_col='timestamp', 
  target_col='value',
  level=[80, 90, 99]
)

​
Step 4: Historical Forecast

You can also generate prediction intervals for historical forecasts by setting add_history=True. 
timegpt_fcst_pred_int_historical_df = nixtla_client.forecast(
      df=df,
      h=12,
      level=[80, 90],
      time_col='timestamp',
      target_col='value',
      add_history=True,
  )

timegpt_fcst_pred_int_historical_df.head()
Plot the prediction intervals for the historical forecasts. 
nixtla_client.plot(
  df, 
  timegpt_fcst_pred_int_historical_df, 
  time_col='timestamp', 
  target_col='value', 
  level=[80,90,99]
)

​
Step 5. Cross-Validation

You can use the cross_validation method to generate prediction intervals for each time window. 
cv_df = nixtla_client.cross_validation(
    df=df,
    h=12,
    n_windows=4,
    level=[80, 90, 99],
    time_col='timestamp',
    target_col='value'
)
cv_df.head()
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']),
        level=[80,90,99],
        time_col='timestamp',
        target_col='value', 
    )
    display(fig)
Congratulations! You have successfully generated prediction intervals using TimeGPT. You also visualized historical forecasts with intervals and evaluated their coverage across multiple time windows using cross-validation.