shap-svg 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,456 @@
+import { P as ParsedExplanation, D as DisplayRows, V as ValuePrecision, R as RowSort } from './format-wEav_cPe.js';
+export { a as DisplayRow, E as Explanation, I as InvalidExplanationError, U as UnsupportedContractVersionError, f as formatFeatureLabel, b as formatLevel, c as formatShapValue, s as sortDisplayRows } from './format-wEav_cPe.js';
+
+/**
+ * Taxonomy-aware views of an Explanation.
+ *
+ * Feature names in this platform are `Genus_species`, which is a real structure
+ * the generic charts ignore. At the species level a genus the model genuinely
+ * uses can be spread across a dozen columns, each with a SHAP value small
+ * enough to read as noise, while the genus as a whole is one of the strongest
+ * signals present. The runtime already offers the same collapse behind
+ * `?aggregate_by=genus`; doing it here instead costs no request, because the
+ * per-species values are already in the browser.
+ */
+/** The genus part of a `Genus_species` name. */
+declare function genusOf(featureName: string): string;
+type GenusGrouping = {
+    /** Genera in first-seen order. */
+    genera: string[];
+    /** For each genus, the Feature indices belonging to it. */
+    memberIndices: number[][];
+};
+/**
+ * Group Feature indices by genus, preserving first-seen order.
+ *
+ * Order matters: it is what keeps the grouping stable across requests, and it
+ * is the same rule `_aggregate_shap_by_genus` uses in the runtime, so the two
+ * paths cannot disagree about which column belongs where.
+ */
+declare function groupByGenus(featureNames: string[]): GenusGrouping;
+type AggregatedExplanation = {
+    values: number[][];
+    data: number[][];
+    featureNames: string[];
+};
+/**
+ * Collapse `Genus_species` columns into one column per genus.
+ *
+ * Summing is the correct operator, not averaging: SHAP is additive, so the
+ * per-Feature values satisfy `base + sum(phi) = f(x)`. A sum within groups is a
+ * re-partition of that same total, which leaves the identity intact — every
+ * waterfall still adds up, and there is a test saying so. Abundance is summed
+ * for the same reason, giving the genus's total relative abundance, which is
+ * what the colour should mean once the rows are genera.
+ */
+declare function aggregateByGenus(values: number[][], data: number[][], featureNames: string[]): AggregatedExplanation;
+/**
+ * A parsed Explanation with its Feature axis collapsed to genera.
+ *
+ * Only the Feature axis changes. Base values, Sample ids and the Sample count
+ * carry through untouched, so everything downstream — ordering, the Other row,
+ * the waterfall walk — runs unchanged on genera, and `base + sum(phi) = f(x)`
+ * still holds for every Sample. The input is not mutated.
+ */
+declare function groupExplanationByGenus(explanation: ParsedExplanation): ParsedExplanation;
+
+declare function parseExplanation(input: unknown, opts?: {
+    classIndex?: number;
+}): ParsedExplanation;
+
+/** mean(|phi|) over Samples, per Feature — what shap.plots.bar collapses a 2-D Explanation to. */
+declare function globalImportance(e: ParsedExplanation): number[];
+/** Descending by importance; ties resolved by ascending index so renders are reproducible. */
+declare function orderFeatures(importance: number[]): number[];
+
+/**
+ * Spec 3.4. `faithfulOtherRow` reproduces shap/plots/_bar.py:228-241, where the last displayed row
+ * absorbs the Feature ranked `maxDisplay` — so maxDisplay=15 shows 14 real Features. The default
+ * corrected mode shows `maxDisplay` real Features and adds the Other features row alongside.
+ */
+declare function collapseToDisplay(featureNames: string[], importance: number[], order: number[], maxDisplay: number, faithfulOtherRow: boolean): DisplayRows;
+
+type AxisTick = {
+    value: number;
+    x: number;
+    label: string;
+};
+type AxisSpine = {
+    x1: number;
+    x2: number;
+    y: number;
+};
+type AxisTitle = {
+    text: string;
+    x: number;
+    y: number;
+    fontSize: number;
+};
+
+declare const POSITIVE_COLOR = "#ff0051";
+declare const NEGATIVE_COLOR = "#008bfb";
+type BarLayoutOptions = {
+    width: number;
+    rowHeight: number;
+    marginLeft: number;
+    marginRight: number;
+    marginTop: number;
+};
+type BarGeometry = {
+    label: string;
+    featureIndex: number | null;
+    isOtherRow: boolean;
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color: string;
+    /** vertical centre of the row, for label baselines */
+    centerY: number;
+};
+type BarLayout = {
+    bars: BarGeometry[];
+    xDomain: [number, number];
+    xZero: number;
+    plotWidth: number;
+    /** Bottom edge of the last row, where the axis area begins. */
+    plotBottom: number;
+    xTicks: AxisTick[];
+    /** The bottom spine, which _bar.py:327-330 never hides. */
+    xSpine: AxisSpine | null;
+    xTitle: AxisTitle;
+    /**
+     * The solid vertical at zero. Always present, because SHAP's two code paths
+     * converge on it: _bar.py:252-254 draws axvline(0) when a value is negative,
+     * and _bar.py:329-330 hides the left spine only in that same case. With no
+     * negatives the spine stays and barh pins the axes' left edge to 0 — so
+     * either way there is one line at zero. Mean |SHAP| is never negative, so the
+     * summary chart always takes the spine path.
+     */
+    zeroLine: {
+        x: number;
+        y1: number;
+        y2: number;
+    };
+    height: number;
+};
+declare function barLayout(rows: DisplayRows, opts: BarLayoutOptions): BarLayout;
+
+/** Fixed on-screen arrowhead length; matplotlib's equivalent is 0.08 inches. */
+declare const WATERFALL_HEAD_LENGTH_PX = 8;
+declare const WATERFALL_TICK_LABEL_DY = 18;
+declare const WATERFALL_BASE_LABEL_DY = 36;
+type WaterfallRow = {
+    label: string;
+    featureIndex: number | null;
+    isOtherRow: boolean;
+    /** The full, unrounded SHAP contribution represented by this row. */
+    value: number;
+    /** Start of the arrow in value space while walking backward from f(x). */
+    left: number;
+    /** Signed full arrow width in value space. */
+    width: number;
+    /** matplotlib-compatible row number, counted upward from the bottom. */
+    row: number;
+    color: string;
+};
+type WaterfallRows = {
+    /** Rows are ordered top-to-bottom. */
+    rows: WaterfallRow[];
+    baseValue: number;
+    modelOutput: number;
+    collapsedCount: number;
+};
+type WaterfallLayoutOptions = {
+    width: number;
+    rowHeight: number;
+    marginLeft: number;
+    marginRight: number;
+    marginTop: number;
+    /** Decimal places for the bar labels. Display only; omit for 3 significant figures. */
+    decimals?: ValuePrecision;
+};
+type Point = {
+    x: number;
+    y: number;
+};
+/** Where a bar's numeric label goes, and roughly how wide it is. */
+type WaterfallValueLabel = {
+    x: number;
+    anchor: "start" | "middle" | "end";
+    /** Estimated from the glyph count — enough to decide whether it fits. */
+    estimatedWidth: number;
+    /** Drawn over the bar, so the renderer must paint it in a contrasting colour. */
+    inside: boolean;
+    text: string;
+};
+type WaterfallArrowGeometry = WaterfallRow & {
+    points: Point[];
+    startX: number;
+    endX: number;
+    y: number;
+    centerY: number;
+    height: number;
+    headLength: number;
+    valueLabel: WaterfallValueLabel;
+};
+type WaterfallAxisMark = {
+    kind: "base" | "output";
+    value: number;
+    x: number;
+    /** Vertical extent of the dashed rule. The two do not match — see below. */
+    y1: number;
+    y2: number;
+    label: string;
+};
+/**
+ * The dashed vertical joining one bar's start to the next bar's end.
+ *
+ * shap/plots/_waterfall.py:130-137 draws these inside the loop that walks the
+ * contributions, at `loc` immediately after `loc -= sval` — so the line sits
+ * exactly where the two bars meet, which is what shows the reader that the
+ * steps really do join up.
+ */
+type WaterfallConnector = {
+    x: number;
+    y1: number;
+    y2: number;
+};
+type WaterfallTick = {
+    value: number;
+    x: number;
+    label: string;
+};
+type WaterfallSeparator = {
+    y: number;
+    x1: number;
+    x2: number;
+};
+type WaterfallLayout = {
+    arrows: WaterfallArrowGeometry[];
+    axisMarks: WaterfallAxisMark[];
+    connectors: WaterfallConnector[];
+    xTicks: WaterfallTick[];
+    separators: WaterfallSeparator[];
+    xDomain: [number, number];
+    plotWidth: number;
+    /** Left and right edge of the plot area, where the axis is drawn. */
+    plotLeft: number;
+    plotRight: number;
+    plotBottom: number;
+    height: number;
+};
+/**
+ * The value-space part of shap/plots/_waterfall.py::waterfall_legacy.
+ * It walks backward from f(x), leaving pixel scaling and arrowheads to waterfallLayout.
+ */
+declare function waterfallRows(explanation: ParsedExplanation, sampleIndex: number, maxDisplay: number, faithfulOtherRow: boolean): WaterfallRows;
+declare function waterfallLayout(valueRows: WaterfallRows, opts: WaterfallLayoutOptions): WaterfallLayout;
+
+type ColormapName = "red_blue" | "red_white_blue";
+/** Samples a captured SHAP colour map, interpolating adjacent LUT entries in sRGB. */
+declare function sampleColormap(name: ColormapName, t: number): string;
+
+declare const BEESWARM_MISSING_COLOR = "#777777";
+declare const BEESWARM_ROW_HEIGHT = 0.4;
+type BeeswarmPoint = {
+    sampleIndex: number;
+    /** SHAP value in value space. */
+    x: number;
+    /** SHAP-compatible row coordinate, including signed vertical jitter. */
+    y: number;
+    /** Original Feature value before percentile clipping. */
+    featureValue: number;
+    /** Value sent through the colour map, or null when the Feature value is missing. */
+    colorValue: number | null;
+    color: string;
+};
+type BeeswarmRow = {
+    label: string;
+    featureIndex: number | null;
+    isOtherRow: boolean;
+    /** SHAP row number, counted upward from the bottom. */
+    rowIndex: number;
+    vmin: number;
+    vmax: number;
+    points: BeeswarmPoint[];
+};
+type BeeswarmRows = {
+    /** Rows are ordered top-to-bottom. */
+    rows: BeeswarmRow[];
+    collapsedCount: number;
+};
+type BeeswarmLayoutOptions = {
+    width: number;
+    rowHeight: number;
+    marginLeft: number;
+    marginRight: number;
+    marginTop: number;
+    dotRadius: number;
+};
+type BeeswarmPointGeometry = Omit<BeeswarmPoint, "x" | "y"> & {
+    x: number;
+    y: number;
+    valueX: number;
+    valueY: number;
+    radius: number;
+};
+type BeeswarmRowGeometry = Omit<BeeswarmRow, "points"> & {
+    centerY: number;
+    points: BeeswarmPointGeometry[];
+};
+type BeeswarmLayout = {
+    rows: BeeswarmRowGeometry[];
+    xDomain: [number, number];
+    xZero: number;
+    plotWidth: number;
+    plotBottom: number;
+    xTicks: AxisTick[];
+    /** The bottom spine, which _beeswarm.py:493-495 leaves visible. */
+    xSpine: AxisSpine | null;
+    xTitle: AxisTitle;
+    height: number;
+};
+/**
+ * Computes SHAP-compatible beeswarm rows entirely in value space. Pixel scaling belongs in
+ * beeswarmLayout so golden values can be compared without a viewport.
+ */
+declare function beeswarmRows(explanation: ParsedExplanation, maxDisplay: number, faithfulOtherRow: boolean, seed?: number, rowSort?: RowSort): BeeswarmRows;
+/** Projects beeswarm value-space rows into SVG coordinates. */
+declare function beeswarmLayout(valueRows: BeeswarmRows, opts: BeeswarmLayoutOptions): BeeswarmLayout;
+
+type HeatmapCell = {
+    /** Original index in the Explanation, before Sample ordering. */
+    sampleIndex: number;
+    /** Full-precision SHAP value represented by this cell. */
+    value: number;
+    /** Value after clipping to the shared symmetric colour domain. */
+    colorValue: number;
+    color: string;
+};
+type HeatmapColumn = {
+    sampleIndex: number;
+    /** The record UUID: the key for click-through, never shown to a person. */
+    sampleId?: string;
+    /** What a person reads for this Sample, when the payload carries labels. */
+    sampleLabel?: string;
+    /** Sum of all SHAP values for this Sample. */
+    total: number;
+};
+type HeatmapRow = {
+    label: string;
+    featureIndex: number | null;
+    isOtherRow: boolean;
+    importance: number;
+    /** Importance divided by the largest displayed-row importance. */
+    sideBarValue: number;
+    cells: HeatmapCell[];
+};
+type HeatmapRows = {
+    /** Header of the uploaded column the labels came from, when it had one. */
+    sampleLabelColumn?: string;
+    /** Feature rows in top-to-bottom display order. */
+    rows: HeatmapRow[];
+    /** Sample columns in descending total-attribution order. */
+    columns: HeatmapColumn[];
+    /** Sample totals in the same order as columns. */
+    fxLine: number[];
+    vmin: number;
+    vmax: number;
+    collapsedCount: number;
+};
+type HeatmapLayoutOptions = {
+    width: number;
+    rowHeight: number;
+    marginLeft: number;
+    marginRight: number;
+    /** Top of the matrix; the f(x) line occupies the space above it. */
+    marginTop: number;
+};
+type HeatmapCellGeometry = HeatmapCell & {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type HeatmapSideBarGeometry = {
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type HeatmapRowGeometry = Omit<HeatmapRow, "cells"> & {
+    centerY: number;
+    cells: HeatmapCellGeometry[];
+    sideBar: HeatmapSideBarGeometry;
+};
+type HeatmapColumnGeometry = HeatmapColumn & {
+    x: number;
+    centerX: number;
+    width: number;
+};
+type HeatmapLinePoint = {
+    sampleIndex: number;
+    sampleId?: string;
+    value: number;
+    x: number;
+    y: number;
+};
+type HeatmapAxisMark = {
+    value: number;
+    y: number;
+    label: string;
+};
+type HeatmapSpine = {
+    x: number;
+    y1: number;
+    y2: number;
+};
+/** An outward tick on the left edge, one per Feature row. */
+type HeatmapYTick = {
+    y: number;
+    x1: number;
+    x2: number;
+};
+type HeatmapLayout = {
+    sampleLabelColumn?: string;
+    rows: HeatmapRowGeometry[];
+    columns: HeatmapColumnGeometry[];
+    fxLine: HeatmapLinePoint[];
+    fxAxisMarks: HeatmapAxisMark[];
+    fxDomain: [number, number];
+    separatorY: number;
+    gridLeft: number;
+    gridRight: number;
+    gridTop: number;
+    plotBottom: number;
+    /**
+     * _heatmap.py:135 shows the left and right spines (and hides top and bottom),
+     * and :136 bounds them with set_bounds(n - row_height, -row_height). With
+     * row_height = 0.5 (:116) that is exactly the outer edge of the first and last
+     * row — so they frame the grid and stop short of the f(x) chart above it. The
+     * side bars are drawn with clip_on=False (:173), outside the right spine.
+     */
+    spines: {
+        left: HeatmapSpine;
+        right: HeatmapSpine;
+    };
+    /** yaxis.set_ticks_position("left") with tick_params(direction="out"), :134,:138. */
+    yTicks: HeatmapYTick[];
+    /** Ticks along the Sample axis, at the centre of each ticked column. */
+    xTicks: AxisTick[];
+    /** Always null: _heatmap.py:137 hides the bottom spine. */
+    xSpine: AxisSpine | null;
+    xTitle: AxisTitle;
+    plotWidth: number;
+    cellWidth: number;
+    height: number;
+};
+/** Computes the SHAP-compatible orderings, collapse, colours, line, and side bars in value space. */
+declare function heatmapRows(explanation: ParsedExplanation, maxDisplay: number, faithfulOtherRow: boolean, rowSort?: RowSort): HeatmapRows;
+/** Projects heatmap value-space rows into SVG geometry. */
+declare function heatmapLayout(valueRows: HeatmapRows, opts: HeatmapLayoutOptions): HeatmapLayout;
+
+export { type AggregatedExplanation, BEESWARM_MISSING_COLOR, BEESWARM_ROW_HEIGHT, type BarGeometry, type BarLayout, type BarLayoutOptions, type BeeswarmLayout, type BeeswarmLayoutOptions, type BeeswarmPoint, type BeeswarmPointGeometry, type BeeswarmRow, type BeeswarmRowGeometry, type BeeswarmRows, type ColormapName, DisplayRows, type GenusGrouping, type HeatmapAxisMark, type HeatmapCell, type HeatmapCellGeometry, type HeatmapColumn, type HeatmapColumnGeometry, type HeatmapLayout, type HeatmapLayoutOptions, type HeatmapLinePoint, type HeatmapRow, type HeatmapRowGeometry, type HeatmapRows, type HeatmapSideBarGeometry, type HeatmapSpine, type HeatmapYTick, NEGATIVE_COLOR, POSITIVE_COLOR, ParsedExplanation, type Point, RowSort, ValuePrecision, WATERFALL_BASE_LABEL_DY, WATERFALL_HEAD_LENGTH_PX, WATERFALL_TICK_LABEL_DY, type WaterfallArrowGeometry, type WaterfallAxisMark, type WaterfallConnector, type WaterfallLayout, type WaterfallLayoutOptions, type WaterfallRow, type WaterfallRows, type WaterfallSeparator, type WaterfallTick, type WaterfallValueLabel, aggregateByGenus, barLayout, beeswarmLayout, beeswarmRows, collapseToDisplay, genusOf, globalImportance, groupByGenus, groupExplanationByGenus, heatmapLayout, heatmapRows, orderFeatures, parseExplanation, sampleColormap, waterfallLayout, waterfallRows };

package/dist/index.js

@@ -0,0 +1,63 @@
+import {
+  BEESWARM_MISSING_COLOR,
+  BEESWARM_ROW_HEIGHT,
+  InvalidExplanationError,
+  NEGATIVE_COLOR,
+  POSITIVE_COLOR,
+  UnsupportedContractVersionError,
+  WATERFALL_BASE_LABEL_DY,
+  WATERFALL_HEAD_LENGTH_PX,
+  WATERFALL_TICK_LABEL_DY,
+  aggregateByGenus,
+  barLayout,
+  beeswarmLayout,
+  beeswarmRows,
+  collapseToDisplay,
+  formatFeatureLabel,
+  formatLevel,
+  formatShapValue,
+  genusOf,
+  globalImportance,
+  groupByGenus,
+  groupExplanationByGenus,
+  heatmapLayout,
+  heatmapRows,
+  orderFeatures,
+  parseExplanation,
+  sampleColormap,
+  sortDisplayRows,
+  waterfallLayout,
+  waterfallRows
+} from "./chunk-OXFKP5I3.js";
+export {
+  BEESWARM_MISSING_COLOR,
+  BEESWARM_ROW_HEIGHT,
+  InvalidExplanationError,
+  NEGATIVE_COLOR,
+  POSITIVE_COLOR,
+  UnsupportedContractVersionError,
+  WATERFALL_BASE_LABEL_DY,
+  WATERFALL_HEAD_LENGTH_PX,
+  WATERFALL_TICK_LABEL_DY,
+  aggregateByGenus,
+  barLayout,
+  beeswarmLayout,
+  beeswarmRows,
+  collapseToDisplay,
+  formatFeatureLabel,
+  formatLevel,
+  formatShapValue,
+  genusOf,
+  globalImportance,
+  groupByGenus,
+  groupExplanationByGenus,
+  heatmapLayout,
+  heatmapRows,
+  orderFeatures,
+  parseExplanation,
+  sampleColormap,
+  sortDisplayRows,
+  waterfallLayout,
+  waterfallRows
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}