shap-svg 0.2.1 → 0.2.3

package/README.md

@@ -172,6 +172,7 @@ Shared by all four charts:
 | `classIndex` | `1` | which output to draw for multi-output explanations |
 | `width` | `720` | SVG width in pixels |
 | `rowHeight` | per chart | pixels per feature row |
+| `labels` | SHAP's wording | text the chart draws; see [Wording](#wording) |
 | `onFeatureClick` | — | called with the feature index, or `null` for the "other" row |
 
 Per chart:
@@ -185,6 +186,43 @@ Per chart:
 | `Plots.waterfall` | `sampleIndex` | `0` | which sample to explain |
 | `Plots.waterfall` | `decimals` | `2` | `2`, `3`, `4` or `"percent"`; display only |
 
+## Wording
+
+Every piece of text a chart draws comes from `labels`, keyed by what it means rather than where it
+appears — a word used in two places is changed once. Give only the keys you want to change; the rest
+keep SHAP's wording, exported as `shapLabels`.
+
+```tsx
+import { Plots } from "shap-svg/react";
+import type { PlotLabels } from "shap-svg";
+
+// A module constant: a new object on every render recomputes the layout on every render.
+const researchLabels: Partial<PlotLabels> = {
+  shapValue: "Contribution",
+  shapValueAxis: "Contribution to predicted probability",
+  featureValue: "Relative abundance",
+  otherFeatures: (count) => `${count} other taxa`,
+};
+
+<Plots.beeswarm explanation={explanation} labels={researchLabels} />;
+```
+
+| Key | Default | Drawn as |
+| --- | --- | --- |
+| `shapValue` | `SHAP value` | beeswarm tooltip |
+| `shapValueAxis` | `SHAP value (impact on model output)` | beeswarm x axis, heatmap colour bar |
+| `meanAbsShapValue` | `mean(\|SHAP value\|)` | bar x axis |
+| `featureValue` | `Feature value` | beeswarm tooltip and colour bar |
+| `featureValueLow`, `featureValueHigh` | `Low`, `High` | ends of the beeswarm colour bar |
+| `missingFeatureValue` | `missing` | beeswarm tooltip, for a value the payload lacks |
+| `samples` | `Instances` | heatmap x axis |
+| `sampleTotal` | `Σφ` | heatmap tooltip |
+| `sampleFallback(n)` | `Sample n` | a heatmap column with no `sample_labels` entry |
+| `baseValue`, `modelOutput` | `E[f(X)]`, `f(x)` | the waterfall's two reference lines |
+| `otherFeatures(count, style)` | `Sum of N other features` / `N other features` | the row for every feature not shown; `style` is `"sum"` in `faithfulOtherRow` mode on bar, beeswarm and heatmap |
+
+Accessible names are built from the same words.
+
 ## Faithful to SHAP where it matters
 
 Ordering, the "other features" partition, colour maps, tick placement and the waterfall's geometry are

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

@@ -261,8 +261,34 @@ function formatFeatureLabel(name) {
   return name.replace(/_/g, " ");
 }
 
+// src/core/labels.ts
+var shapLabels = {
+  shapValue: "SHAP value",
+  shapValueAxis: "SHAP value (impact on model output)",
+  meanAbsShapValue: "mean(|SHAP value|)",
+  featureValue: "Feature value",
+  featureValueLow: "Low",
+  featureValueHigh: "High",
+  missingFeatureValue: "missing",
+  samples: "Instances",
+  sampleTotal: "\u03A3\u03C6",
+  sampleFallback: (sampleNumber) => `Sample ${sampleNumber}`,
+  baseValue: "E[f(X)]",
+  modelOutput: "f(x)",
+  otherFeatures: (count, style) => style === "sum" ? `Sum of ${count} other features` : `${count} other features`
+};
+function resolveLabels(labels) {
+  if (!labels) return shapLabels;
+  const resolved = { ...shapLabels };
+  for (const key of Object.keys(labels)) {
+    const value = labels[key];
+    if (value !== void 0) resolved[key] = value;
+  }
+  return resolved;
+}
+
 // src/core/collapse.ts
