shap-svg 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -34,6 +34,9 @@ __export(index_exports, {
   beeswarmLayout: () => beeswarmLayout,
   beeswarmRows: () => beeswarmRows,
   collapseToDisplay: () => collapseToDisplay,
+  colorBarExtent: () => colorBarExtent,
+  colorBarLayout: () => colorBarLayout,
+  fitColorBar: () => fitColorBar,
   formatFeatureLabel: () => formatFeatureLabel,
   formatLevel: () => formatLevel,
   formatShapValue: () => formatShapValue,
@@ -45,7 +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
@@ -315,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 {
@@ -339,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
@@ -406,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
@@ -422,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);
@@ -462,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
   };
@@ -496,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}`
@@ -534,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,
@@ -552,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);
@@ -619,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",
@@ -628,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) => ({
@@ -1193,12 +1237,120 @@ 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;
+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;
 var X_MARGIN2 = 0.05;
 function percentile(values, percent) {
@@ -1262,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}`);
   }
@@ -1277,7 +1429,8 @@ function beeswarmRows(explanation, maxDisplay, faithfulOtherRow, seed = 0, rowSo
       importance,
       order,
       maxDisplay,
-      faithfulOtherRow
+      faithfulOtherRow,
+      labels
     ),
     rowSort,
     explanation.data
@@ -1329,14 +1482,14 @@ 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));
+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
@@ -1344,8 +1497,19 @@ function beeswarmXAxis(min, max, toX, marginLeft, plotWidth, plotBottom) {
   };
 }
 function beeswarmLayout(valueRows, opts) {
+  var _a;
   const { width, rowHeight, marginLeft, marginRight, marginTop, dotRadius } = opts;
-  const plotWidth = width - marginLeft - marginRight;
+  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, colorBar)
+  }) : 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);
@@ -1370,14 +1534,18 @@ function beeswarmLayout(valueRows, opts) {
       }))
     };
   });
-  const plotBottom = marginTop + valueRows.rows.length * rowHeight;
   return {
     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(colorBar, {
+      x: marginLeft + plotWidth + fit.gap,
+      y1: marginTop,
+      y2: plotBottom
+    }) : null,
     height: plotBottom + AXIS_HEIGHT3
   };
 }
@@ -1390,7 +1558,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;
@@ -1401,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}`);
   }
@@ -1413,7 +1583,8 @@ function heatmapRows(explanation, maxDisplay, faithfulOtherRow, rowSort = "impor
       importance,
       featureOrder,
       maxDisplay,
-      faithfulOtherRow
+      faithfulOtherRow,
+      labels
     ),
     rowSort,
     explanation.data
@@ -1477,11 +1648,11 @@ 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,
-    tickSpace(plotWidth, TICK_LABEL_PT4),
+    tickSpace(plotWidth, TICK_LABEL_PT5),
     { integer: true }
   );
   return {
@@ -1492,20 +1663,38 @@ 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_PT4
+      fontSize: TICK_LABEL_PT5
     }
   };
 }
 function heatmapLayout(valueRows, opts) {
+  var _a;
   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 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 colorBarSpec2 = {
+    colormap: "red_white_blue",
+    tickLabels: [ticks.labels[0], ticks.labels[1]],
+    ...ticks.offsetText ? { offsetText: ticks.offsetText } : {},
+    label: labels.shapValueAxis,
+    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, colorBarSpec2)
+  }) : 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,
@@ -1574,10 +1763,22 @@ 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(colorBarSpec2, {
+      x: gridRight + fit.gap,
+      y1: colorBarTop,
+      y2: plotBottom
+    }) : null,
     height: plotBottom + AXIS_HEIGHT4
   };
 }
@@ -1597,6 +1798,9 @@ function heatmapLayout(valueRows, opts) {
   beeswarmLayout,
   beeswarmRows,
   collapseToDisplay,
+  colorBarExtent,
+  colorBarLayout,
+  fitColorBar,
   formatFeatureLabel,
   formatLevel,
   formatShapValue,
@@ -1608,7 +1812,10 @@ function heatmapLayout(valueRows, opts) {
   heatmapRows,
   orderFeatures,
   parseExplanation,
+  resolveLabels,
   sampleColormap,
+  scalarFormatterLabels,
+  shapLabels,
   sortDisplayRows,
   waterfallLayout,
   waterfallRows