WebSHAP

Explaining any machine learning models directly in your browser!

🔎 Example Web application applying WebSHAP to explain loan approval decisions

What is WebSHAP?

WebSHAP is a TypeScript 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.✨

Getting Started

Installation

WebSHAP supports both browser and Node.js environments. To install WebSHAP, you can use npm:

npm install webshap

Explain Machine Learning Models

WebSHAP 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 or this nice tutorial.

To run WebSHAP on your model, you need to prepare the following three arguments.

Name	Description	Type	Details
ML Model	A function that transforms input data into predicted probabilities	(x: number[][]) => Promise<number[]>	This function wraps your ML model inference code. WebSHAP is model-agnostic, so any model can be used (e.g. random forest, CNNs, transformers).
Data Point	The input data for a prediction.	number[][]	WebSHAP generates local explanations by computing the feature importance for individual predictions.
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.

Then, you can generate explanations with WebSHAP through two functions:

// Import the class KernelSHAP from the webshap module
import { KernelSHAP } from 'webshap';

// Create an explainer object by feeding it with background data
const explainer = new KernelSHAP(
  (x: number[][]) => myModel(x),  // ML Model function wrapper
  backgroundData,                 // Background data
  0.2022                          // Random seed
);

// Explain one prediction
let shapValues = await explainer.explainOneInstance(x);

// By default, WebSHAP automatically chooses the number of feature
// permutations. You can also pass it as an argument here.
const nSamples = 512;
shapValues = await explainer.explainOneInstance(x, nSamples);

// Finally, `shapValues` contains the importance score for each feature in `x`
console.log(shapValue);

Application Example

🔎 WebSHAP explaining an XGBoost-based loan approval model

We 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: https://poloclub.github.io/webshap.

This example showcases a bank using an XGBoost classifier on the LendingClub dataset 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.

This demo runs entirely on the client side, making it accessible from desktops, tablets, and phones. The model inference is powered by ONNX Runtime. The UI is implemented using 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.

Developing WebSHAP

Clone or download this repository:

git clone git@github.com:poloclub/webshap.git

Install the dependencies:

npm install

Use Vitest for unit testing:

npm run test

Developing the Loan Explainer Example

Clone or download this repository:

git clone git@github.com:poloclub/webshap.git

Navigate to the example folder:

cd ./examples/demo

Install the dependencies:

npm install

Then run Loan Explainer:

npm run dev

Navigate to localhost:3000. You should see Loan Explainer running in your browser :)

Credits

WebSHAP is created by Jay Wang and Polo Chau.

License

The software is available under the MIT License.

Contact

If you have any questions, feel free to open an issue or contact Jay Wang.