This tutorial explores how the SHAP IQ package can be used to discover and visualize feature interaction in machine-learning models, using Shapley Interaction Indices.
While Shapley Values are great at explaining the individual contributions of features to AI models, they fail to capture interactions. Shapley interactions go a step further by separating individual effects from interactions, offering deeper insights—like how longitude and latitude together influence house prices. This tutorial will show you how to use the shapiq software package to explore and compute these Shapley interaction for any model. Visit the Full Codes here
Install the dependencies
Scikit-learn numpy pandas!pip overrides shapiq
Data Loading & Pre-processing
OpenML Bike sharing dataset will be used in this tutorial. We’ll divide the dataset into two training sets and two testing sets after loading it to train and evaluate models. Take a look at the Full Codes here
import shapiq
from sklearn.ensemble import RandomForestRegressor
From sklearn.metrics, import mean_absolute_error (macro), mean_squared_error (msi), r2_score
from sklearn.model_selection import train_test_split
Import numpy as an np
# Load data
X, y = shapiq.load_bike_sharing(to_numpy=True)
Separate training from testing
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
Model Training Evaluation
Model # Train
model = RandomForestRegressor()
model.fit(X_train, y_train)
# Predict
y_pred = model.predict(X_test)
# Evaluate
mae = mean_absolute_error(y_test, y_pred)
rmse = np.sqrt(mean_squared_error(y_test, y_pred))
r2 = r2_score(y_test, y_pred)
print(f"R² Score: {r2:.4f}")
print(f"Mean Absolute Error: {mae:.4f}")
print(f"Root Mean Squared Error: {rmse:.4f}")
Create an Explainer
By using the Shapley interaction index kSII, we set up TabularExplainer to use the Shapley package. The max_order=4 option allows the explainer consider up to four features at once, giving us deeper insight into the impact of groups of features on model predictions. Click here to see the Full Codes here
Create an explanation with interaction values kSII up to 4
explainer = shapiq.TabularExplainer(
model=model,
data=X,
index="k-SII",
max_order=4
)
Understanding a local instance
To generate local explanations, we select one specific test case (index number 100). This code displays the predicted and true values of this test instance. It then breaks down its features values. The code helps us to better understand how inputs are passed through the Shapley model. This context is important for understanding the Shapley interactivity explanations. Visit the Full Codes here
From tqdm.asyncio, import tqdm
Explain different orders
feature_names = list(df[0]Columns # Get feature names
n_features = len(feature_names)
Select a local example to be described
instance_id = 100
x_explain = X_test[instance_id]
y_true = y_test[instance_id]
y_pred = model.predict(x_explain.reshape(1, -1))[0]
print(f"Instance {instance_id}, True Value: {y_true}, Predicted Value: {y_pred}")
for i, feature in enumerate(feature_names):
print(f"{feature}: {x_explain[i]}")
Analysis of Interaction Values
Explainer is the tool we use to explain.() Method to calculate Shapley values for specific data instances (X[100]This will return an InteractionValues Object, which represents the influence of individual features on the output. It returns an InteractionValues Object, which contains information about how features in combination with each other affect the output. This means that interactions up to four features are considered. See the Full Codes here
interaction_values = explainer.explain(X[100], budget=256)
# Analyse interaction values
print(interaction_values)
First-Order Values of Interaction
To keep things simple, we compute first-order interaction values—i.e., standard Shapley values that capture only individual feature contributions (no interactions).
We’re telling the TreeExplainer:
“Tell me how much each feature individually contributes to the prediction, without considering any interaction effects.”
Standard Shapley Values. The average marginal contribution is calculated for every feature across all permutations. Look at the Full Codes here
feature_names = list(df[0].columns)
explainer = shapiq.TreeExplainer(model=model, max_order=1, index="SV")
si_order = explainer.explain(x=x_explain)
si_order
Waterfall chart plotting
The Waterfall Chart visually decomposes a model’s predictions into their individual contributions. The Waterfall chart starts with the base prediction, and then adds or subtracts the Shapley values of each feature to arrive at the predicted final output.
We’ll be using the output from TreeExplainer, with the max_order=1 option (i.e. individual contributions) to show the contribution each feature. Look at the Full Codes here
si_order.plot_waterfall(feature_names=feature_names, show=True)
The baseline value in our example (i.e. the expected output of the model without any feature data) is 190.717.
We can see how the individual contributions (order-1 Shapley value) push or pull the prediction.
- The features like weather and humidity have positive contributions, which increase the forecast above the baseline.
- Features like Temperature and Year have a strong negative impact, pulling the prediction down by −35.4 and −45, respectively.
Overall, the Waterfall chart helps us understand which features are driving the prediction, and in which direction—providing valuable insight into the model’s decision-making.
Take a look at the Full Codes here. Please feel free to browse our GitHub Page for Tutorials, Codes and Notebooks. Also, feel free to follow us on Twitter Don’t forget about our 100k+ ML SubReddit Subscribe Now our Newsletter.



