In forecasting, we are often interested in a distribution of predictions rather than only a point prediction, because we want to have a notion of the uncertainty around the forecast. To this end, we can create prediction intervals. Prediction intervals have an intuitive interpretation, as they present a specific range of the forecast distribution. For instance, a 95% prediction interval means that 95 out of 100 times, we expect the future value to fall within the estimated range. Therefore, a wider interval indicates greater uncertainty about the forecast, while a narrower interval suggests higher confidence. With TimeGPT, we can create a distribution of forecasts, and extract the prediction intervals for a required level. TimeGPT uses conformal prediction to produce the prediction intervals.

​
1. Import packages

First, we import the required packages and initialize the Nixtla client 
import pandas as pd
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key = 'my_api_key_provided_by_nixtla'
)
👍 Use an Azure AI endpoint To use an Azure AI endpoint, set the base_url argument: nixtla_client = NixtlaClient(base_url="you azure ai endpoint", api_key="your api_key")

​
2. Load data

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

​
3. Forecast with prediction intervals

When using TimeGPT for time series forecasting, you can set the level (or levels) of prediction intervals according to your requirements. Here’s how you could do it: 
timegpt_fcst_pred_int_df = nixtla_client.forecast(
    df=df, h=12, level=[80, 90, 99.7], 
    time_col='timestamp', target_col='value',
)
timegpt_fcst_pred_int_df.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
timestampTimeGPTTimeGPT-lo-99.7TimeGPT-lo-90TimeGPT-lo-80TimeGPT-hi-80TimeGPT-hi-90TimeGPT-hi-99.7
01961-01-01437.837952415.826484423.783737431.987091443.688812451.892166459.849419
11961-02-01426.062744402.833553407.694092412.704956439.420532444.431396449.291935
21961-03-01463.116577423.434092430.316893437.412564488.820590495.916261502.799062
31961-04-01478.244507444.885193446.776764448.726837507.762177509.712250511.603821
41961-05-01505.646484465.736694471.976787478.409872532.883096539.316182545.556275
📘 Available models in Azure AI If you are using an Azure AI endpoint, please be sure to set model="azureai": nixtla_client.forecast(..., model="azureai") For the public API, we support two models: timegpt-1 and timegpt-1-long-horizon. By default, timegpt-1 is used. Please see this tutorial on how and when to use timegpt-1-long-horizon. 
nixtla_client.plot(
    df, timegpt_fcst_pred_int_df, 
    time_col='timestamp', target_col='value',
    level=[80, 90],
)
It’s essential to note that the choice of prediction interval level depends on your specific use case. For high-stakes predictions, you might want a wider interval to account for more uncertainty. For less critical forecasts, a narrower interval might be acceptable.

​
Historical Forecast

You can also compute prediction intervals for historical forecasts adding the add_history=True parameter as follows: 
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()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
INFO:nixtla.nixtla_client:Calling Historical Forecast Endpoint...
timestampTimeGPTTimeGPT-lo-80TimeGPT-lo-90TimeGPT-hi-80TimeGPT-hi-90
01951-01-01135.483673111.937767105.262830159.029579165.704516
11951-02-01144.442413120.896508114.221571167.988319174.663256
21951-03-01157.191910133.646004126.971067180.737815187.412752
31951-04-01148.769379125.223473118.548536172.315284178.990221
41951-05-01140.472946116.927041110.252104164.018852170.693789
nixtla_client.plot(
    df, timegpt_fcst_pred_int_historical_df, 
    time_col='timestamp', target_col='value',
    level=[80, 90],
)