-function collapseToDisplay(featureNames, importance, order, maxDisplay, faithfulOtherRow) {
+function collapseToDisplay(featureNames, importance, order, maxDisplay, faithfulOtherRow, labels = shapLabels) {
   const p = order.length;
   if (maxDisplay >= p) {
     return {
@@ -285,7 +311,7 @@ function collapseToDisplay(featureNames, importance, order, maxDisplay, faithful
   const collapsed = order.slice(realCount);
   const collapsedValue = collapsed.reduce((sum, index) => sum + importance[index], 0);
   rows.push({
-    label: faithfulOtherRow ? `Sum of ${collapsed.length} other features` : `${collapsed.length} other features`,
+    label: labels.otherFeatures(collapsed.length, faithfulOtherRow ? "sum" : "count"),
     featureIndex: null,
     value: collapsedValue,
     isOtherRow: true
@@ -354,15 +380,15 @@ var AXIS_HEIGHT = 52;
 var TICK_LABEL_PT = 11;
 var TITLE_PT = 13;
 var X_MARGIN = 0.05;
-function barXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
+function barXAxis(min, max, toX, marginLeft, plotWidth, plotBottom, title) {
   const { ticks, step } = niceTicks(min, max, tickSpace(plotWidth, TICK_LABEL_PT));
   return {
     xTicks: ticks.map((value) => ({ value, x: toX(value), label: tickLabel(value, step) })),
     xSpine: { x1: marginLeft, x2: marginLeft + plotWidth, y: plotBottom },
     xTitle: {
-      // _bar.py:143-150 builds this from the Explanation's transform history:
-      // "SHAP value" -> "|SHAP value|" -> "mean(|SHAP value|)".
-      text: "mean(|SHAP value|)",
+      // _bar.py:143-150 builds the default from the Explanation's transform
+      // history: "SHAP value" -> "|SHAP value|" -> "mean(|SHAP value|)".
+      text: title,
       x: marginLeft + plotWidth / 2,
       y: plotBottom + AXIS_TITLE_DY,
       fontSize: TITLE_PT
@@ -370,6 +396,7 @@ function barXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
   };
 }
 function barLayout(rows, opts) {
+  var _a;
   const { width, rowHeight, marginLeft, marginRight, marginTop } = opts;
   const plotWidth = width - marginLeft - marginRight;
   const values = rows.rows.map((r) => r.value);
@@ -410,7 +437,15 @@ function barLayout(rows, opts) {
     xZero,
     plotWidth,
     plotBottom: marginTop + rows.rows.length * rowHeight,
-    ...barXAxis(min, max, toX, marginLeft, plotWidth, marginTop + rows.rows.length * rowHeight),
+    ...barXAxis(
+      min,
+      max,
+      toX,
+      marginLeft,
+      plotWidth,
+      marginTop + rows.rows.length * rowHeight,
+      ((_a = opts.labels) != null ? _a : shapLabels).meanAbsShapValue
+    ),
     zeroLine: { x: xZero, y1: marginTop, y2: marginTop + rows.rows.length * rowHeight },
     height: marginTop + rows.rows.length * rowHeight + AXIS_HEIGHT
   };
@@ -444,7 +479,7 @@ function placeValueLabel(value, startX, endX, gutterX, decimals) {
   }
   return { ...base, x: startX + VALUE_LABEL_GAP, anchor: "start", inside: false };
 }
-function waterfallRows(explanation, sampleIndex, maxDisplay, faithfulOtherRow) {
+function waterfallRows(explanation, sampleIndex, maxDisplay, faithfulOtherRow, labels = shapLabels) {
   if (!Number.isInteger(sampleIndex) || sampleIndex < 0 || sampleIndex >= explanation.nSamples) {
     throw new RangeError(
       `sampleIndex must identify a Sample from 0 to ${explanation.nSamples - 1}, received ${sampleIndex}`
@@ -482,7 +517,8 @@ function waterfallRows(explanation, sampleIndex, maxDisplay, faithfulOtherRow) {
   if (hasOtherRow) {
     const value = collapsed.reduce((sum, featureIndex) => sum + values[featureIndex], 0);
     rows.push({
-      label: `${collapsed.length} other features`,
+      // SHAP's waterfall counts the hidden Features whatever the collapse mode.
+      label: labels.otherFeatures(collapsed.length, "count"),
       featureIndex: null,
       isOtherRow: true,
       value,
@@ -500,7 +536,9 @@ function waterfallRows(explanation, sampleIndex, maxDisplay, faithfulOtherRow) {
   };
 }
 function waterfallLayout(valueRows, opts) {
+  var _a;
   const { width, rowHeight, marginLeft, marginRight, marginTop } = opts;
+  const labels = (_a = opts.labels) != null ? _a : shapLabels;
   const plotWidth = width - marginLeft - marginRight;
   const coordinates = [valueRows.baseValue, valueRows.modelOutput];
   for (const row of valueRows.rows) coordinates.push(row.left, row.left + row.width);
@@ -567,7 +605,7 @@ function waterfallLayout(valueRows, opts) {
         // got, which is the whole reason SHAP hides the left spine.
         y1: plotBottom - rowHeight,
         y2: plotBottom,
-        label: `E[f(X)] = ${formatLevel(valueRows.baseValue, opts.decimals)}`
+        label: `${labels.baseValue} = ${formatLevel(valueRows.baseValue, opts.decimals)}`
       },
       {
         kind: "output",
@@ -576,7 +614,7 @@ function waterfallLayout(valueRows, opts) {
         // axvline(fx, 0, 1) — the full height.
         y1: marginTop,
         y2: plotBottom,
-        label: `f(x) = ${formatLevel(valueRows.modelOutput, opts.decimals)}`
+        label: `${labels.modelOutput} = ${formatLevel(valueRows.modelOutput, opts.decimals)}`
       }
     ],
     separators: valueRows.rows.map((_, index) => ({
@@ -1240,17 +1278,35 @@ function scalarFormatterLabels(locs) {
   return order === 0 ? { labels } : { labels, offsetText: `1e${String(order).replace("-", MINUS3)}` };
 }
 
+// src/core/tooltip.ts
+var CHAR_PX = 6.5;
+var PADDING_X = 7;
+var OFFSET = 8;
+var RAISE = 24;
+function placeTooltip(opts) {
+  const { anchorX, anchorY, lines, lineHeight, minWidth, chartWidth, chartHeight } = opts;
+  const longest = lines.reduce((max, line) => Math.max(max, line.length), 0);
+  const width = Math.max(minWidth, longest * CHAR_PX + 2 * PADDING_X);
+  const height = lines.length * lineHeight + lineHeight * 0.6;
+  const right = anchorX + OFFSET;
+  const x = right + width <= chartWidth ? right : Math.max(0, anchorX - OFFSET - width);
+  const y = Math.max(0, Math.min(anchorY - RAISE, chartHeight - height));
+  return { x, y, width, height };
+}
+
 // src/core/beeswarmLayout.ts
 var BEESWARM_MISSING_COLOR = "#777777";
 var BEESWARM_ROW_HEIGHT = 0.4;
 var NBINS = 100;
 var AXIS_HEIGHT3 = 52;
-var COLOR_BAR = {
-  colormap: "red_blue",
-  tickLabels: ["Low", "High"],
-  label: "Feature value",
-  labelPad: 0
-};
+function colorBarSpec(labels) {
+  return {
+    colormap: "red_blue",
+    tickLabels: [labels.featureValueLow, labels.featureValueHigh],
+    label: labels.featureValue,
+    labelPad: 0
+  };
+}
 var COLOR_BAR_GAP_RATIO = 0.05 / 0.8;
 var TICK_LABEL_PT4 = 11;
 var TITLE_PT2 = 13;
@@ -1316,7 +1372,7 @@ function spreadPoints(xs, rowIndex, seed) {
   const scale = 0.9 * (BEESWARM_ROW_HEIGHT / (maxPositiveOffset + 1));
   return offsets.map((offset) => rowIndex + offset * scale);
 }
-function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSort = "importance") {
+function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSort = "importance", labels = shapLabels) {
   if (!Number.isInteger(maxDisplay) || maxDisplay <= 0) {
     throw new RangeError(`maxDisplay must be a positive integer, received ${maxDisplay}`);
   }
@@ -1331,7 +1387,8 @@ function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSo
       importance,
       order,
       maxDisplay,
-      faithfulOtherRow
+      faithfulOtherRow,
+      labels
     ),
     rowSort,
     explanation.data
@@ -1383,14 +1440,14 @@ function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSo
   });
   return { rows, collapsedCount: display.collapsedCount };
 }
-function beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
+function beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom, title) {
   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 },
     xTitle: {
-      // _labels.py:5, labels["VALUE"].
-      text: "SHAP value (impact on model output)",
+      // The default is _labels.py:5, labels["VALUE"].
+      text: title,
       x: marginLeft + plotWidth / 2,
       y: plotBottom + AXIS_TITLE_DY,
       fontSize: TITLE_PT2
@@ -1398,14 +1455,17 @@ function beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
   };
 }
 function beeswarmLayout(valueRows, opts) {
+  var _a;
   const { width, rowHeight, marginLeft, marginRight, marginTop, dotRadius } = opts;
+  const labels = (_a = opts.labels) != null ? _a : shapLabels;
+  const colorBar = colorBarSpec(labels);
   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)
+    extent: colorBarExtent(plotBottom - marginTop, colorBar)
   }) : null;
   const plotWidth = fit ? fit.plotWidth : width - marginLeft - marginRight;
   const values = valueRows.rows.flatMap((row) => row.points.map((point) => point.x));
@@ -1436,10 +1496,10 @@ function beeswarmLayout(valueRows, opts) {
     rows,
     xDomain: [min, max],
     xZero: toX(0),
-    ...beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom),
+    ...beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom, labels.shapValueAxis),
     plotWidth,
     plotBottom,
-    colorBar: fit ? colorBarLayout(COLOR_BAR, {
+    colorBar: fit ? colorBarLayout(colorBar, {
       x: marginLeft + plotWidth + fit.gap,
       y1: marginTop,
       y2: plotBottom
@@ -1469,7 +1529,7 @@ function percentile2(values, fraction) {
   const weight = position - lower;
   return sorted[lower] + (sorted[upper] - sorted[lower]) * weight;
 }
-function heatmapRows(explanation, maxDisplay, faithfulOtherRow, rowSort = "importance") {
+function heatmapRows(explanation, maxDisplay, faithfulOtherRow, rowSort = "importance", labels = shapLabels) {
   if (!Number.isInteger(maxDisplay) || maxDisplay <= 0) {
     throw new RangeError(`maxDisplay must be a positive integer, received ${maxDisplay}`);
   }
@@ -1481,7 +1541,8 @@ function heatmapRows(explanation, maxDisplay, faithfulOtherRow, rowSort = "impor
       importance,
       featureOrder,
       maxDisplay,
-      faithfulOtherRow
+      faithfulOtherRow,
+      labels
     ),
     rowSort,
     explanation.data
@@ -1545,7 +1606,7 @@ function heatmapRows(explanation, maxDisplay, faithfulOtherRow, rowSort = "impor
     sampleLabelColumn: explanation.sampleLabelColumn
   };
 }
-function heatmapXAxis(sampleCount, marginLeft, cellWidth, plotWidth, plotBottom) {
+function heatmapXAxis(sampleCount, marginLeft, cellWidth, plotWidth, plotBottom, title) {
   const { ticks, step } = niceTicks(
     -0.5,
     sampleCount - 0.5,
@@ -1560,7 +1621,7 @@ function heatmapXAxis(sampleCount, marginLeft, cellWidth, plotWidth, plotBottom)
     })),
     xSpine: null,
     xTitle: {
-      text: "Instances",
+      text: title,
       x: marginLeft + plotWidth / 2,
       y: plotBottom + AXIS_TITLE_DY,
       fontSize: TICK_LABEL_PT5
@@ -1568,15 +1629,17 @@ function heatmapXAxis(sampleCount, marginLeft, cellWidth, plotWidth, plotBottom)
   };
 }
 function heatmapLayout(valueRows, opts) {
+  var _a;
   const { width, rowHeight, marginLeft, marginRight, marginTop } = opts;
+  const labels = (_a = opts.labels) != null ? _a : shapLabels;
   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 = {
+  const colorBarSpec2 = {
     colormap: "red_white_blue",
     tickLabels: [ticks.labels[0], ticks.labels[1]],
     ...ticks.offsetText ? { offsetText: ticks.offsetText } : {},
-    label: "SHAP value (impact on model output)",
+    label: labels.shapValueAxis,
     labelPad: -10
   };
   const colorBarTop = FX_TOP;
@@ -1585,7 +1648,7 @@ function heatmapLayout(valueRows, opts) {
     available: marginRight,
     gapRatio: COLOR_BAR_GAP_RATIO2,
     minGap: SIDE_BAR_GAP + sideBarWidth + COLOR_BAR_CLEARANCE,
-    extent: colorBarExtent(plotBottom - colorBarTop, colorBarSpec)
+    extent: colorBarExtent(plotBottom - colorBarTop, colorBarSpec2)
   }) : null;
   const plotWidth = fit ? fit.plotWidth : width - marginLeft - marginRight;
   const cellWidth = valueRows.columns.length === 0 ? 0 : plotWidth / valueRows.columns.length;
@@ -1658,11 +1721,18 @@ function heatmapLayout(valueRows, opts) {
       x1: marginLeft - Y_TICK_LENGTH,
       x2: marginLeft
     })),
-    ...heatmapXAxis(valueRows.columns.length, marginLeft, cellWidth, plotWidth, plotBottom),
+    ...heatmapXAxis(
+      valueRows.columns.length,
+      marginLeft,
+      cellWidth,
+      plotWidth,
+      plotBottom,
+      labels.samples
+    ),
     sampleLabelColumn: valueRows.sampleLabelColumn,
     plotWidth,
     cellWidth,
-    colorBar: fit ? colorBarLayout(colorBarSpec, {
+    colorBar: fit ? colorBarLayout(colorBarSpec2, {
       x: gridRight + fit.gap,
       y1: colorBarTop,
       y2: plotBottom
@@ -1685,6 +1755,8 @@ export {
   formatShapValue,
   formatLevel,
   formatFeatureLabel,
+  shapLabels,
+  resolveLabels,
   collapseToDisplay,
   TICK_LENGTH,
   TICK_LABEL_DY,
@@ -1701,6 +1773,7 @@ export {
   fitColorBar,
   colorBarLayout,
   scalarFormatterLabels,
+  placeTooltip,
   BEESWARM_MISSING_COLOR,
   BEESWARM_ROW_HEIGHT,
   beeswarmRows,
@@ -1708,4 +1781,4 @@ export {
   heatmapRows,
   heatmapLayout
 };
-//# sourceMappingURL=chunk-ZWO4CN22.js.map
+//# sourceMappingURL=chunk-UVIVTJK3.js.map