{"id":13857624,"url":"https://github.com/NorskRegnesentral/shapr","last_synced_at":"2025-07-13T22:30:50.302Z","repository":{"id":38195516,"uuid":"133624629","full_name":"NorskRegnesentral/shapr","owner":"NorskRegnesentral","description":"Explaining the output of machine learning models with more accurately estimated Shapley values","archived":false,"fork":false,"pushed_at":"2024-05-29T19:29:48.000Z","size":42510,"stargazers_count":135,"open_issues_count":31,"forks_count":30,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-29T20:02:54.826Z","etag":null,"topics":["explainable-ai","explainable-ml","rcpp","rcpparmadillo","rstats","shapley"],"latest_commit_sha":null,"homepage":"https://norskregnesentral.github.io/shapr/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NorskRegnesentral.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-16T07:05:13.000Z","updated_at":"2024-05-31T15:01:45.417Z","dependencies_parsed_at":"2024-02-15T16:50:02.083Z","dependency_job_id":"ce46dad5-7fda-400e-99d5-70169b8e35a5","html_url":"https://github.com/NorskRegnesentral/shapr","commit_stats":{"total_commits":207,"total_committers":8,"mean_commits":25.875,"dds":"0.49275362318840576","last_synced_commit":"c2d0a11337491e7194aa0beb2df332e169527bd0"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorskRegnesentral%2Fshapr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorskRegnesentral%2Fshapr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorskRegnesentral%2Fshapr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorskRegnesentral%2Fshapr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NorskRegnesentral","download_url":"https://codeload.github.com/NorskRegnesentral/shapr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225920424,"owners_count":17545492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["explainable-ai","explainable-ml","rcpp","rcpparmadillo","rstats","shapley"],"created_at":"2024-08-05T03:01:42.220Z","updated_at":"2025-07-13T22:30:50.246Z","avatar_url":"https://github.com/NorskRegnesentral.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\nbibliography: ./inst/REFERENCES.bib\nlink-citations: yes\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\",\n  tidy = \"styler\"\n)\n```\n\n# shapr \u003cimg src=\"man/figures/nrlogo_new.jpg\" align=\"right\" height=\"100\"/\u003e\n\n\u003c!-- badges: start --\u003e\n[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/shapr)](https://cran.r-project.org/package=shapr)\n[![CRAN_Downloads_Badge](https://cranlogs.r-pkg.org/badges/grand-total/shapr)](https://cran.r-project.org/package=shapr)\n[![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)\n[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit)\n[![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)\n[![arXiv (v1.0.4)](https://img.shields.io/badge/arXiv (v1.0.4)-2504.01842-b31b1b.svg)](https://arxiv.org/abs/2504.01842)\n\u003c!-- badges: end --\u003e\n\nSee the pkgdown site at [norskregnesentral.github.io/shapr/](https://norskregnesentral.github.io/shapr/)\nfor a complete introduction with examples and documentation of the package.\n\nFor an overview of the methodology and capabilities of the package (per `shapr` v1.0.4), \nsee the software paper @jullum2025shapr, available in preprint [here](https://arxiv.org/abs/2504.01842).\n\n\n\n\n## NEWS\n\nWith `shapr` version 1.0.0 (GitHub only, Nov 2024) and version 1.0.1 (CRAN, Jan 2025),\nthe package was subject to a major update, providing a full restructuring of the code based, and \na full suit of new functionality, including:\n\n* A long list of approaches for estimating the contribution/value function $v(S)$, including Variational Autoencoders,\nand regression-based methods\n* Iterative Shapley value estimation with convergence detection\n* Parallelized computations with progress updates\n* Reweighted Kernel SHAP for faster convergence\n* New function `explain_forecast()` for explaining forecasts\n* Asymmetric and causal Shapley values\n* Several other methodological, computational and user-experience improvements\n* Python wrapper `shaprpy` making the core functionality of `shapr` available in Python\n\n\nSee the [NEWS](https://norskregnesentral.github.io/shapr/news/index.html) for a complete list.\n\n### Coming from shapr \u003c 1.0.0?\n`shapr` version \u003e= 1.0.0 comes with a number of breaking changes. \nMost notably, we moved from using two function (`shapr()` and `explain()`) to \na single function (`explain()`). \nIn addition, custom models are now explained by passing the prediction function directly to `explain()`, \nquite a few input arguments got new names, and a few functions for edge cases was removed to simplify the code base. \n\nClick [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).\n\n### Python wrapper\n\nWe provide a Python wrapper (`shaprpy`) which allows explaining Python models with the methodology \nimplemented in `shapr`, directly from Python. \nThe wrapper calls `R` internally, and therefore requires an installation of `R`. \nSee [here](https://norskregnesentral.github.io/shapr/shaprpy.html) for installation instructions and examples.\n\n\n## The package\n\nThe `shapr` R package implements an enhanced version of the Kernel SHAP method, for approximating Shapley values, \nwith a strong focus on conditional Shapley values. \nThe core idea is to remain completely model-agnostic while offering a variety of methods for estimating contribution \nfunctions, enabling accurate computation of conditional Shapley values across different feature types, dependencies, \nand distributions. \nThe package also includes evaluation metrics to compare various approaches. \nWith features like parallelized computations, convergence detection, progress updates, and extensive plotting options, \nshapr is as a highly efficient and user-friendly tool, delivering precise estimates of conditional Shapley values, \nwhich are critical for understanding how features truly contribute to predictions.\n\nA basic example is provided below. \nOtherwise we refer to the [pkgdown website](https://norskregnesentral.github.io/shapr/) and the different vignettes there for details and further examples.\n\n\n## Installation\n\n`shapr` is available on [CRAN](https://cran.r-project.org/package=shapr) and can be installed in R as:\n\n```{r, eval = FALSE}\ninstall.packages(\"shapr\")\n```\n\nTo install the development version of `shapr`, available on GitHub, use\n\n```{r, eval = FALSE}\nremotes::install_github(\"NorskRegnesentral/shapr\")\n```\n\nTo also install all dependencies, use\n\n```{r, eval = FALSE}\nremotes::install_github(\"NorskRegnesentral/shapr\", dependencies = TRUE)\n```\n\n\n## Example\n`shapr` supports computation of Shapley values with any predictive model which takes a set of numeric features and produces a numeric outcome. \n\nThe following example shows how a simple `xgboost` model is trained using the *airquality* dataset, and how `shapr` explains the individual predictions. \n\nWe first enable parallel computation and progress updates with the following code chunk. \nThese are optional, but recommended for improved performance and user friendliness, \nparticularly for problems with many features.\n\n```{r init_no_eval,eval = FALSE}\n# Enable parallel computation\n# Requires the future and future_lapply packages\nfuture::plan(\"multisession\", workers = 2) # Increase the number of workers for increased performance with many features\n\n# Enable progress updates of the v(S)-computations\n# Requires the progressr package\nprogressr::handlers(global = TRUE)\nprogressr::handlers(\"cli\") # Using the cli package as backend (recommended for the estimates of the remaining time)\n```\n\nHere comes the actual example\n```{r basic_example, warning = FALSE}\nlibrary(xgboost)\nlibrary(shapr)\n\ndata(\"airquality\")\ndata \u003c- data.table::as.data.table(airquality)\ndata \u003c- data[complete.cases(data), ]\n\nx_var \u003c- c(\"Solar.R\", \"Wind\", \"Temp\", \"Month\")\ny_var \u003c- \"Ozone\"\n\nind_x_explain \u003c- 1:6\nx_train \u003c- data[-ind_x_explain, ..x_var]\ny_train \u003c- data[-ind_x_explain, get(y_var)]\nx_explain \u003c- data[ind_x_explain, ..x_var]\n\n# Looking at the dependence between the features\ncor(x_train)\n\n# Fitting a basic xgboost model to the training data\nmodel \u003c- xgboost(\n  data = as.matrix(x_train),\n  label = y_train,\n  nround = 20,\n  verbose = FALSE\n)\n\n# Specifying the phi_0, i.e. the expected prediction without any features\np0 \u003c- mean(y_train)\n\n# Computing the Shapley values with kernelSHAP accounting for feature dependence using\n# the empirical (conditional) distribution approach with bandwidth parameter sigma = 0.1 (default)\nexplanation \u003c- explain(\n  model = model,\n  x_explain = x_explain,\n  x_train = x_train,\n  approach = \"empirical\",\n  phi0 = p0,\n  seed = 1\n)\n\n# Printing the Shapley values for the data to explain.\n# For more information about the interpretation of the values in the table, see ?shapr::explain.\nprint(explanation$shapley_values_est)\n\n# Finally we plot the resulting explanations\nplot(explanation)\n```\n\nSee @jullum2025shapr (preprint available [here](https://arxiv.org/abs/2504.01842)) for a software paper with an overview of the methodology and capabilities of the \npackage (as of v1.0.4).\nSee the [general usage vignette](https://norskregnesentral.github.io/shapr/articles/general_usage.html) for further \nbasic usage examples and brief introductions to the methodology. \nFor more thorough information about the underlying methodology, see methodological papers\n@aas2019explaining, @redelmeier2020explaining, @jullum2021efficient, @olsen2022using, @olsen2024comparative.\nSee also @sellereite2019shapr for a very brief paper about a previous version (v0.1.1) of the package \n(with a different structure, syntax and significantly less functionality).\n\n## Contribution\n\nAll feedback and suggestions are very welcome. Details on how to contribute can be found \n[here](https://norskregnesentral.github.io/shapr/CONTRIBUTING.html). If you have any questions or comments, feel\nfree to open an issue [here](https://github.com/NorskRegnesentral/shapr/issues). \n\nPlease note that the 'shapr' project is released with a\n[Contributor Code of Conduct](https://norskregnesentral.github.io/shapr/CODE_OF_CONDUCT.html).\nBy contributing to this project, you agree to abide by its terms. \n\n## References\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNorskRegnesentral%2Fshapr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNorskRegnesentral%2Fshapr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNorskRegnesentral%2Fshapr/lists"}