shap-svg 0.2.0 → 0.2.1

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,
@@ -46,6 +49,7 @@ __export(index_exports, {
   orderFeatures: () => orderFeatures,
   parseExplanation: () => parseExplanation,
   sampleColormap: () => sampleColormap,
+  scalarFormatterLabels: () => scalarFormatterLabels,
   sortDisplayRows: () => sortDisplayRows,
   waterfallLayout: () => waterfallLayout,
   waterfallRows: () => waterfallRows
@@ -1193,12 +1197,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) {
@@ -1330,7 +1440,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 },
@@ -1345,7 +1455,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);
@@ -1370,7 +1488,6 @@ function beeswarmLayout(valueRows, opts) {
       }))
     };
   });
-  const plotBottom = marginTop + valueRows.rows.length * rowHeight;
   return {
     rows,
     xDomain: [min, max],
@@ -1378,6 +1495,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
   };
 }
@@ -1390,7 +1512,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;
@@ -1481,7 +1605,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 {
@@ -1495,17 +1619,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,
@@ -1578,6 +1718,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
   };
 }
@@ -1597,6 +1742,9 @@ function heatmapLayout(valueRows, opts) {
   beeswarmLayout,
   beeswarmRows,
   collapseToDisplay,
+  colorBarExtent,
+  colorBarLayout,
+  fitColorBar,
   formatFeatureLabel,
   formatLevel,
   formatShapValue,
@@ -1609,6 +1757,7 @@ function heatmapLayout(valueRows, opts) {
   orderFeatures,
   parseExplanation,
   sampleColormap,
+  scalarFormatterLabels,
   sortDisplayRows,
   waterfallLayout,
   waterfallRows