effector

effector an eXplainable AI package for tabular data. It:

creates global and regional effect plots
has a simple API with smart defaults, but can become flexible if needed
is model agnostic; it provides methods that can explain any underlying ML model
integrates easily with popular ML libraries, like Scikit-Learn, Tensorflow, Pytorch or any other
is fast, for both global and regional methods
provides a large collection of global and regional effects methods

📖 Documentation | 🔍 Intro to global and regional effects | 🔧 API | 🏗 Examples

Installation

Effector requires Python 3.10+:

pip install effector

This installs a lightweight core (numpy, scipy, matplotlib, tqdm) that covers PDP, ALE, RHALE and their regional variants.

ShapDP and RegionalShapDP need the heavier shap/shapiq backends (which pull in numba, scikit-learn, pandas, ...). Install them only if you use those methods:

pip install effector[shap]

Quickstart

Train an ML model

import effector
import keras
import numpy as np
import tensorflow as tf

np.random.seed(42)
tf.random.set_seed(42)

# Load dataset
bike_sharing = effector.datasets.BikeSharing(pcg_train=0.8)
X_train, Y_train = bike_sharing.x_train, bike_sharing.y_train
X_test, Y_test = bike_sharing.x_test, bike_sharing.y_test

# Define and train a neural network
model = keras.Sequential([
    keras.layers.Dense(1024, activation="relu"),
    keras.layers.Dense(512, activation="relu"),
    keras.layers.Dense(256, activation="relu"),
    keras.layers.Dense(1)
])
model.compile(optimizer="adam", loss="mse", metrics=["mae", keras.metrics.RootMeanSquaredError()])
model.fit(X_train, Y_train, batch_size=512, epochs=20, verbose=1)
model.evaluate(X_test, Y_test, verbose=1)

Wrap it in a callable

def predict(x):
    return model(x).numpy().squeeze()

Explain it with global effect plots

# Initialize the Partial Dependence Plot (PDP) object
pdp = effector.PDP(
    X_test,  # Use the test set as background data
    predict,  # Prediction function
    feature_names=bike_sharing.feature_names,  # (optional) Feature names
    target_name=bike_sharing.target_name  # (optional) Target variable name
)

# Plot the effect of a feature
pdp.plot(
    feature=3,  # Select the 3rd feature (feature: hour)
    nof_ice=200,  # (optional) Number of Individual Conditional Expectation (ICE) curves to plot
    scale_x={"mean": bike_sharing.x_test_mu[3], "std": bike_sharing.x_test_std[3]},  # (optional) Scale x-axis
    scale_y={"mean": bike_sharing.y_test_mu, "std": bike_sharing.y_test_std},  # (optional) Scale y-axis
    centering=True,  # (optional) Center PDP and ICE curves
    show_avg_output=True,  # (optional) Display the average prediction
    y_limits=[-200, 1000]  # (optional) Set y-axis limits
)

Explain it with regional effect plots

# Initialize the Regional Partial Dependence Plot (RegionalPDP)
r_pdp = effector.RegionalPDP(
    X_test,  # Test set data
    predict,  # Prediction function
    feature_names=bike_sharing.feature_names,  # Feature names
    target_name=bike_sharing.target_name  # Target variable name
)

# Summarize the subregions of the 3rd feature (temperature)
r_pdp.summary(
    features=3,  # Select the 3rd feature for the summary
    scale_x_list=[  # scale each feature with mean and std
        {"mean": bike_sharing.x_test_mu[i], "std": bike_sharing.x_test_std[i]}
        for i in range(X_test.shape[1])
    ]
)

Feature 3 - Full partition tree:
🌳 Full Tree Structure:
───────────────────────
hr 🔹 [id: 0 | heter: 0.27 | inst: 3476 | w: 1.00]
    workingday = 0.00 🔹 [id: 1 | heter: 0.14 | inst: 1114 | w: 0.32]
        temp ≤ 8.44 🔹 [id: 2 | heter: 0.07 | inst: 576 | w: 0.17]
        temp > 8.44 🔹 [id: 3 | heter: 0.10 | inst: 538 | w: 0.15]
    workingday ≠ 0.00 🔹 [id: 4 | heter: 0.14 | inst: 2362 | w: 0.68]
        yr = 0.00 🔹 [id: 5 | heter: 0.06 | inst: 1220 | w: 0.35]
        yr ≠ 0.00 🔹 [id: 6 | heter: 0.12 | inst: 1142 | w: 0.33]
--------------------------------------------------
Feature 3 - Statistics per tree level:
🌳 Tree Summary:
─────────────────
Level 0🔹heter: 0.27
    Level 1🔹heter: 0.14 | 🔻0.13 (47.97%)
        Level 2🔹heter: 0.08 | 🔻0.05 (39.15%)

The summary of feature hr (hour) says that its effect on the output is highly dependent on the value of features:

workingday, whether it is a workingday or not
temp, what is the temperature the specific hour
yr, whether it is the first or the second year of the dataset

Let's see how the effect changes on these subregions!

