Model Interpretability

​

What Are SHAP Values?

SHAP (SHapley Additive exPlanation) values use game theory concepts to explain how each feature influences machine learning forecasts. They’re particularly useful when working with exogenous (external) variables, letting you understand contributions both at individual prediction steps and across entire forecast horizons.

SHAP values can be seamlessly combined with visualization methods from the SHAP Python package for powerful plots and insights. Before proceeding, make sure you understand forecasting with exogenous features. For reference, see our tutorial on exogenous variables.

​

How to Use SHAP Values for TimeGPT

​

Install SHAP

Install the SHAP library.

pip install shap

For more details, visit the official SHAP documentation.

​

Step 1: Import Packages

Import the necessary libraries and initialize the Nixtla client.

import pandas as pd
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'  # Or use os.environ.get("NIXTLA_API_KEY")
)

​

Step 2: Load Data

We’ll use exogenous variables (covariates) to enhance electricity market forecasting accuracy. The widely known EPF dataset is available at this link. It contains hourly prices and relevant exogenous factors for five different electricity markets.

For this tutorial, we’ll focus on the Belgian electricity market (BE). The data includes:

• Hourly prices (y)
• Forecasts for load (Exogenous1) and generation (Exogenous2)
• Day-of-week indicators (one-hot encoded)

If your data relies on factors such as weather, holiday calendars, marketing, or other elements, ensure they’re similarly structured.

market = "BE"

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

df.head()

​

Step 3: Forecast with Exogenous Variables

To make forecasts with exogenous variables, you must have future data for these variables available at the time of prediction.

Before generating forecasts, ensure you have (or can generate) future exogenous values. Below, we load future exogenous features to obtain 24-step-ahead predictions:

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()

Next, create forecasts using the Nixtla API:

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

timegpt_fcst_ex_vars_df.head()

​

Step 4: Extract SHAP Values

After forecasting, you can retrieve SHAP values to see how each feature contributed to the model’s predictions.

shap_df = nixtla_client.feature_contributions
shap_df = shap_df.query("unique_id == @market")

shap_df.head()

​

Step 5: Visualization with SHAP

Visualizing SHAP values helps interpret the impact of exogenous features in detail. Below, we demonstrate three common SHAP plots.

​

Bar Plot

Use a bar plot to see the average impact of each feature across predictions:

import shap
import matplotlib.pyplot as plt

shap_columns = shap_df.columns.difference(['unique_id', 'ds', 'TimeGPT', 'base_value'])

shap_obj = shap.Explanation(
    values=shap_df[shap_columns].values,
    base_values=shap_df['base_value'].values,
    feature_names=shap_columns
)

shap.plots.bar(
    shap_obj,
    max_display=len(shap_columns),
    show=False
)

plt.title(f'SHAP values for {market}')
plt.show()

​

Waterfall Plot

A waterfall plot shows how each feature contributes to a single prediction step. Here, we select the earliest date for illustration:

selected_ds = shap_df['ds'].min()

filtered_df = shap_df[shap_df['ds'] == selected_ds]

shap_obj = shap.Explanation(
    values=filtered_df[shap_columns].values.flatten(),
    base_values=filtered_df['base_value'].values[0],
    feature_names=shap_columns
)

shap.plots.waterfall(shap_obj, show=False)

plt.title(f'Waterfall Plot: {market}, date: {selected_ds}')
plt.show()

​

Heatmap

Visualize how feature impacts vary across each forecast step. This often reveals time-dependent effects of certain variables.

shap_obj = shap.Explanation(
    values=shap_df[shap_columns].values,
    feature_names=shap_columns
)

shap.plots.heatmap(shap_obj, show=False)

plt.title(f'SHAP Heatmap (Unique ID: {market})')
plt.show()