# shaprpy
Python wrapper for the R package [shapr](https://github.com/NorskRegnesentral/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](https://github.com/NorskRegnesentral/shapr),
using the [`rpy2`](https://rpy2.github.io/) 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](https://norskregnesentral.github.io/shapr/py_changelog.html).
---
## 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](https://pip.pypa.io/en/stable/installation/).
- Official instructions for installing R can be found [here](https://cran.r-project.org/).
On Debian/Ubuntu-based systems, R can also be installed via:
```bash
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:
```bash
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:
```bash
export R_HOME=$(R RHOME)
export PATH=$PATH:$(R RHOME)/bin
```
### 3. Install the Python wrapper
Install directly from PyPI with:
```bash
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:
```bash
pip install -e .
```
The `-e` flag installs in editable mode, allowing local code changes to be reflected immediately.
---
## Quick Demo
```python
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`](https://scikit-learn.org/)
- [`keras`](https://keras.io/) (Sequential API)
- [`xgboost`](https://xgboost.readthedocs.io/)
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)](https://link.springer.com/article/10.1007/s10618-024-01016-z),
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
Raw data
{
"_id": null,
"home_page": null,
"name": "shaprpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.10",
"maintainer_email": null,
"keywords": "explainable-ai, shapley-values, machine-learning, model-interpretability",
"author": "Martin Jullum, Lars Henry Berge Olsen, Didrik Nielsen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1e/46/ed0d26c4ab1827e8514b7c9db660bae0a8e8a9995afa466587c90d423369/shaprpy-0.3.0.tar.gz",
"platform": null,
"description": "# shaprpy\n\nPython wrapper for the R package [shapr](https://github.com/NorskRegnesentral/shapr).\n\nNOTE: This wrapper is not as comprehensively tested as the `R`-package.\n\n`shaprpy` relies heavily on the `rpy2` Python library for accessing R from within Python.\n`rpy2` has limited support on Windows. `shaprpy` has only been tested on Linux.\nThe below instructions assumes a Linux environment.\n\n# shaprpy\n\n`shaprpy` is a Python wrapper for the R package [shapr](https://github.com/NorskRegnesentral/shapr),\nusing the [`rpy2`](https://rpy2.github.io/) Python library to access R from within Python.\n\n> **Note:** This wrapper is **not** as comprehensively tested as the R package.\n> `rpy2` has limited support on Windows, and the same therefore applies to `shaprpy`.\n> `shaprpy` has only been tested on Linux (and WSL - Windows Subsystem for Linux), and the below instructions assume a Linux environment.\n>\n> **Requirement:** Python 3.10 or later is required to use `shaprpy`.\n\n## Changelog\n\nFor a list of changes and updates to the `shaprpy` package, see the [shaprpy CHANGELOG](https://norskregnesentral.github.io/shapr/py_changelog.html).\n\n---\n\n## Installation\n\nThese instructions assume you already have **pip** and **R** installed and available to the Python environment in which you want to run `shaprpy`.\n\n- Official instructions for installing `pip` can be found [here](https://pip.pypa.io/en/stable/installation/).\n- Official instructions for installing R can be found [here](https://cran.r-project.org/).\n\nOn Debian/Ubuntu-based systems, R can also be installed via:\n```bash\nsudo apt update\nsudo apt install r-base r-base-dev -y\n```\n\n### 1. Install the R package `shapr`\n\n`shaprpy` requires the R package `shapr` (version 1.0.5 or newer).\nIn your R environment, install the latest version from CRAN using:\n\n```bash\nRscript -e 'install.packages(\"shapr\", repos=\"https://cran.rstudio.com\")'\n```\n\n### 2. Ensure R is discoverable (R_HOME and PATH)\n\nSometimes `shaprpy` cannot automatically locate your R installation. To ensure proper detection, verify that:\n- R is available in your system `PATH`, **or**\n- The `R_HOME` environment variable is set to your R installation directory.\n\nExample:\n```bash\nexport R_HOME=$(R RHOME)\nexport PATH=$PATH:$(R RHOME)/bin\n```\n\n### 3. Install the Python wrapper\n\nInstall directly from PyPI with:\n\n```bash\npip install shaprpy\n```\n\n#### Local development install (for contributors)\nIf you have cloned the repository and want to install in development mode for local changes, navigate to the `./python` directory and run:\n```bash\npip install -e .\n```\nThe `-e` flag installs in editable mode, allowing local code changes to be reflected immediately.\n\n---\n\n## Quick Demo\n\n```python\nfrom sklearn.ensemble import RandomForestRegressor\nfrom shaprpy import explain\nfrom shaprpy.datasets import load_california_housing\n\n# Load example data\ndfx_train, dfx_test, dfy_train, dfy_test = load_california_housing()\n\n# Fit a model\nmodel = RandomForestRegressor()\nmodel.fit(dfx_train, dfy_train.values.flatten())\n\n# Explain predictions\nexplanation = explain(\n model=model,\n x_train=dfx_train,\n x_explain=dfx_test,\n approach=\"empirical\",\n phi0=dfy_train.mean().item(),\n seed=1\n)\n\nprint(explanation[\"shapley_values_est\"])\n```\n\n---\n\n## Supported Models\n\n`shaprpy` can explain predictions from models built with:\n- [`scikit-learn`](https://scikit-learn.org/)\n- [`keras`](https://keras.io/) (Sequential API)\n- [`xgboost`](https://xgboost.readthedocs.io/)\n\nFor other model types, you can supply:\n- A custom `predict_model` function\n- (Optionally) a custom `get_model_specs` function\nto `shaprpy.explain`.\n\n---\n\n## Examples\n\nSee the `/examples` folder for runnable examples, including:\n- A custom PyTorch model\n- The **regression paradigm** described in [Olsen et al. (2024)](https://link.springer.com/article/10.1007/s10618-024-01016-z),\n which shows:\n - How to specify the regression model\n - How to enable automatic cross-validation of hyperparameters\n - How to apply pre-processing steps before fitting regression models\n",
"bugtrack_url": null,
"license": "YEAR: 2019\n COPYRIGHT HOLDER: Norsk Regnesentral\n ",
"summary": "Python wrapper for the R package shapr (via rpy2)",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/NorskRegnesentral/shapr/blob/main/python/CHANGELOG.md",
"Documentation": "https://norskregnesentral.github.io/shapr/shaprpy.html",
"Homepage": "https://github.com/NorskRegnesentral/shapr",
"Issues": "https://github.com/NorskRegnesentral/shapr/issues"
},
"split_keywords": [
"explainable-ai",
" shapley-values",
" machine-learning",
" model-interpretability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ec8c062b21c75ca0e90a8bdd93917b0ea6ad1ff0ad4fb2571808e2bb00059239",
"md5": "013e333a8c2baf2375efd00d41e7b117",
"sha256": "bfd0f60273946c997fb349b2dc29c12e98d035490a2718807fd7a9bee9f1a8af"
},
"downloads": -1,
"filename": "shaprpy-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "013e333a8c2baf2375efd00d41e7b117",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.10",
"size": 13421,
"upload_time": "2025-08-27T18:23:06",
"upload_time_iso_8601": "2025-08-27T18:23:06.999240Z",
"url": "https://files.pythonhosted.org/packages/ec/8c/062b21c75ca0e90a8bdd93917b0ea6ad1ff0ad4fb2571808e2bb00059239/shaprpy-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1e46ed0d26c4ab1827e8514b7c9db660bae0a8e8a9995afa466587c90d423369",
"md5": "9d484d348464b1c609e2499b8558e8b1",
"sha256": "16e4d0d5f2e8df709f30d3333dc402706951d7a7d85784fe0d5d39ff21f33c17"
},
"downloads": -1,
"filename": "shaprpy-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "9d484d348464b1c609e2499b8558e8b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.10",
"size": 15002,
"upload_time": "2025-08-27T18:23:08",
"upload_time_iso_8601": "2025-08-27T18:23:08.413128Z",
"url": "https://files.pythonhosted.org/packages/1e/46/ed0d26c4ab1827e8514b7c9db660bae0a8e8a9995afa466587c90d423369/shaprpy-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 18:23:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NorskRegnesentral",
"github_project": "shapr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shaprpy"
}
JSON