Is it workingday or not?

# Plot regional effects after the first-level split (workingday vs non-workingday)
for node in r_pdp.tree["feature_3"].nodes:  # Node ids depend on the fitted tree
    if node.info["level"] != 1:  # Keep only the nodes of the first-level split
        continue
    r_pdp.plot(
        feature=3,  # Feature 3 (temperature)
        node_idx=node.idx,  # Node index (workingday / non-workingday)
        nof_ice=200,  # Number of ICE curves
        scale_x_list=[  # scale features by mean and std
            {"mean": bike_sharing.x_test_mu[i], "std": bike_sharing.x_test_std[i]}
            for i in range(X_test.shape[1])
        ],
        scale_y={"mean": bike_sharing.y_test_mu, "std": bike_sharing.y_test_std},  # Scale the target
        y_limits=[-200, 1000]  # Set y-axis limits
    )

Second-level splits: is it hot or cold? is it 2011 or 2012?

# Plot regional effects after second-level splits (temperature on non-workingdays, year on workingdays)
for node in r_pdp.tree["feature_3"].nodes:
    if node.info["level"] != 2:  # Keep only the nodes of the second-level splits
        continue
    r_pdp.plot(
        feature=3,  # Feature 3 (temperature)
        node_idx=node.idx,  # Node index of the second-level splits
        nof_ice=200,  # Number of ICE curves
        scale_x_list=[  # Scale features by mean and std
            {"mean": bike_sharing.x_test_mu[i], "std": bike_sharing.x_test_std[i]}
            for i in range(X_test.shape[1])
        ],
        scale_y={"mean": bike_sharing.y_test_mu, "std": bike_sharing.y_test_std},  # Scale the target
        y_limits=[-200, 1000]  # Set y-axis limits
    )

Supported Methods

effector implements global and regional effect methods:

Method	Global Effect	Regional Effect	Reference	ML model	Speed
PDP	`PDP`	`RegionalPDP`	PDP	any	Fast for a small dataset
d-PDP	`DerPDP`	`RegionalDerPDP`	d-PDP	differentiable	Fast for a small dataset
ALE	`ALE`	`RegionalALE`	ALE	any	Fast
RHALE	`RHALE`	`RegionalRHALE`	RHALE	differentiable	Very fast
SHAP-DP	`ShapDP`	`RegionalShapDP`	SHAP	any	Fast for a small dataset and a light ML model

Method Selection Guide

From the runtime persepective there are three criterias:

is the dataset small (N<10K) or large (N>10K instances) ?
is the ML model light (runtime < 0.1s) or heavy (runtime > 0.1s) ?
is the ML model differentiable or non-differentiable ?

Trust us and follow this guide:

light + small + differentiable = any([PDP, RHALE, ShapDP, ALE, DerPDP])
light + small + non-differentiable: [PDP, ALE, ShapDP]
heavy + small + differentiable = any([PDP, RHALE, ALE, DerPDP])
heavy + small + non differentiable = any([PDP, ALE])
big + not differentiable = ALE
big + differentiable = RHALE

Citation

If you use effector, please cite it:

@misc{gkolemis2024effector,
  title={effector: A Python package for regional explanations},
  author={Vasilis Gkolemis et al.},
  year={2024},
  eprint={2404.02629},
  archivePrefix={arXiv},
  primaryClass={cs.LG}
}

Spotlight on `effector`

📚 Featured Publications

Gkolemis, Vasilis, et al.
"Fast and Accurate Regional Effect Plots for Automated Tabular Data Analysis."
Proceedings of the VLDB Endowment | ISSN 2150-8097

🎤 Talks & Presentations

LMU-IML Group Talk
Slides & Materials | LMU-IML Research
AIDAPT Plenary Meeting
Deep dive into effector
XAI World Conference 2024
Poster | Paper

🌍 Adoption & Collaborations

AIDAPT Project
Leveraging effector for explainable AI solutions.

🔍 Additional Resources

Medium Post
Effector: An eXplainability Library for Global and Regional Effects
Courses & Lists:
IML Course @ LMU
Awesome ML Interpretability
Awesome XAI
Best of ML Python

Papers that have inspired effector:

REPID: Regional Effects in Predictive Models
Herbinger et al., 2022 - Link
Decomposing Global Feature Effects Based on Feature Interactions
Herbinger et al., 2023 - Link
RHALE: Robust Heterogeneity-Aware Effects
Gkolemis Vasilis et al., 2023 - Link
DALE: Decomposing Global Feature Effects
Gkolemis Vasilis et al., 2023 - Link
Greedy Function Approximation: A Gradient Boosting Machine
Friedman, 2001 - Link
Visualizing Predictor Effects in Black-Box Models
Apley, 2016 - Link
SHAP: A Unified Approach to Model Interpretation
Lundberg & Lee, 2017 - Link
Regionally Additive Models: Explainable-by-design models minimizing feature interactions
Gkolemis Vasilis et al., 2023 - Link

License

effector is released under the MIT License.

Powered by:

AIDAPT
XMANAI