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 shaprpy 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

To install from TestPyPI (for testing the package before the official release), run:

python -m pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple shaprpy

The --extra-index-url flag ensures that dependencies (such as rpy2, numpy, etc.) are installed from the main PyPI repository.

Once shaprpy is available on the official PyPI, you will be able to install it directly 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