{"id":28100746,"url":"https://github.com/poloclub/webshap","last_synced_at":"2025-08-20T14:13:02.194Z","repository":{"id":93030571,"uuid":"592840354","full_name":"poloclub/webshap","owner":"poloclub","description":"JavaScript library to explain any machine learning models anywhere!","archived":false,"fork":false,"pushed_at":"2023-03-29T19:23:32.000Z","size":37245,"stargazers_count":65,"open_issues_count":1,"forks_count":20,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-09T19:03:10.385Z","etag":null,"topics":["interpretability","machine-learning","tensorflowjs","transformer","visualization"],"latest_commit_sha":null,"homepage":"https://poloclub.github.io/webshap","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poloclub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2023-01-24T16:45:48.000Z","updated_at":"2025-08-04T13:42:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"f17ad668-9b0c-4880-8f4e-1b629bfc1611","html_url":"https://github.com/poloclub/webshap","commit_stats":null,"previous_names":["xiaohk/webshap"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/poloclub/webshap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fwebshap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fwebshap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fwebshap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fwebshap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poloclub","download_url":"https://codeload.github.com/poloclub/webshap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fwebshap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271330310,"owners_count":24740818,"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","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["interpretability","machine-learning","tensorflowjs","transformer","visualization"],"created_at":"2025-05-13T18:38:49.664Z","updated_at":"2025-08-20T14:13:02.180Z","avatar_url":"https://github.com/poloclub.png","language":"TypeScript","readme":"# WebSHAP \u003ca href=\"https://poloclub.github.io/webshap/\"\u003e\u003cimg align=\"right\" src=\"https://raw.githubusercontent.com/poloclub/webshap/main/examples/demo/src/imgs/icon-webshap.svg\" height=\"38\"\u003e\u003c/img\u003e\u003c/a\u003e\n\n[![build](https://github.com/xiaohk/webshap/actions/workflows/build.yml/badge.svg)](https://github.com/xiaohk/webshap/actions/workflows/build.yml)\n[![npm](https://img.shields.io/npm/v/webshap?color=orange)](https://www.npmjs.com/package/webshap)\n[![license](https://img.shields.io/badge/License-MIT-blue)](https://github.com/poloclub/webshap/blob/main/LICENSE)\n[![arxiv badge](https://img.shields.io/badge/arXiv-2209.09227-red)](https://arxiv.org/abs/2303.09545)\n[![DOI:10.1145/3543873.3587362](https://img.shields.io/badge/DOI-10.1145/3543873.3587362-blue)](https://doi.org/10.1145/3543873.3587362)\n\nJavaScript library that explains any machine learning models in your browser!\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\"\u003e\u003ca href=\"https://poloclub.github.io/webshap\"\u003e\u003cimg src='https://user-images.githubusercontent.com/15007159/225991959-c2b10d8b-be24-4f5c-a6f4-2b9f5876095c.gif' width=\"100%\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ctable\u003e\n        \u003ctr\u003e\n          \u003ctd colspan=\"3\" align=\"center\"\u003eLive Explainer Demos\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd\u003e\u003ca href=\"https://poloclub.github.io/webshap/?model=tabulark\"\u003e💰 Loan Prediction\u003c/a\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ca href=\"https://poloclub.github.io/webshap/?model=image\"\u003e🌠 Image Classifier\u003c/a\u003e\u003c/td\u003e\n          \u003ctd\u003e\u003ca href=\"https://poloclub.github.io/webshap/?model=text\"\u003e🔤 Toxicity Detector\u003c/a\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n      \u003c/table\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ctable\u003e\n        \u003ctr\u003e\n          \u003ctd colspan=\"1\" align=\"center\"\u003eResearch Paper\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\u003c/tr\u003e\n        \u003ctr\u003e\n          \u003ctd\u003e\u003ca href=\"https://arxiv.org/abs/2303.09545\"\u003e📖 WebSHAP(TheWebConf'23)\u003c/a\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n      \u003c/table\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n## What is WebSHAP?\n\nWebSHAP is a JavaScript library that adapts Kernel SHAP for the Web environments. You can use it to explain any machine learning models available on the Web directly in your browser. Given a model's prediction on a data point, WebSHAP can compute the importance score for each input feature. WebSHAP leverages modern Web technologies such as WebGL to accelerate computations. With a moderate model size and number of input features, WebSHAP can generate explanations in real time.✨\n\n## Getting Started\n\n### Installation\n\nWebSHAP supports both browser and Node.js environments. To install WebSHAP, you can use `npm`:\n\n```bash\nnpm install webshap\n```\n\n### Explain Machine Learning Models\n\nWebSHAP uses the Kernel SHAP algorithm to interpret machine learning (ML) models. This algorithm uses a game theoretic approach to approximate the importance of each input feature. You can learn more about Kernel SHAP from [the original paper](https://arxiv.org/abs/1705.07874) or [this nice tutorial](https://christophm.github.io/interpretable-ml-book/shap.html).\n\nTo run WebSHAP on your model, you need to prepare the following three arguments.\n\n|Name|Description|Type|Details|\n|:---|:---|:---|:---|\n|ML Model|A function that transforms input data into predicted probabilities|`(x: number[][]) =\u003e Promise\u003cnumber[]\u003e`|This function wraps your ML model inference code. WebSHAP is model-agnostic, so any model can be used (e.g. random forest, CNNs, transformers).|\n|Data Point|The input data for a prediction.|`number[][]`|WebSHAP generates local explanations by computing the feature importance for individual predictions.|\n|Background Data|A 2D array that represents feature \"missingness\" |`number[][]`|WebSHAP approximates the contribution of a feature by comparing it to its missing value (also known as the base value). Using all zeros is the simplest option, but using the median or a subset of your data can improve accuracy.|\n\nThen, you can generate explanations with WebSHAP through two functions:\n\n```typescript\n// Import the class KernelSHAP from the webshap module\nimport { KernelSHAP } from 'webshap';\n\n// Create an explainer object by feeding it with background data\nconst explainer = new KernelSHAP(\n  (x: number[][]) =\u003e myModel(x),  // ML Model function wrapper\n  backgroundData,                 // Background data\n  0.2022                          // Random seed\n);\n\n// Explain one prediction\nlet shapValues = await explainer.explainOneInstance(x);\n\n// By default, WebSHAP automatically chooses the number of feature\n// permutations. You can also pass it as an argument here.\nconst nSamples = 512;\nshapValues = await explainer.explainOneInstance(x, nSamples);\n\n// Finally, `shapValues` contains the importance score for each feature in `x`\nconsole.log(shapValue);\n```\n\nSee the [WebSHAP Documentation](http://poloclub.github.io/webshap/doc/) for more details.\n\n## Application Example\n\n### Demo 1: Explaining XGBoost\n\n|\u003cimg src='https://user-images.githubusercontent.com/15007159/226003794-94b3a0d9-b132-4ab2-80fc-33aecbd66337.jpg'\u003e|\n|:---:|\n|[🔎 WebSHAP explaining an XGBoost-based loan approval model](https://poloclub.github.io/webshap/?model=tabular) 💰|\n\nWe present `Loan Explainer` as an example of applying WebSHAP to explain a financial ML model in browsers. For a live demo of Loan Explainer, visit [this webpage](https://poloclub.github.io/webshap/?model=text).\n\nThis example showcases a bank using an [XGBoost classifier](https://github.com/dmlc/xgboost) on the [LendingClub dataset](https://www.kaggle.com/datasets/wordsforthewise/lending-club) to predict if a loan applicant will be able to repay the loan on time. With this model, the bank can make automatic loan approval decisions. It's important to understand how these high-stakes decisions are being made, and that's where WebSHAP comes in. It provides *private*, *ubiquitous*, and *interactive* ML explanations.\n\nThis demo runs entirely on the client side, making it accessible from desktops, tablets, and phones. The model inference is powered by [ONNX Runtime](https://github.com/microsoft/onnxruntime). The UI is implemented using [Svelte](https://github.com/sveltejs/svelte). With Loan Explainer, users can experiment with different feature inputs and instantly see the model's predictions, along with clear explanations for those predictions.\n\n### Demo 2: Explaining Convolutional Neural Networks\n\n|\u003cimg src='https://user-images.githubusercontent.com/15007159/226048036-c92043ee-df9b-42a6-9607-a15dd3da5470.jpg'\u003e|\n|:---:|\n|[🔎 WebSHAP explaining a convolutional neural network for image classification](https://poloclub.github.io/webshap/?model=image) 🌠|\n\nWe apply WebSHAP to explain convolutional neural networks (CNNs) in browsers. The live demo of this explainer is available on [this webpage](https://poloclub.github.io/webshap/?model=image).\n\nIn this example, we first train a TinyVGG model to classify images into four categories: 🐞`Ladybug`, ☕️`Espresso`, 🍊`Orange`, and 🚙`Sports Car`. TinyVGG is a type of convolutional neural network. For more details about the model architecture, check out [CNN Explainer](https://poloclub.github.io/cnn-explainer). TinyVGG is implemented using [TensorFlow.js](https://www.tensorflow.org/js).\n\nTo explain the predictions of TinyVGG, we first apply image segmentation ([SLIC](https://www.iro.umontreal.ca/~mignotte/IFT6150/Articles/SLIC_Superpixels.pdf)) to divide the input image into multiple segments. Then, we compute SHAP scores on each segment for each class. The background data here are white pixels. We compute SHAP values for segments instead of raw pixels for computation efficiency. For example, in the figure above, there are only 16 input features (16 segments) for WebSHAP, but there would have been $64 \\times 64 \\times 3 = 12288$ input features if we use raw pixels. Finally, we visualize the SHAP scores of each segment as an overlay with a diverging color scale on top of the original input image.\n\nEverything in this example (TinyVGG, image segmenter, WebSHAP) runs in the user's browser. In addition, WebSHAP enables *interactive* explanation: users can click a button to use a random input image or upload their own images. Both model inference and SHAP computation are real-time.\n\n\n### Demo 3: Explaining Transformer-based Text Classifiers\n\n|\u003cimg src='https://user-images.githubusercontent.com/15007159/226048056-1e5f0d2d-f7f1-4f8f-9a48-7b2b2f4cad72.jpg'\u003e|\n|:---:|\n|[🔎 WebSHAP explaining a transformer model for text classification](https://poloclub.github.io/webshap/?model=text) 🔤|\n\nWe use WebSHAP to explain the predictions of a Transformer text classifier in browsers. The live demo for this explainer is accessible on [this webpage](https://poloclub.github.io/webshap/?model=text).\n\nWe train an [XtremeDistil model](https://github.com/microsoft/xtreme-distil-transformers) to predict if an input text is toxic. The XtremeDistil model is a distilled version of pre-trained transformer-based language model BERT. We train this model on the [Toxic Comments dataset](https://www.kaggle.com/competitions/jigsaw-toxic-comment-classification-challenge/data). Then, we quantize and export the trained model to use `int8` weights with [ONNX](https://github.com/onnx/onnxmltools). We use [TensorFlow.js](https://github.com/tensorflow/tfjs-models/blob/master/qna/src/bert_tokenizer.ts) for tokenization and [ONNX Runtime](https://onnxruntime.ai) for model inference.\n\nTo explain the model's predictions, we compute SHAP scores for each input token. For background data, we use BERT's attention mechanism to mask tokens. For example, we represent a \"missing\" token by setting its [attention map](https://huggingface.co/docs/transformers/glossary#attention-mask) to `0`, which tells the model to ignore this token. Finally, we visualize the SHAP scores as the token's background color with a diverging color scale.\n\nAll components in this example (XtremeDistil, tokenizer, WebSHAP) run on the client side. WebSHAP provides *private*, *ubiquitous*, and *interactive* explanations. Users can edit the input text and see new predictions and explanations. The model inference is real-time, and SHAP computation takes about 5 seconds for 50 tokens.\n\n\n## Developing WebSHAP\n\nClone or download this repository:\n\n```bash\ngit clone git@github.com:poloclub/webshap.git\n```\n\nInstall the dependencies:\n\n```bash\nnpm install\n```\n\nUse Vitest for unit testing:\n\n```\nnpm run test\n```\n\n## Developing the Application Examples\n\nClone or download this repository:\n\n```bash\ngit clone git@github.com:poloclub/webshap.git\n```\n\nNavigate to the example folder:\n\n```bash\ncd ./examples/demo\n```\n\nInstall the dependencies:\n\n```bash\nnpm install\n```\n\nThen run Loan Explainer:\n\n```\nnpm run dev\n```\n\nNavigate to localhost:3000. You should see three Explainers running in your browser :)\n\n## Credits\n\nWebSHAP is created by \u003ca href='https://zijie.wang/' target='_blank'\u003eJay Wang\u003c/a\u003e and \u003ca href='' target='_blank'\u003ePolo Chau\u003c/a\u003e.\n\n## Citation\n\nTo learn more about WebSHAP, please read our [research paper](https://arxiv.org/abs/2303.09545) (published at [TheWebConf'23](https://www2023.thewebconf.org)). If you find WebSHAP useful for your research, please consider citing our paper. And if you're building any exciting projects with WebSHAP, we'd love to hear about them!\n\n```bibTeX\n@inproceedings{wangWebSHAPExplainingAny2023,\n  title = {{{WebSHAP}}: {{Towards Explaining Any Machine Learning Models Anywhere}}},\n  shorttitle = {{{WebSHAP}}},\n  booktitle = {Companion {{Proceedings}} of the {{Web Conference}} 2023},\n  author = {Wang, Zijie J. and Chau, Duen Horng},\n  year = {2023},\n  langid = {english}\n}\n```\n\n## License\n\nThe software is available under the [MIT License](https://github.com/poloclub/webshap/blob/main/LICENSE).\n\n## Contact\n\nIf you have any questions, feel free to [open an issue](https://github.com/poloclub/webshap/issues/new) or contact [Jay Wang](https://zijie.wang).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoloclub%2Fwebshap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoloclub%2Fwebshap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoloclub%2Fwebshap/lists"}