shap-svg 0.2.1 → 0.2.2

package/dist/index.cjs

@@ -48,8 +48,10 @@ __export(index_exports, {
   heatmapRows: () => heatmapRows,
   orderFeatures: () => orderFeatures,
   parseExplanation: () => parseExplanation,
+  resolveLabels: () => resolveLabels,
   sampleColormap: () => sampleColormap,
   scalarFormatterLabels: () => scalarFormatterLabels,
+  shapLabels: () => shapLabels,
   sortDisplayRows: () => sortDisplayRows,
   waterfallLayout: () => waterfallLayout,
   waterfallRows: () => waterfallRows
@@ -319,8 +321,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 {
@@ -343,7 +371,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
@@ -410,15 +438,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
@@ -426,6 +454,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);
@@ -466,7 +495,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
   };
@@ -500,7 +537,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}`
@@ -538,7 +575,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,
@@ -556,7 +594,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);
@@ -623,7 +663,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",
@@ -632,7 +672,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) => ({
@@ -1301,12 +1341,14 @@ 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;
@@ -1372,7 +1414,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}`);
   }
@@ -1387,7 +1429,8 @@ function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSo
       importance,
       order,
       maxDisplay,
-      faithfulOtherRow
+      faithfulOtherRow,
+      labels
     ),
     rowSort,
     explanation.data
@@ -1439,14 +1482,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
@@ -1454,14 +1497,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));
@@ -1492,10 +1538,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
@@ -1525,7 +1571,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}`);
   }
@@ -1537,7 +1583,8 @@ function heatmapRows(explanation, maxDisplay, faithfulOtherRow, rowSort = "impor
       importance,
       featureOrder,
       maxDisplay,
-      faithfulOtherRow
+      faithfulOtherRow,
+      labels
     ),
     rowSort,
     explanation.data
@@ -1601,7 +1648,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,
@@ -1616,7 +1663,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
@@ -1624,15 +1671,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;
@@ -1641,7 +1690,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;
@@ -1714,11 +1763,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
@@ -1756,8 +1812,10 @@ function heatmapLayout(valueRows, opts) {
   heatmapRows,
   orderFeatures,
   parseExplanation,
+  resolveLabels,
   sampleColormap,
   scalarFormatterLabels,
+  shapLabels,
   sortDisplayRows,
   waterfallLayout,
   waterfallRows