shap-svg 0.1.0 → 0.2.0

package/README.md

@@ -26,23 +26,107 @@ affiliated with the SHAP authors.
 
 | Component | SHAP counterpart | Shows |
 | --- | --- | --- |
-| `ShapBar` | `shap.plots.bar` | mean(\|SHAP value\|) per feature across samples |
-| `ShapBeeswarm` | `shap.plots.beeswarm` | one dot per sample per feature, coloured by feature value |
-| `ShapHeatmap` | `shap.plots.heatmap` | samples × features coloured by SHAP value, with the f(x) line above |
-| `ShapWaterfall` | `shap.plots.waterfall` | how one sample's prediction is built from E[f(X)] to f(x) |
+| `Plots.bar` | `shap.plots.bar` | mean(\|SHAP value\|) per feature across samples |
+| `Plots.beeswarm` | `shap.plots.beeswarm` | one dot per sample per feature, coloured by feature value |
+| `Plots.heatmap` | `shap.plots.heatmap` | samples × features coloured by SHAP value, with the f(x) line above |
+| `Plots.waterfall` | `shap.plots.waterfall` | how one sample's prediction is built from E[f(X)] to f(x) |
 
 Every chart is a pure component: all state that changes what is drawn arrives through props, so the
 host application owns its own controls. The only internal state is hover highlighting.
 
 ## Usage
 
-```tsx
-import { ShapBeeswarm, ShapWaterfall } from "shap-svg/react";
+`shap-svg` draws SHAP values; it does not compute them. The values come from
+[`shap`](https://github.com/shap/shap) in Python, travel through your server as JSON, and are handed to
+a component in the browser:
+
+```text
+Python: shap computes the values  →  server returns them as JSON  →  browser fetches  →  <Plots.waterfall explanation={…} />
+```
+
+### 1. Compute SHAP values in Python and serialise them
+
+```python
+import numpy as np
+import shap
+
+explainer = shap.TreeExplainer(model)  # any shap explainer works
+
+
+def to_payload(explanation: shap.Explanation, sample_ids=None) -> dict:
+    """Serialise a shap.Explanation into the JSON shap-svg reads."""
+    payload = {
+        "contract_version": 1,
+        "values": np.asarray(explanation.values, dtype=float).tolist(),
+        "base_values": np.asarray(explanation.base_values, dtype=float).tolist(),
+        "data": np.asarray(explanation.data, dtype=float).tolist(),
+        "feature_names": [str(name) for name in explanation.feature_names],
+    }
+    if sample_ids is not None:
+        payload["sample_ids"] = [str(sample_id) for sample_id in sample_ids]
+    return payload
+```
+
+- **Pass the explanation as it comes.** A scikit-learn binary classifier gives `values` shaped
+  `(samples, features, 2)` and `base_values` shaped `(samples, 2)`; `shap-svg` reads class 1 by default
+  (`classIndex` on every component). There is no need to pick a class in Python.
+- **Send only finite numbers.** Fill or drop missing feature values first. Flask's `jsonify` writes
+  `NaN` unquoted, which is not valid JSON, and `parseExplanation` rejects it; serialising with
+  `json.dumps(payload, allow_nan=False)` makes the mistake fail on the server instead.
+- **`sample_ids` are optional** but give each Sample a stable key: the heatmap hands it back from
+  `onSampleClick`. Add `sample_labels` for the names a person should read.
+
+### 2. Return the payload from your server
 
-<ShapBeeswarm explanation={explanation} maxDisplay={15} groupByGenus rowSort="name" />
-<ShapWaterfall explanation={explanation} sampleIndex={0} decimals="percent" />
+```python
+from flask import Flask, jsonify
+
+app = Flask(__name__)
+
+
+@app.post("/api/explain")
+def explain():
+    X = rows_to_explain()  # a pandas DataFrame, e.g. built from the request body
+    explanation = explainer(X)
+    return jsonify(to_payload(explanation, sample_ids=X.index))
 ```
 
+Any framework works — the contract is only the JSON above. Serve it gzipped if you can: the payload is
+mostly repeated digits and compresses well.
+
+### 3. Fetch it in the browser and hand it to a component
+
+```tsx
+import { useEffect, useState } from "react";
+import type { Explanation } from "shap-svg";
+import { Plots } from "shap-svg/react";
+
+export function ExplanationView() {
+  const [explanation, setExplanation] = useState<Explanation>();
+
+  useEffect(() => {
+    fetch("/api/explain", { method: "POST" })
+      .then((response) => response.json())
+      .then(setExplanation);
+  }, []);
+
+  if (!explanation) return <p>Loading…</p>;
+
+  return (
+    <>
+      <Plots.beeswarm explanation={explanation} maxDisplay={15} groupByGenus rowSort="name" />
+      <Plots.waterfall explanation={explanation} sampleIndex={0} decimals="percent" />
+    </>
+  );
+}
+```
+
+The charts are named the way `shap` names them in Python: `shap.plots.bar` becomes `<Plots.bar />`.
+`Plots` brings all four charts into your bundle, even if a page draws one — about 30 KB minified.
+
+From here every control — how many features, grouping, sorting, precision — is a prop. Changing one
+redraws from the payload already in memory; nothing goes back to the server.
+
 The framework-free core — parsing, ordering, collapsing, layout and colour — has no React import and
 can drive any renderer:
 
@@ -94,11 +178,11 @@ Per chart:
 
 | Chart | Prop | Default | |
 | --- | --- | --- | --- |
-| `ShapBeeswarm`, `ShapHeatmap` | `rowSort` | `"importance"` | `"importance"`, `"name"` or `"featureValue"`; reorders the rows shown, never which rows are shown |
-| `ShapBeeswarm` | `seed`, `dotRadius` | `0`, `3` | jitter is seeded, so a chart is identical on every render |
-| `ShapHeatmap` | `onSampleClick` | — | called with the column's `sample_ids` entry |
-| `ShapWaterfall` | `sampleIndex` | `0` | which sample to explain |
-| `ShapWaterfall` | `decimals` | `2` | `2`, `3`, `4` or `"percent"`; display only |
+| `Plots.beeswarm`, `Plots.heatmap` | `rowSort` | `"importance"` | `"importance"`, `"name"` or `"featureValue"`; reorders the rows shown, never which rows are shown |
+| `Plots.beeswarm` | `seed`, `dotRadius` | `0`, `3` | jitter is seeded, so a chart is identical on every render |
+| `Plots.heatmap` | `onSampleClick` | — | called with the column's `sample_ids` entry |
+| `Plots.waterfall` | `sampleIndex` | `0` | which sample to explain |
+| `Plots.waterfall` | `decimals` | `2` | `2`, `3`, `4` or `"percent"`; display only |
 
 ## Faithful to SHAP where it matters