Skip to main content
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

Open In Colab
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
  • Standard Endpoint
  • Azure AI Endpoint
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
)
Price elasticity measures demand sensitivity to price changes. For more details, see this Wikipedia article.
  • Forecasting relies on historical patterns, which may not capture entirely new market conditions.
  • Include additional exogenous variables if you expect them to significantly impact sales.
  • If historical data capture major market shifts, explicitly model them for better accuracy.
⌘I