Skip to contents

shaprpy

Source: .github/shaprpy.md

Python wrapper for the R package shapr.

NOTE: This wrapper is not as comprehensively tested as the R-package.

shaprpy relies heavily on the rpy2 Python library for accessing R from within Python. rpy2 has limited support on Windows. shaprpy has only been tested on Linux. The below instructions assumes a Linux environment.

shaprpy

shaprpy is a Python wrapper for the R package shapr, using the rpy2 Python library to access R from within Python.

Note: This wrapper is not as comprehensively tested as the R package. rpy2 has limited support on Windows, and the same therefore applies to shaprpy. shaprpy has only been tested on Linux (and WSL - Windows Subsystem for Linux), and the below instructions assume a Linux environment.

Requirement: Python 3.10 or later is required to use shaprpy.

Changelog

For a list of changes and updates to the shaprpy package, see the shaprpy CHANGELOG.

Installation

These instructions assume you already have pip and R installed and available to the Python environment in which you want to run shaprpy.

  • Official instructions for installing pip can be found here.
  • Official instructions for installing R can be found here.

On Debian/Ubuntu-based systems, R can also be installed via:

sudo apt update
sudo apt install r-base r-base-dev -y

1. Install the R package shapr

shaprpy requires the R package shapr (version 1.0.5 or newer). In your R environment, install the latest version from CRAN using:

Rscript -e 'install.packages("shapr", repos="https://cran.rstudio.com")'

2. Ensure R is discoverable (R_HOME and PATH)

Sometimes rpy2 (which shaprpy relies on) cannot automatically locate your R installation. To ensure proper detection, verify that: - R is available in your system PATH, or - The R_HOME environment variable is set to your R installation directory.

Example:

export R_HOME=$(R RHOME)
export PATH=$PATH:$(R RHOME)/bin

3. Install the Python wrapper

Install directly from PyPI with:

pip install shaprpy

Local development install (for contributors)

If you have cloned the repository and want to install in development mode for local changes, navigate to the ./python directory and run:

pip install -e .

The -e flag installs in editable mode, allowing local code changes to be reflected immediately.

Quick Demo

from sklearn.ensemble import RandomForestRegressor
from shaprpy import explain
from shaprpy.datasets import load_california_housing

# Load example data
dfx_train, dfx_test, dfy_train, dfy_test = load_california_housing()

# Fit a model
model = RandomForestRegressor()
model.fit(dfx_train, dfy_train.values.flatten())

# Explain predictions
explanation = explain(
    model=model,
    x_train=dfx_train,
    x_explain=dfx_test,
    approach="empirical",
    phi0=dfy_train.mean().item(),
    seed=1
)

print(explanation["shapley_values_est"])

Supported Models

shaprpy can explain predictions from models built with: - scikit-learn - keras (Sequential API) - xgboost

For other model types, you can supply: - A custom predict_model function - (Optionally) a custom get_model_specs function to shaprpy.explain.

Examples

See the /examples folder for runnable examples, including: - A custom PyTorch model - The regression paradigm described in Olsen et al. (2024), which shows: - How to specify the regression model - How to enable automatic cross-validation of hyperparameters - How to apply pre-processing steps before fitting regression models