TimeGPT makes it possible to forecast product demand in the retail sector and evaluate how different pricing scenarios might affect demand. Scenario analysis offers valuable insights for informed decision-making.

Forecast product demand using price as an exogenous variable

Evaluate different pricing scenarios

1

1. Import required packages

Import the packages needed for this tutorial and initialize your Nixtla client:

import pandas as pd
import os

from nixtla import NixtlaClient
from datasetsforecast.m5 import M5

If you are using Nixtla’s standard endpoint, simply provide your API key:

Initialize NixtlaClient with Standard Endpoint
nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)
2

2. Load the M5 dataset

We will use the M5 dataset, containing product sales data from 10 US retail stores. The data includes:

DataFrameContents
Y_dfHistorical sales (y) for each product (unique_id) and date (ds).
X_dfAdditional information (exogenous variables) such as sell_price.

For a full tutorial on incorporating exogenous variables with TimeGPT, please see the dedicated documentation.

Y_df, X_df, S_df = M5.load(directory=os.getcwd())
Y_df.head(10)

Because we want price-driven demand forecasts, we’ll focus on the sell_price column:

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

3. Forecast demand using price as an exogenous variable

In this example, we forecast for a single product (FOODS_1_129_) across all 10 stores. This product exhibits frequent price changes, making it ideal for modeling price effects on demand.

products = [
    'FOODS_1_129_CA_1', 'FOODS_1_129_CA_2', 'FOODS_1_129_CA_3', 'FOODS_1_129_CA_4',
    'FOODS_1_129_TX_1', 'FOODS_1_129_TX_2', 'FOODS_1_129_TX_3',
    'FOODS_1_129_WI_1', 'FOODS_1_129_WI_2', 'FOODS_1_129_WI_3'
]

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

Merge the sales (y) and price (sell_price) data into one DataFrame:

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

Check the historical demand and pricing trends:

nixtla_client.plot(df, unique_ids=products, max_insample_length=365)

nixtla_client.plot(df, unique_ids=products, target_col='sell_price')

Now, split the data into: • Training data (df_train)
• Future exogenous data (future_ex_vars_df)

future_ex_vars_df = df.drop(columns=['y']).query("ds >= '2016-05-23'")
df_train = df.query("ds < '2016-05-23'")

Generate forecasts using TimeGPT (28 days ahead):

timegpt_fcst_df = nixtla_client.forecast(
    df=df_train,
    X_df=future_ex_vars_df,
    h=28
)
timegpt_fcst_df.head()

When using Azure AI endpoints, specify model="azureai" in the forecast call. Refer to the official tutorials for more details.

Finally, visualize your baseline forecast:

nixtla_client.plot(
    df[['unique_id', 'ds', 'y']],
    timegpt_fcst_df,
    max_insample_length=56
)
4

4. 'What if?' forecasting: exploring price changes

We’ll now explore ±5% price changes and their impact on demand. Adjust future prices, forecast demand, and compare to the baseline:

price_change = 0.05

future_ex_vars_df_plus = future_ex_vars_df.copy()
future_ex_vars_df_plus["sell_price"] *= (1 + price_change)

future_ex_vars_df_minus = future_ex_vars_df.copy()
future_ex_vars_df_minus["sell_price"] *= (1 - price_change)

timegpt_fcst_df_plus = nixtla_client.forecast(df_train, future_ex_vars_df_plus, h=28)
timegpt_fcst_df_minus = nixtla_client.forecast(df_train, future_ex_vars_df_minus, h=28)

Rename and combine the scenario forecasts:

timegpt_fcst_df_plus.rename(
    columns={'TimeGPT': f'TimeGPT+{price_change*100:.0f}%'},
    inplace=True
)

timegpt_fcst_df_minus.rename(
    columns={'TimeGPT': f'TimeGPT-{price_change*100:.0f}%'},
    inplace=True
)

timegpt_fcst_df = pd.concat(
    [
        timegpt_fcst_df,
        timegpt_fcst_df_plus.iloc[:, -1],
        timegpt_fcst_df_minus.iloc[:, -1]
    ],
    axis=1
)

Visualize all three forecasts (baseline, +5%, and –5%):

nixtla_client.plot(
    df[['unique_id', 'ds', 'y']],
    timegpt_fcst_df,
    max_insample_length=56
)