Bounded forecasting ensures predictions remain within a meaningful range (for example, keeping forecasts positive). This tutorial shows how to generate bounded forecasts with TimeGPT by transforming data prior to forecasting.

Bounded Forecasting

Ensures forecasts remain within valid ranges (e.g., non-negative sales predictions).

Data Transformation

Methods like log-transformations help enforce bounds and improve model stability.

TimeGPT Integration

Easily apply transformations and forecast with intervals using TimeGPT’s API.

1

1. Import Packages

In this step, you’ll install and import the required packages. The NixtlaClient from nixtla is used to connect with TimeGPT.

import_packages.py
import pandas as pd
import numpy as np

from nixtla import NixtlaClient

Initialize your Nixtla client with the API key:

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

2. Load Data

We’ll use the annual egg prices dataset from Forecasting: Principles and Practice. Because egg prices should not be negative, they are ideal for demonstrating bounded forecasts.

If you haven’t already, install pyreadr to read R data formats.

pip install pyreadr

import pyreadr
from pathlib import Path

url = 'https://github.com/robjhyndman/fpp3package/raw/master/data/prices.rda'
dst_path = str(Path.cwd().joinpath('prices.rda'))
result = pyreadr.read_r(pyreadr.download_file(url, dst_path), dst_path)

df = result['prices'][['year', 'eggs']]
df = df.dropna().reset_index(drop=True)
df = df.rename(columns={'year': 'ds', 'eggs': 'y'})
df['ds'] = pd.to_datetime(df['ds'], format='%Y')
df['unique_id'] = 'eggs'

df.tail(10)

Without showing the full table output here, the last 10 rows look like:

unique_iddsyProduct
841984-01-01100.58eggs
851985-01-0176.84eggs
861986-01-0181.10eggs
871987-01-0169.60eggs
881988-01-0164.55eggs
891989-01-0180.36eggs
901990-01-0179.79eggs
911991-01-0174.79eggs
921992-01-0164.86eggs
931993-01-0162.27eggs

Finally, let’s visualize the historical trend of egg prices during the 20th century:

nixtla_client.plot(df)

Figure 1: Annual Egg Prices Trend from 1900s to 1990s

3

3. Generate Bounded Forecasts

Bounded forecasts can be achieved through transformations. Log-transformation is a convenient way to ensure forecasts remain positive.

First, apply a log transformation to the target variable (y) before forecasting:

df_transformed = df.copy()
df_transformed['y'] = np.log(df_transformed['y'])

Next, create forecasts for the next 10 years with confidence intervals at 80%, 90%, and 99.5%:

timegpt_fcst_with_transform = nixtla_client.forecast(
df=df_transformed,
h=10,
freq='Y',
level=[80, 90, 99.5]
)

Available models with Azure AI
If you’re using an Azure AI endpoint, specify model="azureai" explicitly.
Default supported models are timegpt-1 and timegpt-1-long-horizon.
More details in the long horizon forecasting tutorial.

Reverse the log-transformation by exponentiating the forecasted values:

cols_to_transform = [
col for col in timegpt_fcst_with_transform if col not in ['unique_id', 'ds']
]

for col in cols_to_transform:
timegpt_fcst_with_transform[col] = np.exp(timegpt_fcst_with_transform[col])

Finally, plot the forecasts with intervals:

nixtla_client.plot(
df,
timegpt_fcst_with_transform,
level=[80, 90, 99.5],
max_insample_length=20
)

Figure 2: Bounded Forecasts with TimeGPT Using Log Transformation

Log-transformations are a simple and effective way to enforce non-negative predictions. This tutorial demonstrated how TimeGPT accommodates bounded forecasts to enhance forecast realism and reliability.