Long-horizon forecasting Tutorial

Learn how to use the TimeGPT long-horizon model for forecasting far into the future with Nixtla client.

Long-horizon forecasting refers to predictions far into the future, typically exceeding two seasonal periods. The exact threshold depends on data frequency. The further you forecast, the more uncertainty you face. To tackle these extended prediction windows, Nixtla provides the specialized timegpt-1-long-horizon model in TimeGPT.

What is Long-Horizon Forecasting?

Long-horizon forecasting refers to predictions far into the future—typically exceeding two seasonal periods—where uncertainty grows significantly. For instance, forecasting 72 hours ahead is long-horizon for hourly data, two years ahead for monthly data, and over two weeks for daily data.

Key Challenge

Because these forecasts extend far into the future, they may be influenced by unforeseen factors not present in the initial dataset. Hence, long-horizon forecasts generally involve greater risk and uncertainty.

Solution: TimeGPT Model

To address unique challenges, Nixtla provides the specialized timegpt-1-long-horizon model. Simply specify model="timegpt-1-long-horizon" when calling nixtla_client.forecast.

For Interactive Tutorials
Check out our Google Colab notebook to run all code cells interactively.

1. 1. Import Packages

   Start by installing and importing the required packages, then initialize the Nixtla client:

   Import Packages

   from nixtla import NixtlaClient
   from datasetsforecast.long_horizon import LongHorizon
   from utilsforecast.losses import mae
   
   nixtla_client = NixtlaClient(
       api_key='my_api_key_provided_by_nixtla'  # defaults to os.environ.get("NIXTLA_API_KEY")
   )
   

   Use an Azure AI Endpoint
   To use an Azure AI endpoint, specify the base_url parameter as well:

   nixtla_client = NixtlaClient(base_url="your azure ai endpoint", api_key="your api_key")

2. 2. Load the Data

   We’ll demonstrate long-horizon forecasting using the ETTh1 dataset, which measures oil temperatures and load variations on an electricity transformer in China. Here, we only forecast oil temperatures (y):

   Load ETTh1 Dataset

   Y_df, *_ = LongHorizon.load(directory='./', group='ETTh1')
   
   Y_df.head()
   

   Download Progress & Logging

   Download Progress & Logging

   Download Log

   100%|██████████| 314M/314M [00:14<00:00, 21.3MiB/s]
   INFO:datasetsforecast.utils:Successfully downloaded datasets.zip, 314116557, bytes.
   INFO:datasetsforecast.utils:Decompressing zip file...
   INFO:datasetsforecast.utils:Successfully decompressed longhorizon\\datasets\\datasets.zip
   

   Sample Rows

   	unique_id	ds	y
   0	OT	2016-07-01 00:00:00	1.460552
   1	OT	2016-07-01 01:00:00	1.161527
   2	OT	2016-07-01 02:00:00	1.161527
   3	OT	2016-07-01 03:00:00	0.862611
   4	OT	2016-07-01 04:00:00	0.525227

   We’ll set our horizon to 96 timestamps (4 days) for testing and use the previous 42 days as input to the model:

   Setup Horizon and Input Sequence

   test = Y_df[-96:]              # 96 timestamps (4 days × 24 hours/day)
   input_seq = Y_df[-1104:-96]    # 1008 timestamps (42 days × 24 hours/day)
   
3. 3. Forecasting with the Long-Horizon Model

   TimeGPT’s timegpt-1-long-horizon model is optimized for predictions far into the future. Specify it like so:

   Forecast with TimeGPT Long-Horizon

   fcst_df = nixtla_client.forecast(
       df=input_seq,
       h=96,
       level=[90],
       finetune_steps=10,
       finetune_loss='mae',
       model='timegpt-1-long-horizon',
       time_col='ds',
       target_col='y'
   )
   

   Forecast Logging

   Forecast Log

   INFO:nixtla.nixtla_client:Validating inputs...
   INFO:nixtla.nixtla_client:Preprocessing dataframes...
   INFO:nixtla.nixtla_client:Inferred freq: H
   INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
   

   Models Available in Azure AI
   If you access Azure AI services, set model="azureai": nixtla_client.forecast(..., model="azureai")

   Next, plot the forecast along with 90% confidence intervals:

   Plot Forecast with Confidence Intervals

   nixtla_client.plot(
       Y_df[-168:],
       fcst_df,
       models=['TimeGPT'],
       level=[90],
       time_col='ds',
       target_col='y'
   )
   

   
4. 4. Evaluation

   Finally, assess forecast performance using Mean Absolute Error (MAE):

   Evaluate MAE of Forecast

   test = test.copy()
   test.loc[:, 'TimeGPT'] = fcst_df['TimeGPT'].values
   
   evaluation = mae(
       test,
       models=['TimeGPT'],
       id_col='unique_id',
       target_col='y'
   )
   
   print(evaluation)
   

   Evaluation Results

   MAE Output

     unique_id   TimeGPT
   0        OT  0.145393
   

   The model achieves a MAE of approximately 0.146, indicating strong performance for these longer-range forecasts.

Congratulations!
You’ve successfully set up a long-horizon forecasting pipeline using TimeGPT. Continue exploring to optimize model parameters, add additional covariates, or integrate Azure AI endpoints.