shapr

shapr: An R-package for explaining machine learning models with dependence-aware Shapley values - Published in JOSS (2019)

https://github.com/norskregnesentral/shapr

Keywords

Scientific Fields

Repository

Explaining the output of machine learning models with more accurately estimated Shapley values

README.Rmd

---
output: github_document
bibliography: ./inst/REFERENCES.bib
link-citations: yes
---



```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  tidy = "styler"
)
```

# shapr 


[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/shapr)](https://cran.r-project.org/package=shapr)
[![CRAN_Downloads_Badge](https://cranlogs.r-pkg.org/badges/grand-total/shapr)](https://cran.r-project.org/package=shapr)
[![R build status](https://github.com/NorskRegnesentral/shapr/workflows/R-CMD-check/badge.svg)](https://github.com/NorskRegnesentral/shapr/actions?query=workflow%3AR-CMD-check)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit)
[![JOSS (v0.2.3)](https://img.shields.io/badge/JOSS (v0.2.3)-10.21105/joss.02027-brightgreen.svg)](https://doi.org/10.21105/joss.02027)
[![arXiv (v1.0.4)](https://img.shields.io/badge/arXiv (v1.0.4)-2504.01842-b31b1b.svg)](https://arxiv.org/abs/2504.01842)


See the pkgdown site at [norskregnesentral.github.io/shapr/](https://norskregnesentral.github.io/shapr/)
for a complete introduction with examples and documentation of the package.

For an overview of the methodology and capabilities of the package (per `shapr` v1.0.4),
see the software paper @jullum2025shapr, available as a preprint [here](https://arxiv.org/abs/2504.01842).




## NEWS

With `shapr` version 1.0.0 (GitHub only, Nov 2024) and version 1.0.1 (CRAN, Jan 2025),
the package underwent a major update, providing a full restructuring of the code base, and
a full suite of new functionality, including:

* A long list of approaches for estimating the contribution/value function $v(S)$, including Variational Autoencoders
  and regression-based methods
* Iterative Shapley value estimation with convergence detection
* Parallelized computations with progress updates
* Reweighted Kernel SHAP for faster convergence
* New function `explain_forecast()` for explaining forecasts
* Asymmetric and causal Shapley values
* Several other methodological, computational and user-experience improvements
* Python wrapper `shaprpy` making the core functionality of `shapr` available in Python


See the [NEWS](https://norskregnesentral.github.io/shapr/news/index.html) for a complete list.

### Coming from shapr < 1.0.0?
`shapr` version >= 1.0.0 comes with a number of breaking changes.
Most notably, we moved from using two functions (`shapr()` and `explain()`) to
one function (`explain()`).
In addition, custom models are now explained by passing the prediction function directly to `explain()`.
Several input arguments were renamed, and a few functions for edge cases were removed to simplify the code base.

Click [here](https://github.com/NorskRegnesentral/shapr/blob/cranversion_0.2.2/README.md) to view a version of this README with the old syntax (v0.2.2).

### Python wrapper

We provide a Python wrapper (`shaprpy`) which allows explaining Python models with the methodology
implemented in `shapr`, directly from Python.
The wrapper calls R internally and therefore requires an installation of R.
See [here](https://norskregnesentral.github.io/shapr/shaprpy.html) for installation instructions and examples.


## The package

The `shapr` R package implements an enhanced version of the Kernel SHAP method for approximating Shapley values,
with a strong focus on conditional Shapley values.
The core idea is to remain completely model-agnostic while offering a variety of methods for estimating contribution 
functions, enabling accurate computation of conditional Shapley values across different feature types, dependencies, 
and distributions. 
The package also includes evaluation metrics to compare various approaches. 
With features like parallelized computations, convergence detection, progress updates, and extensive plotting options,
shapr is a highly efficient and user-friendly tool, delivering precise estimates of conditional Shapley values,
which are critical for understanding how features truly contribute to predictions.

A basic example is provided below.
Otherwise, we refer to the [pkgdown website](https://norskregnesentral.github.io/shapr/) and the vignettes there for details and further examples.


## Installation

`shapr` is available on [CRAN](https://cran.r-project.org/package=shapr) and can be installed in R as:

```{r, eval = FALSE}
install.packages("shapr")
```

To install the development version of `shapr`, available on GitHub, use

```{r, eval = FALSE}
remotes::install_github("NorskRegnesentral/shapr")
```

To also install all dependencies, use

```{r, eval = FALSE}
remotes::install_github("NorskRegnesentral/shapr", dependencies = TRUE)
```


## Example
`shapr` supports computation of Shapley values with any predictive model that takes a set of numeric features and produces a numeric outcome.

The following example shows how a simple `xgboost` model is trained using the *airquality* dataset, and how `shapr` explains the individual predictions. 

We first enable parallel computation and progress updates with the following code chunk.
These are optional, but recommended for improved performance and user-friendliness,
particularly for problems with many features.

```{r init_no_eval,eval = FALSE}
# Enable parallel computation
# Requires the future and future_lapply packages
future::plan("multisession", workers = 2) # Increase the number of workers for increased performance with many features

# Enable progress updates of the v(S) computations
# Requires the progressr package
progressr::handlers(global = TRUE)
progressr::handlers("cli") # Using the cli package as backend (recommended for the estimates of the remaining time)
```

Here is the actual example:
```{r basic_example, warning = FALSE}
library(xgboost)
library(shapr)

data("airquality")
data <- data.table::as.data.table(airquality)
data <- data[complete.cases(data), ]

x_var <- c("Solar.R", "Wind", "Temp", "Month")
y_var <- "Ozone"

ind_x_explain <- 1:6
x_train <- data[-ind_x_explain, ..x_var]
y_train <- data[-ind_x_explain, get(y_var)]
x_explain <- data[ind_x_explain, ..x_var]

# Look at the dependence between the features
cor(x_train)

# Fit a basic xgboost model to the training data
model <- xgboost(
  data = as.matrix(x_train),
  label = y_train,
  nround = 20,
  verbose = FALSE
)

# Specify phi_0, i.e., the expected prediction without any features
p0 <- mean(y_train)

# Compute Shapley values with Kernel SHAP, accounting for feature dependence using
# the empirical (conditional) distribution approach with bandwidth parameter sigma = 0.1 (default)
explanation <- explain(
  model = model,
  x_explain = x_explain,
  x_train = x_train,
  approach = "empirical",
  phi0 = p0,
  seed = 1
)

# Print the Shapley values for the observations to explain.
print(explanation)

# Provide a formatted summary of the shapr object
summary(explanation)

# Finally, we plot the resulting explanations
plot(explanation)
```

See @jullum2025shapr (preprint available [here](https://arxiv.org/abs/2504.01842)) for a software paper with an overview of the methodology and capabilities of the
package (as of v1.0.4).
See the [general usage vignette](https://norskregnesentral.github.io/shapr/articles/general_usage.html) for further 
basic usage examples and brief introductions to the methodology. 
For more thorough information about the underlying methodology, see methodological papers
@aas2019explaining, @redelmeier2020explaining, @jullum2021efficient, @olsen2022using, @olsen2024comparative.
See also @sellereite2019shapr for a very brief paper about a previous version (v0.1.1) of the package
(with a different structure, syntax, and significantly less functionality).

## Contribution

All feedback and suggestions are very welcome. Details on how to contribute can be found 
[here](https://norskregnesentral.github.io/shapr/CONTRIBUTING.html). If you have any questions or comments, feel
free to open an issue [here](https://github.com/NorskRegnesentral/shapr/issues). 

Please note that the `shapr` project is released with a
[Contributor Code of Conduct](https://norskregnesentral.github.io/shapr/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms. 

## References

Owner

JOSS Publication

shapr: An R-package for explaining machine learning models with dependence-aware Shapley values

Published

February 05, 2020

DOI

10.21105/joss.02027

Volume 5, Issue 46, Page 2027

Authors

Nikolai Sellereite
Norwegian Computing Center

Martin Jullum
Norwegian Computing Center

Editor

Yuan Tang

Tags

explainable AI interpretable machine learning shapley values feature dependence

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages