shap-svg 0.1.0 → 0.2.1

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,12 @@ 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`, `Plots.heatmap` | `colorBar` | `true` | SHAP's colour bar right of the plot — Low to High feature value on the beeswarm, the SHAP value range on the heatmap. The plot narrows when the right margin cannot hold it |
+| `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
 

package/dist/{chunk-OXFKP5I3.js → chunk-ZWO4CN22.js}

@@ -1141,12 +1141,118 @@ function sampleColormap(name, t) {
   return `#${hexByte(red)}${hexByte(green)}${hexByte(blue)}`;
 }
 
+// src/core/colorBar.ts
+var ASPECT = 80;
+var TICK_PAD = 3.5;
+var TICK_LABEL_PT3 = 11;
+var LABEL_PT = 12;
+var LABEL_THICKNESS_EM = 1.08;
+var LABEL_BASELINE_EM = 0.84;
+var CHAR_EM = 0.6;
+var STEPS = 64;
+function textWidth(text, fontSize) {
+  return text.length * fontSize * CHAR_EM;
+}
+function tickColumnWidth(spec) {
+  return Math.max(...spec.tickLabels.map((label) => textWidth(label, TICK_LABEL_PT3)));
+}
+function colorBarExtent(height, spec) {
+  return height / ASPECT + TICK_PAD + Math.max(0, tickColumnWidth(spec) + spec.labelPad) + LABEL_PT * LABEL_THICKNESS_EM;
+}
+function fitColorBar(opts) {
+  const { plotWidth, available, gapRatio, minGap, extent } = opts;
+  const gapFor = (width) => Math.max(gapRatio * width, minGap);
+  if (gapFor(plotWidth) + extent <= available) {
+    return { plotWidth, gap: gapFor(plotWidth) };
+  }
+  const byRatio = (available + plotWidth - extent) / (1 + gapRatio);
+  const fitted = Math.max(
+    0,
+    gapRatio * byRatio >= minGap ? byRatio : plotWidth - (minGap + extent - available)
+  );
+  return { plotWidth: fitted, gap: gapFor(fitted) };
+}
+function colorBarLayout(spec, position) {
+  const { x, y1, y2 } = position;
+  const width = (y2 - y1) / ASPECT;
+  const step = (y2 - y1) / STEPS;
+  const steps = Array.from({ length: STEPS }, (_, index) => ({
+    y: y2 - (index + 1) * step,
+    // Every band but the lowest reaches half a pixel into the one below, so
+    // anti-aliasing cannot open a hairline seam between them.
+    height: index === 0 ? step : step + 0.5,
+    color: sampleColormap(spec.colormap, index / (STEPS - 1))
+  }));
+  const tickX = x + width + TICK_PAD;
+  const labelLeft = tickX + tickColumnWidth(spec) + spec.labelPad;
+  return {
+    x,
+    y1,
+    y2,
+    width,
+    steps,
+    tickX,
+    tickFontSize: TICK_LABEL_PT3,
+    ticks: [
+      { y: y2, label: spec.tickLabels[0] },
+      { y: y1, label: spec.tickLabels[1] }
+    ],
+    ...spec.offsetText ? { offsetText: { x: tickX, y: y1 - TICK_LABEL_PT3, text: spec.offsetText } } : {},
+    label: {
+      x: labelLeft + LABEL_PT * LABEL_BASELINE_EM,
+      y: (y1 + y2) / 2,
+      text: spec.label,
+      fontSize: LABEL_PT
+    },
+    right: Math.max(
+      tickX + tickColumnWidth(spec),
+      labelLeft + LABEL_PT * LABEL_THICKNESS_EM
+    )
+  };
+}
+var MINUS3 = "\u2212";
+var POWER_LIMITS = [-5, 6];
+function roundTo(value, decimals) {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+function scalarFormatterLabels(locs) {
+  const largest = Math.max(0, ...locs.map(Math.abs));
+  const magnitude = largest === 0 ? 0 : Math.floor(Math.log10(largest));
+  const order = magnitude <= POWER_LIMITS[0] || magnitude >= POWER_LIMITS[1] ? magnitude : 0;
+  const scaled = locs.map((value) => value / 10 ** order);
+  let range = Math.max(...scaled) - Math.min(...scaled);
+  if (range === 0) range = Math.max(...scaled.map(Math.abs));
+  if (range === 0) range = 1;
+  const rangeMagnitude = Math.floor(Math.log10(range));
+  const threshold = 1e-3 * 10 ** rangeMagnitude;
+  let decimals = Math.max(0, 3 - rangeMagnitude);
+  while (decimals >= 0) {
+    const error = Math.max(...scaled.map((value) => Math.abs(value - roundTo(value, decimals))));
+    if (error < threshold) decimals -= 1;
+    else break;
+  }
+  decimals += 1;
+  const labels = scaled.map((value) => {
+    const text = value.toFixed(decimals);
+    return Number(text) === 0 ? text.replace("-", "") : text.replace("-", MINUS3);
+  });
+  return order === 0 ? { labels } : { labels, offsetText: `1e${String(order).replace("-", MINUS3)}` };
+}
+
 // src/core/beeswarmLayout.ts
 var BEESWARM_MISSING_COLOR = "#777777";
 var BEESWARM_ROW_HEIGHT = 0.4;
 var NBINS = 100;
-var AXIS_HEIGHT3 = 74;
-var TICK_LABEL_PT3 = 11;
+var AXIS_HEIGHT3 = 52;
+var COLOR_BAR = {
+  colormap: "red_blue",
+  tickLabels: ["Low", "High"],
+  label: "Feature value",
+  labelPad: 0
+};
+var COLOR_BAR_GAP_RATIO = 0.05 / 0.8;
+var TICK_LABEL_PT4 = 11;
 var TITLE_PT2 = 13;
 var X_MARGIN2 = 0.05;
 function percentile(values, percent) {
@@ -1278,7 +1384,7 @@ function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSo
   return { rows, collapsedCount: display.collapsedCount };
 }
 function beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
-  const { ticks, step } = niceTicks(min, max, tickSpace(plotWidth, TICK_LABEL_PT3));
+  const { ticks, step } = niceTicks(min, max, tickSpace(plotWidth, TICK_LABEL_PT4));
   return {
     xTicks: ticks.map((value) => ({ value, x: toX(value), label: tickLabel(value, step) })),
     xSpine: { x1: marginLeft, x2: marginLeft + plotWidth, y: plotBottom },
@@ -1293,7 +1399,15 @@ function beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
 }
 function beeswarmLayout(valueRows, opts) {
   const { width, rowHeight, marginLeft, marginRight, marginTop, dotRadius } = opts;
-  const plotWidth = width - marginLeft - marginRight;
+  const plotBottom = marginTop + valueRows.rows.length * rowHeight;
+  const fit = opts.colorBar ? fitColorBar({
+    plotWidth: width - marginLeft - marginRight,
+    available: marginRight,
+    gapRatio: COLOR_BAR_GAP_RATIO,
+    minGap: 0,
+    extent: colorBarExtent(plotBottom - marginTop, COLOR_BAR)
+  }) : null;
+  const plotWidth = fit ? fit.plotWidth : width - marginLeft - marginRight;
   const values = valueRows.rows.flatMap((row) => row.points.map((point) => point.x));
   const dataMin = Math.min(0, ...values);
   const dataMax = Math.max(0, ...values);
@@ -1318,7 +1432,6 @@ function beeswarmLayout(valueRows, opts) {
       }))
     };
   });
