Categorical Variables

​

What Are Categorical Variables?

Categorical variables are external factors that take on a limited range of discrete values, grouping observations by categories. For example, “Sporting” or “Cultural” events in a dataset describing product demand.

By capturing unique external conditions, categorical variables enhance the predictive power of your model and can reduce forecasting error. They are easy to incorporate by merging each time series data point with its corresponding categorical data.

This tutorial demonstrates how to incorporate categorical (discrete) variables into TimeGPT forecasts.

​

How to Use Categorical Variables in TimeGPT

​

Step 1: Import Packages and Initialize the Nixtla Client

Make sure you have the necessary libraries installed: pandas, nixtla, and datasetsforecast.

import pandas as pd
import os

from nixtla import NixtlaClient
from datasetsforecast.m5 import M5

# Initialize the Nixtla Client
nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)

​

Step 2: Load M5 Data

We use the M5 dataset — a collection of daily product sales demands across 10 US stores — to showcase how categorical variables can improve forecasts.

Start by loading the M5 dataset and converting the date columns to datetime objects.

Y_df, X_df, _ = M5.load(directory=os.getcwd())

Y_df['ds'] = pd.to_datetime(Y_df['ds'])
X_df['ds'] = pd.to_datetime(X_df['ds'])

Y_df.head(10)

Extract the categorical columns from the X_df dataframe.

X_df = X_df[['unique_id', 'ds', 'event_type_1']]
X_df.head(10)

Notice that there is a Sporting event on February 6, 2011, listed under event_type_1.

​

Step 3: Prepare Data for Forecasting

We’ll select a specific product to demonstrate how to incorporate categorical features into TimeGPT forecasts.

​

Select a High-Selling Product and Merge Data

Start by selecting a high-selling product and merging the data.

product = 'FOODS_3_090_CA_3'

Y_df_product = Y_df.query('unique_id == @product')
X_df_product = X_df.query('unique_id == @product')

df = Y_df_product.merge(X_df_product)
df.head(10)

​

One-Hot Encode Categorical Events

Encode categorical variables using one-hot encoding. One-hot encoding transforms each category into a separate column containing binary indicators (0 or 1).

event_type_1_ohe = pd.get_dummies(df['event_type_1'], dtype=int)

df = pd.concat([df, event_type_1_ohe], axis=1)
df = df.drop(columns=['event_type_1'])

df.tail(10)

​

Prepare Future External Variables

Select future external variables for Feb 1-7, 2016.

future_ex_vars_df = df.drop(columns=['y']).query("ds >= '2016-02-01' & ds <= '2016-02-07'")

Separate training data before Feb 1, 2016.

df_train = df.query("ds < '2016-02-01'")
df_train.tail(10)

​

Step 4: Forecast Product Demand

To evaluate the impact of categorical variables, we’ll forecast product demand with and without them.

​

Forecast Without Categorical Variables

timegpt_fcst_without_cat_vars_df = nixtla_client.forecast(
    df=df_train,
    h=7,
    level=[80, 90]
)

timegpt_fcst_without_cat_vars_df.head()

Visualize the forecast without categorical variables.

nixtla_client.plot(
    df[['unique_id', 'ds', 'y']].query("ds <= '2016-02-07'"),
    timegpt_fcst_without_cat_vars_df,
    max_insample_length=28,
)

TimeGPT already provides a reasonable forecast, but it seems to somewhat underforecast the peak on the 6th of February 2016 - the day before the Super Bowl.

​

Forecast With Categorical Variables

timegpt_fcst_with_cat_vars_df = nixtla_client.forecast(
    df=df_train,
    X_df=future_ex_vars_df,
    h=7,
    level=[80, 90]
)

timegpt_fcst_with_cat_vars_df.head()

Visualize the forecast with categorical variables.

# Visualize the forecast with categorical variables
nixtla_client.plot(
    df[['unique_id', 'ds', 'y']].query("ds <= '2016-02-07'"),
    timegpt_fcst_with_cat_vars_df,
    max_insample_length=28,
)

​

5. Evaluate Forecast Accuracy

Finally, we calculate the Mean Absolute Error (MAE) for the forecasts with and without categorical variables.

# Create target dataframe
df_target = df[['unique_id', 'ds', 'y']].query("ds >= '2016-02-01' & ds <= '2016-02-07'")

# Rename forecast columns
timegpt_fcst_without_cat_vars_df = timegpt_fcst_without_cat_vars_df.rename(columns={'TimeGPT': 'TimeGPT-without-cat-vars'})
timegpt_fcst_with_cat_vars_df = timegpt_fcst_with_cat_vars_df.rename(columns={'TimeGPT': 'TimeGPT-with-cat-vars'})

# Merge forecasts with target dataframe
df_target = df_target.merge(timegpt_fcst_without_cat_vars_df[['unique_id', 'ds', 'TimeGPT-without-cat-vars']])
df_target = df_target.merge(timegpt_fcst_with_cat_vars_df[['unique_id', 'ds', 'TimeGPT-with-cat-vars']])

# Compute errors
mean_absolute_errors = mae(df_target, ['TimeGPT-without-cat-vars', 'TimeGPT-with-cat-vars'])

Including categorical variables noticeably improves forecast accuracy, reducing MAE by about 20%.

​

Conclusion

Categorical variables are powerful additions to TimeGPT forecasts, helping capture valuable external factors. By properly encoding these variables and merging them with your time series, you can significantly enhance predictive performance.

Continue exploring more advanced techniques or different datasets to further improve your TimeGPT forecasting models.