qshap 0.3.8

Exact computation of Shapley R-squared for tree ensembles in polynomial time

Q-SHAP: Feature-Specific $R^2$ Values for Tree Ensembles

This package is used to compute feature-specific $R^2$ values, following Shapley decomposition of the total $R^2$, for tree ensembles in polynomial time based on the paper.

This version supports XGBoost, LightGBM, CatBoost, scikit-learn Decision Tree, and scikit-learn GBDT regression models. We are working to update it for random forests in the next version. Please check Q-SHAP Tutorial for more details using Q-SHAP.

Installation

qshap can be installed through PyPI:

pip install qshap

Install the model libraries you need with optional extras:

pip install "qshap[xgboost]"
pip install "qshap[lightgbm]"
pip install "qshap[catboost]"

# Or install all supported boosting backends:
pip install "qshap[all]"

Q-SHAP uses a compiled C++ backend for the core second-order tree calculation when available. To force the original numba implementation for comparison or debugging, pass backend="numba" to gazer.loss() or gazer.rsq().

Imports

Use the import that matches the model backend you fit:

import numpy as np
from qshap import gazer, vis

# Pick one or more model libraries:
import xgboost as xgb
import lightgbm as lgb
import catboost as cb

Quick Start with XGBoost

from ISLP import load_data
import numpy as np
import xgboost as xgb
from qshap import gazer, vis

boston = load_data("Boston")

# ---- Load Boston Housing from ISLP ----
y = boston["medv"].to_numpy(dtype=np.float64)

# Features = everything except medv
X_df = boston.drop(columns=["medv"])
x = X_df.to_numpy(dtype=np.float64)

feature_names = X_df.columns.to_numpy()

# ---- Fit a XGBoost regressor ----
model = xgb.XGBRegressor(
    max_depth=2,
    n_estimators=50,
    random_state=42,
    learning_rate=0.1,
).fit(x, y)

# ---- Obtain feature-specific R^2 using qshap ----
g = gazer(model)

phi_rsq = g.rsq(x, y)


# ---- Visualize top feature-specific R^2 ----
vis.rsq(
    phi_rsq,
    label=feature_names,
    rotation=30,
    save_name="boston_housing",
    color_map_name="Pastel2"
)

The same gazer(model).rsq(x, y) call works for LightGBM:

import lightgbm as lgb
from qshap import gazer

model = lgb.LGBMRegressor(
    max_depth=2,
    n_estimators=50,
    learning_rate=0.1,
    verbose=-1,
    random_state=42,
).fit(x, y)

phi_rsq = gazer(model).rsq(x, y)

And for CatBoost:

import catboost as cb
from qshap import gazer

model = cb.CatBoostRegressor(
    depth=2,
    iterations=50,
    learning_rate=0.1,
    loss_function="RMSE",
    verbose=False,
    allow_writing_files=False,
    random_seed=42,
).fit(x, y)

phi_rsq = gazer(model).rsq(x, y)

Citation

@inproceedings{10.5555/3762387.3762469,
author = {Jiang, Zhongli and Zhang, Min and Zhang, Dabao},
title = {Fast calculation of feature contributions in boosting trees},
year = {2025},
publisher = {JMLR.org},
numpages = {17},
location = {Rio de Janeiro, Brazil},
series = {UAI '25}
}

Reference

• Jiang, Z., Zhang, M., & Zhang, D. (2025). Fast calculation of feature contributions in boosting trees. Proceedings of the 41st Conference on Uncertainty in Artificial Intelligence (UAI), 82:1859 - 1875

Container Images

We provide pre-built images, available for both Docker and Singularity, with all necessary packages for Q-SHAP in Python 3.12:

• Docker:
  You can pull the Docker image using the following command:

  docker pull catstat/xai
  

• Singularity:
  You can pull the Docker image using the following command:

  singularity pull docker://catstat/xai:0.1