Numeric Variables

Learn how to incorporate external numeric variables to improve your forecasting accuracy.

What Are Exogenous Variables?

Exogenous variables or external factors are crucial in time series forecasting as they provide additional information that might influence the prediction. These variables could include holiday markers, marketing spending, weather data, or any other external data that correlate with the time series data you are forecasting.

For example, if you’re forecasting ice cream sales, temperature data could serve as a useful exogenous variable. On hotter days, ice cream sales may increase.

How to Use Exogenous Variables

To incorporate exogenous variables in TimeGPT, you’ll need to pair each point in your time series data with the corresponding external data.

Step 1: Import Packages

Import the required libraries and initialize the Nixtla client.

import pandas as pd
from nixtla import NixtlaClient

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

Step 2: Load Dataset

In this tutorial, we’ll predict day-ahead electricity prices. The dataset contains:

• Hourly electricity prices (y) from various markets (identified by unique_id)
• Exogenous variables (Exogenous1 to day_6)

df = pd.read_csv("https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-with-ex-vars.csv")
df.head()

unique_id	ds	y	Exogenous1	Exogenous2	day_0	day_1	day_2	day_3	day_4	day_5	day_6
BE	2016-10-22 00:00:00	70.00	57253.0	49593.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-10-22 01:00:00	37.10	51887.0	46073.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-10-22 02:00:00	37.10	51896.0	44927.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-10-22 03:00:00	44.75	48428.0	44483.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-10-22 04:00:00	37.10	46721.0	44338.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0

Step 3: Forecast without Exogenous Variables

First, let’s create a baseline forecast without using any exogenous variables.

timegpt_fcst_no_ex_vars = nixtla_client.forecast(
    df=df[["unique_id", "ds", "y"]],
    h=24,
    level=[80, 90]
)

Step 4: Forecasting with Exogenous Variables

Next, let’s create a forecast using the exogenous variables. To make a forecast using exogenous variables, you need to provide historical and future exogenous values. Below is an example dataset containing future exogenous variables. Note that it only contains the future exogenous variable values not the target variable y. We need to forecast this target variable using the exogenous variables provided.

future_ex_vars_df = pd.read_csv("https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-future-ex-vars.csv")
future_ex_vars_df.head()

unique_id	ds	Exogenous1	Exogenous2	day_0	day_1	day_2	day_3	day_4	day_5	day_6
BE	2016-12-31 00:00:00	70318.0	64108.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-12-31 01:00:00	67898.0	62492.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-12-31 02:00:00	68379.0	61571.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-12-31 03:00:00	64972.0	60381.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0
BE	2016-12-31 04:00:00	62900.0	60298.0	0.0	0.0	0.0	0.0	0.0	1.0	0.0

Ensure you maintain consistent data formatting and columns in both historical and future exogenous datasets (e.g., dates, unique_id, variable names).

timegpt_fcst_ex_vars = nixtla_client.forecast(
    df=df,
    X_df=future_ex_vars_df,
    h=24,
    level=[80, 90]
)

Step 5: Forecast Visualization

Once you have generated your forecasts, you can visualize the results to compare forecasts between the two methods above.

timegpt_fcst_no_ex_vars.rename(columns={"TimeGPT": "TimeGPT_no_ex_vars"}, inplace=True)
timegpt_fcst_ex_vars.rename(columns={"TimeGPT": "TimeGPT_ex_vars"}, inplace=True)

all_forecasts = (
    timegpt_fcst_no_ex_vars
    .merge(
        timegpt_fcst_ex_vars,
        how='outer',
        on=["unique_id", "ds"]
    )
)

nixtla_client.plot(
    df[["unique_id", "ds", "y"]],
    all_forecasts,
    max_insample_length=1000,
)

Key Takeaways

• Exogenous variables enrich time series forecasting.
• Ensure proper alignment of historical and future exogenous data.

Next Steps

Congratulations! You have mastered the fundamentals of adding exogenous variables to your TimeGPT forecasts. Keep refining your approach by

• Exploring feature engineering to create domain-specific exogenous data.
• Experimenting with different modeling approaches for external variables.
• Validating forecast accuracy by comparing with real future data.