TimeGPT supports categorical variables to enhance your forecasts. This document shows you how to create and use custom categorical variables with SpecialDates.

Key Concept: Categorical Variables

Categorical variables are non-numeric data points that help distinguish different groups or conditions in your dataset. For example, holiday labels or season markers can be treated as categorical variables in time series forecasting.

Key Concept: SpecialDates

SpecialDates is a utility in Nixtla that allows you to define specific date-based labels (e.g., holiday periods, special events). These labels can then be merged into your main dataset as additional columns for forecasting.

1

Step 1: Import the Libraries

Import Libraries
import pandas as pd
import datetime
from nixtla import NixtlaClient
from nixtla.date_features import SpecialDates
2

Step 2: Set Up the Nixtla Client

You can either use the default endpoint or an Azure AI endpoint. Select the appropriate tab below:

Nixtla Client Default Endpoint
nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key='my_api_key_provided_by_nixtla'
)
3

Step 3: Read the Data

Load Dataset
# Read the data
df = pd.read_csv(
    "https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
4

Step 4: Create Categorical Variables

Use SpecialDates to define holiday or seasonal periods you want to label in your time series.

Define and Merge Categorical Variables
# Create categorical variables for Christmas and summer vacations
categories_dates = SpecialDates(
    special_dates={
        'christmas_vacations': [
            datetime.date(year, 12, 1) for year in range(1949, 1960 + 1)
        ],
        'summer_vacations': [
            datetime.date(year, month, 1)
            for year in range(1949, 1960 + 1)
            for month in (6, 7)
        ]
    }
)

dates = pd.date_range('1949-01-01', '1960-12-01', freq='MS')
categories_df = categories_dates(dates).reset_index(drop=True)

# Merge with the dataset
cat_df = pd.concat([df, categories_df], axis=1)
5

Step 5: Forecast with Categorical Variables

Forecast with Categorical Variables
# Forecast
forecast_df = nixtla_client.forecast(
    df=cat_df,
    h=24,
    target_col='value',
    time_col='timestamp'
)

Below is an example of the forecast process logs. These messages show up when you run the forecast, including any warnings about exogenous variables or horizon lengths.

Available models in Azure AI
If you use an Azure AI endpoint, set model="azureai" explicitly:



Azure AI Model Parameter
nixtla_client.forecast(
    ...,
    model="azureai"
)

The public API supports two models: timegpt-1 and timegpt-1-long-horizon. By default, timegpt-1 is used. See this tutorial for more details on using the timegpt-1-long-horizon model.