-  const plotBottom = marginTop + valueRows.rows.length * rowHeight;
   return {
     rows,
     xDomain: [min, max],
@@ -1326,6 +1439,11 @@ function beeswarmLayout(valueRows, opts) {
     ...beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom),
     plotWidth,
     plotBottom,
+    colorBar: fit ? colorBarLayout(COLOR_BAR, {
+      x: marginLeft + plotWidth + fit.gap,
+      y1: marginTop,
+      y2: plotBottom
+    }) : null,
     height: plotBottom + AXIS_HEIGHT3
   };
 }
@@ -1338,7 +1456,9 @@ var SIDE_BAR_GAP = 10;
 var SIDE_BAR_RIGHT_INSET = 40;
 var SIDE_BAR_HEIGHT_RATIO = 0.6;
 var AXIS_HEIGHT4 = 52;
-var TICK_LABEL_PT4 = 10;
+var TICK_LABEL_PT5 = 10;
+var COLOR_BAR_GAP_RATIO2 = 0.1 / 0.89;
+var COLOR_BAR_CLEARANCE = 8;
 var Y_TICK_LENGTH = 5;
 function percentile2(values, fraction) {
   if (values.length === 0) return 0;
@@ -1429,7 +1549,7 @@ function heatmapXAxis(sampleCount, marginLeft, cellWidth, plotWidth, plotBottom)
   const { ticks, step } = niceTicks(
     -0.5,
     sampleCount - 0.5,
-    tickSpace(plotWidth, TICK_LABEL_PT4),
+    tickSpace(plotWidth, TICK_LABEL_PT5),
     { integer: true }
   );
   return {
@@ -1443,17 +1563,33 @@ function heatmapXAxis(sampleCount, marginLeft, cellWidth, plotWidth, plotBottom)
       text: "Instances",
       x: marginLeft + plotWidth / 2,
       y: plotBottom + AXIS_TITLE_DY,
-      fontSize: TICK_LABEL_PT4
+      fontSize: TICK_LABEL_PT5
     }
   };
 }
 function heatmapLayout(valueRows, opts) {
   const { width, rowHeight, marginLeft, marginRight, marginTop } = opts;
-  const plotWidth = width - marginLeft - marginRight;
-  const cellWidth = valueRows.columns.length === 0 ? 0 : plotWidth / valueRows.columns.length;
-  const gridRight = marginLeft + plotWidth;
   const plotBottom = marginTop + valueRows.rows.length * rowHeight;
   const sideBarWidth = Math.max(0, marginRight - SIDE_BAR_RIGHT_INSET - SIDE_BAR_GAP);
+  const ticks = scalarFormatterLabels([valueRows.vmin, valueRows.vmax]);
+  const colorBarSpec = {
+    colormap: "red_white_blue",
+    tickLabels: [ticks.labels[0], ticks.labels[1]],
+    ...ticks.offsetText ? { offsetText: ticks.offsetText } : {},
+    label: "SHAP value (impact on model output)",
+    labelPad: -10
+  };
+  const colorBarTop = FX_TOP;
+  const fit = opts.colorBar ? fitColorBar({
+    plotWidth: width - marginLeft - marginRight,
+    available: marginRight,
+    gapRatio: COLOR_BAR_GAP_RATIO2,
+    minGap: SIDE_BAR_GAP + sideBarWidth + COLOR_BAR_CLEARANCE,
+    extent: colorBarExtent(plotBottom - colorBarTop, colorBarSpec)
+  }) : null;
+  const plotWidth = fit ? fit.plotWidth : width - marginLeft - marginRight;
+  const cellWidth = valueRows.columns.length === 0 ? 0 : plotWidth / valueRows.columns.length;
+  const gridRight = marginLeft + plotWidth;
   const columns = valueRows.columns.map((column, index) => ({
     ...column,
     x: marginLeft + index * cellWidth,
@@ -1526,6 +1662,11 @@ function heatmapLayout(valueRows, opts) {
     sampleLabelColumn: valueRows.sampleLabelColumn,
     plotWidth,
     cellWidth,
+    colorBar: fit ? colorBarLayout(colorBarSpec, {
+      x: gridRight + fit.gap,
+      y1: colorBarTop,
+      y2: plotBottom
+    }) : null,
     height: plotBottom + AXIS_HEIGHT4
   };
 }
@@ -1556,6 +1697,10 @@ export {
   waterfallRows,
   waterfallLayout,
   sampleColormap,
+  colorBarExtent,
+  fitColorBar,
+  colorBarLayout,
+  scalarFormatterLabels,
   BEESWARM_MISSING_COLOR,
   BEESWARM_ROW_HEIGHT,
   beeswarmRows,
@@ -1563,4 +1708,4 @@ export {
   heatmapRows,
   heatmapLayout
 };
-//# sourceMappingURL=chunk-OXFKP5I3.js.map
+//# sourceMappingURL=chunk-ZWO4CN22.js.map