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.

Installing the shap library is required to run the examples in this guide since it’s not included by default in the Nixtla library.

​
Installation

Install shap with pip
pip install shap

For more details, visit the official SHAP documentation.

Key Concept: SHAP

SHAP values measure the contribution of each feature to a particular forecast, making model interpretations more transparent.

Key Concept: TimeGPT/TimeGEN

TimeGPT/TimeGEN are Nixtla’s powerful forecasting models, capable of leveraging exogenous variables for improved predictive ability.

1

1. Import Packages

Import the necessary libraries and initialize the Nixtla client.

Import Nixtla Client and pandas
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")
)

Using an Azure AI endpoint?
Specify the base_url parameter to connect to your Azure AI instance:

Initialize NixtlaClient with Azure AI endpoint
nixtla_client = NixtlaClient(
    base_url="your azure ai endpoint",
    api_key="your api_key"
)
2

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.

Load EPF data for BE market
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()
3

3. Forecast with Exogenous Variables

Important: 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:

Load future exogenous variables
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:

Generate forecast with exogenous variables
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()
4

4. Extract SHAP Values

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

Retrieve SHAP values from Nixtla client
shap_df = nixtla_client.feature_contributions
shap_df = shap_df.query("unique_id == @market")

shap_df.head()
5

5. Visualization with shap

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