@mstone6969/graph 0.1.0 → 0.2.0

package/dist/charts/mlcharts/ElbowPlot.js

@@ -0,0 +1,273 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { ZoomAxis } from "../../core/ChartViewport.js";
+import { TrendHover } from "../linesareas/TrendHover.js";
+import { cellNumber } from "./CellNumber.js";
+import { CurveDiagnosticSamples } from "./CurveDiagnosticSamples.js";
+import { ElbowMethod, SilhouetteView } from "./curveDiagnosticEnums.js";
+import { CurvePickMark } from "./CurvePickMark.js";
+import { DistinctTicks } from "./DistinctTicks.js";
+import { ElbowMath } from "./ElbowMath.js";
+import { WideLabel } from "./WideLabel.js";
+import { axisLeft, axisRight, extent, line, scaleLinear } from "d3";
+// src/charts/mlcharts/ElbowPlot.ts
+var PANEL_SHARE = .6;
+var PANEL_GAP = 20;
+var RIGHT = 62;
+var LEGEND_INSET = 64;
+var LEGEND_CHAR = 6.4;
+/** Keeps end dots off the axes, in units of k. */
+var K_PAD = .35;
+/** Tallest a rescaled trace reaches, leaving the top for the elbow label. */
+var TRACE_REACH = .85;
+var METHOD_NAME = {
+	[ElbowMethod.Kneedle]: "Kneedle",
+	[ElbowMethod.LMethod]: "L method",
+	[ElbowMethod.Chord]: "Chord distance",
+	[ElbowMethod.SecondDifference]: "Second difference"
+};
+var GUIDE_NAME = {
+	[ElbowMethod.Kneedle]: "Difference curve (rescaled)",
+	[ElbowMethod.LMethod]: "Two-line fit",
+	[ElbowMethod.Chord]: "Chord and distance",
+	[ElbowMethod.SecondDifference]: "Second difference (rescaled)"
+};
+var NO_GUIDE = {
+	index: null,
+	trace: [],
+	segments: []
+};
+var average = (values) => values.length ? values.reduce((a, b) => a + b, 0) / values.length : null;
+/**
+* Chooses a cluster count from inertia or another score by k. The elbow comes from a named method: Kneedle (Satopää et al.
+* 2011), the L method (Salvador and Chan 2004), the chord distance of Rosin (2001), or the largest second difference.
+* The silhouette (Rousseeuw 1987) is an independent second opinion on k. A curve with no bend gets no elbow: the elbow
+* is a heuristic, and an honest plot says so instead of always naming a k.
+*/
+var ElbowPlot = class extends CartesianChart {
+	static meta = {
+		id: "elbow-plot",
+		name: "Elbow plot",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots inertia or another score by number of clusters, marks the elbow found by a named method, and can compare it with the silhouette.",
+		tags: [
+			"machine learning",
+			"k-means",
+			"clustering",
+			"kneedle",
+			"silhouette",
+			"model selection"
+		],
+		sample: (seed) => CurveDiagnosticSamples.clusterSweep(seed),
+		variants: {
+			method: Object.values(ElbowMethod),
+			silhouetteView: Object.values(SilhouetteView)
+		}
+	};
+	#points = [];
+	#fit = NO_GUIDE;
+	defaults() {
+		return {
+			x: "k",
+			y: "inertia",
+			silhouette: "silhouette",
+			method: ElbowMethod.Kneedle,
+			sensitivity: 1,
+			silhouetteView: SilhouetteView.None,
+			guide: true,
+			xLabel: "Clusters (k)",
+			yLabel: "Inertia"
+		};
+	}
+	read() {
+		const { data, x, y, silhouette } = this.options;
+		const rows = /* @__PURE__ */ new Map();
+		for (const row of Array.isArray(data) ? data : []) {
+			const k = cellNumber(row?.[x]), score = cellNumber(row?.[y]);
+			if (k === null || score === null) continue;
+			const entry = rows.get(k) ?? rows.set(k, {
+				score: [],
+				silhouette: []
+			}).get(k);
+			entry.score.push(score);
+			const width = cellNumber(row[silhouette]);
+			if (width !== null) entry.silhouette.push(width);
+		}
+		return [...rows].sort(([a], [b]) => a - b).map(([k, entry]) => ({
+			k,
+			score: average(entry.score),
+			silhouette: average(entry.silhouette)
+		}));
+	}
+	/** The chosen view, or `None` when the data has no silhouette column. */
+	get view() {
+		const known = this.options.silhouetteView;
+		const { data, silhouette } = this.options;
+		return Array.isArray(data) && data.some((row) => cellNumber(row?.[silhouette]) !== null) ? known : SilhouetteView.None;
+	}
+	zoomAxes() {
+		return this.view === SilhouetteView.None ? ZoomAxis.XY : ZoomAxis.X;
+	}
+	plotMargin() {
+		return {
+			...super.plotMargin(),
+			...this.view === SilhouetteView.SecondAxis ? { right: RIGHT } : {}
+		};
+	}
+	xTicks() {
+		const [lo = 0, hi = 1] = extent(this.#points, (point) => point.k);
+		return lo === hi ? 2 : Math.min(7, Math.ceil(hi - lo));
+	}
+	tickFormat(scale) {
+		return DistinctTicks.format(scale, super.tickFormat(scale));
+	}
+	yTicks() {
+		return this.view === SilhouetteView.Panel ? 4 : 6;
+	}
+	legendItems() {
+		const shown = this.options.guide && (this.#fit.segments.length || this.#fit.trace.length);
+		const room = this.size.width - LEGEND_INSET;
+		return [...super.legendItems().map((item) => ({
+			...item,
+			label: WideLabel.fit(item.key, room, LEGEND_CHAR)
+		})), ...shown ? [{
+			key: GUIDE_NAME[this.options.method],
+			color: this.theme.inkMuted
+		}] : []];
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot;
+		const points = this.#points = this.read();
+		const fit = this.#fit = ElbowMath.fit(points, this.options.method, this.options.sensitivity);
+		const bottom = this.view === SilhouetteView.Panel ? Math.round(height * PANEL_SHARE) : height;
+		const guide = this.options.guide ? fit.segments.flatMap((segment) => [segment.y1, segment.y2]) : [];
+		let [left, right] = extent(points, (point) => point.k), [lo, hi] = extent([...points.map((point) => point.score), ...guide]);
+		if (left === void 0 || right === void 0) [left, right] = [0, 1];
+		if (left === right) [left, right] = [left - 1, right + 1];
+		if (lo === void 0 || hi === void 0) [lo, hi] = [0, 1];
+		if (lo === hi) {
+			const pad = Math.abs(lo) * .1 || 1;
+			[lo, hi] = [lo - pad, hi + pad];
+		}
+		return {
+			x: scaleLinear([left - K_PAD, right + K_PAD], [0, width]),
+			y: scaleLinear([lo, hi], [bottom, 0]).nice(this.yTicks())
+		};
+	}
+	/** Silhouette scale, with headroom on a shared plot so the peak label stays clear of the elbow label. */
+	silhouetteScale(ctx, values) {
+		const { height } = ctx.plot, panel = this.view === SilhouetteView.Panel;
+		let [lo = 0, hi = 1] = extent(values);
+		if (lo === hi) {
+			lo -= .1;
+			hi += .1;
+		}
+		const head = panel ? 0 : (hi - lo) * .4;
+		const range = panel ? [height, Math.round(height * PANEL_SHARE) + PANEL_GAP] : [height, 0];
+		return scaleLinear([lo, hi + head], range).nice(panel ? 3 : 5);
+	}
+	styleAxis(ctx, axis) {
+		axis.select(".domain").attr("stroke", "none");
+		axis.selectAll("text").attr("fill", ctx.theme.inkSecondary).attr("font-size", 11).attr("font-family", ctx.theme.fontFamily);
+	}
+	plotMarks(ctx, axes) {
+		const { method, guide } = this.options;
+		const { width, height } = ctx.plot;
+		const points = this.#points, fit = this.#fit, view = this.view;
+		const px = (k) => axes.x(k) ?? 0, py = (value) => axes.y(value) ?? 0;
+		const name = this.options.yLabel || "Score", ink = ctx.palette.color(name);
+		this.drawGuide(ctx, guide ? fit : NO_GUIDE, points, axes);
+		const curve = line().x((d) => px(d.k)).y((d) => py(d.score));
+		const path = ctx.marks("curve", "path", points.length ? [points] : []).attr("fill", "none").attr("stroke", ink).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-linecap", "round");
+		ctx.set(path, { d: (d) => curve(d) ?? "" });
+		ctx.drawOn(path);
+		const dots = ctx.marks("dots", "circle", points, (d) => d.k).attr("fill", ink).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => px(d.k),
+			cy: (d) => py(d.score),
+			r: 5
+		}, { r: 0 }, 20);
+		const silhouette = view === SilhouetteView.None ? null : this.drawSilhouette(ctx, points, px);
+		const elbow = fit.index === null ? null : points[fit.index];
+		const pick = elbow && {
+			x: px(elbow.k),
+			y: py(elbow.score),
+			text: `Elbow k = ${TrendHover.title(elbow.k)} · ${METHOD_NAME[method]}`
+		};
+		CurvePickMark.draw(ctx, "elbow", pick, 12);
+		ctx.text(ctx.marks("no-elbow", "text", points.length && !elbow ? [`No elbow found by ${METHOD_NAME[method]}`] : []), 11, "muted").attr("text-anchor", "end").attr("x", width - 2).attr("y", 12).text((d) => d).attr("paint-order", "stroke").attr("stroke", ctx.theme.surface).attr("stroke-width", 3);
+		const slices = points.map((point) => ({
+			x: px(point.k),
+			title: `k = ${TrendHover.title(point.k)}`,
+			rows: [[name, TrendHover.value(point.score)], ...view === SilhouetteView.None ? [] : [["Silhouette", TrendHover.value(point.silhouette)]]],
+			marks: [{
+				x: px(point.k),
+				y: py(point.score),
+				color: ink
+			}, ...silhouette && point.silhouette !== null ? [{
+				x: px(point.k),
+				y: silhouette(point.silhouette),
+				color: ctx.palette.color("Silhouette")
+			}] : []]
+		}));
+		TrendHover.attach(ctx, slices, width, height);
+	}
+	/** Traces have their own units, so they are stretched to the value axis, which the legend says. */
+	drawGuide(ctx, fit, points, { x, y }) {
+		const px = (k) => x(k) ?? 0, py = (value) => y(value) ?? 0;
+		const dashed = (selection) => selection.attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1.5).attr("stroke-dasharray", "6 4");
+		const lines = dashed(ctx.marks("guide-lines", "line", fit.segments));
+		ctx.set(lines, {
+			x1: (d) => px(d.x1),
+			y1: (d) => py(d.y1),
+			x2: (d) => px(d.x2),
+			y2: (d) => py(d.y2)
+		});
+		const rows = fit.segments.length ? [] : fit.trace.map((value, i) => ({
+			k: points[i].k,
+			value
+		}));
+		const [low = 0, high = 1] = extent(rows, (d) => d.value);
+		const [floor = 0, ceiling = 1] = y.domain();
+		const lift = (value) => floor + (high > low ? (value - low) / (high - low) : 0) * TRACE_REACH * (ceiling - floor);
+		const trace = line().defined((d) => d.value !== null).x((d) => px(d.k)).y((d) => py(lift(d.value)));
+		const path = dashed(ctx.marks("guide-trace", "path", rows.length ? [rows] : [])).attr("fill", "none");
+		ctx.set(path, { d: (d) => trace(d) ?? "" });
+	}
+	/** Draws the silhouette on its own axis and returns that axis, for the hover dots. */
+	drawSilhouette(ctx, points, px) {
+		const { width, height } = ctx.plot, panel = this.view === SilhouetteView.Panel;
+		const known = points.filter((point) => point.silhouette !== null);
+		const scale = this.silhouetteScale(ctx, known.map((point) => point.silhouette));
+		const ink = ctx.palette.color("Silhouette");
+		const axis = (panel ? axisLeft(scale) : axisRight(scale)).ticks(5).tickSize(0).tickFormat((value) => (+value).toFixed(2));
+		if (panel && Math.abs(scale.range()[0] - scale.range()[1]) < 60) axis.tickValues(scale.domain());
+		this.styleAxis(ctx, ctx.group("axis-silhouette").attr("transform", panel ? "" : `translate(${width},0)`).call(axis));
+		const top = scale.range()[1];
+		const title = ctx.text(ctx.marks("silhouette-title", "text", ["Silhouette"]), 11, "secondary").text((d) => d);
+		if (panel) title.attr("text-anchor", "end").attr("transform", `translate(${width - 2},${top + 2})`);
+		else title.attr("text-anchor", "middle").attr("transform", `rotate(90) translate(${height / 2},${-width - 48})`);
+		const curve = line().x((d) => px(d.k)).y((d) => scale(d.silhouette));
+		const path = ctx.marks("silhouette", "path", known.length ? [known] : []).attr("fill", "none").attr("stroke", ink).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-linecap", "round");
+		ctx.set(path, { d: (d) => curve(d) ?? "" });
+		ctx.drawOn(path);
+		const dots = ctx.marks("silhouette-dots", "circle", known, (d) => d.k).attr("fill", ink).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => px(d.k),
+			cy: (d) => scale(d.silhouette),
+			r: 5
+		}, { r: 0 }, 20);
+		const peak = known.reduce((top, point) => !top || point.silhouette > top.silhouette ? point : top, null);
+		const text = peak && `Peak k = ${TrendHover.title(peak.k)}`;
+		const reach = (text?.length ?? 0) * 6.2 / 2;
+		const note = ctx.text(ctx.marks("silhouette-peak", "text", peak ? [peak] : []), 11, "ink").attr("text-anchor", "middle").attr("paint-order", "stroke").attr("stroke", ctx.theme.surface).attr("stroke-width", 3).text(text ?? "");
+		ctx.set(note, {
+			x: (d) => Math.max(reach, Math.min(width - reach, px(d.k))),
+			y: (d) => scale(d.silhouette) - 11
+		});
+		return scale;
+	}
+};
+export { ElbowPlot };

package/dist/charts/mlcharts/ExplainabilitySamples.js

@@ -0,0 +1,70 @@
+import { SampleData } from "../../data/SampleData.js";
+// src/charts/mlcharts/ExplainabilitySamples.ts
+/** Feature names and the sign of their synthetic coefficient, strongest first. */
+var FEATURES = [
+	["debt_to_income", 1],
+	["annual_income", -1],
+	["credit_utilization", 1],
+	["months_since_last_delinquency", -1],
+	["loan_amount", 1],
+	["employment_length", -1],
+	["open_accounts", 1],
+	["recent_inquiries", 1],
+	["mortgage_accounts", -1],
+	["revolving_balance", 1],
+	["total_accounts", -1],
+	["installment", 1],
+	["home_ownership", -1],
+	["loan_term", 1],
+	["public_records", 1],
+	["savings_balance", -1],
+	["age", -1],
+	["region_index", 1],
+	["verified_income", -1],
+	["card_count", 1],
+	["autopay_enrolled", -1],
+	["joint_application", -1],
+	["purpose_code", 1],
+	["application_hour", 1]
+];
+var CURVES = 36;
+var GRID = 28;
+var RESPONSE_MIDPOINT = 50;
+var RESPONSE_WIDTH = 14;
+/** Synthetic model output for demos. Nothing here was measured or came from a fitted model. */
+var ExplainabilitySamples = class {
+	static #normals(seed, count) {
+		const values = SampleData.distribution(seed, count, 1).map((row) => (row.value - 40) / 8);
+		let i = 0;
+		return () => values[i++ % values.length];
+	}
+	/** Synthetic standardised coefficients: `{ feature, importance, error }`, a power-law tail with noise. */
+	static importance(seed) {
+		const z = this.#normals(seed, FEATURES.length * 2);
+		return FEATURES.map(([feature, sign], rank) => {
+			const size = .9 / (rank + 1) ** .85 * (1 + z() * .08);
+			return {
+				feature,
+				importance: +(sign * size).toFixed(4),
+				error: +(size * .12 + .01 * Math.abs(z())).toFixed(4)
+			};
+		});
+	}
+	/** Synthetic ICE sweeps: `{ instance, x, prediction, observed }`, one saturating response per instance, whose slope flips for some. */
+	static iceCurves(seed) {
+		const z = this.#normals(seed, 72);
+		const observed = SampleData.points(seed, CURVES).map((row) => row.x);
+		const low = Math.min(...observed), high = Math.max(...observed);
+		const grid = Array.from({ length: GRID }, (_, i) => +(low + (high - low) * i / 27).toFixed(2));
+		return observed.flatMap((at, i) => {
+			const level = z(), slope = z();
+			return grid.map((x) => ({
+				instance: `row ${i + 1}`,
+				x,
+				observed: at,
+				prediction: +(.45 + .1 * level + (.2 + .22 * slope) * Math.tanh((x - RESPONSE_MIDPOINT) / RESPONSE_WIDTH)).toFixed(4)
+			}));
+		});
+	}
+};
+export { ExplainabilitySamples };

package/dist/charts/mlcharts/FeatureImportanceChart.js

@@ -0,0 +1,150 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { BandChart } from "../bars/BandChart.js";
+import { ExplainabilitySamples } from "./ExplainabilitySamples.js";
+import { FeatureImportanceOther, FeatureImportanceSign, ImportanceRanking } from "./ImportanceRanking.js";
+import { WideLabel } from "./WideLabel.js";
+import { format, max } from "d3";
+// src/charts/mlcharts/FeatureImportanceChart.ts
+var CAP = 4;
+/** Widest band label, in px: 14 Latin characters. */
+var LABEL_ROOM = 86.8;
+var LABEL_LINE = 13;
+var TICK_GAP = 12;
+var TITLE_GAP = 18;
+var figure = format(".3~g");
+/**
+* Ranked feature scores from a fitted model: impurity importance (Breiman 2001), permutation
+* importance (Fisher et al. 2019), mean |SHAP| (Lundberg & Lee 2017) or coefficients, which need
+* standardised inputs for their sizes to compare. Use `FeatureImportanceSign.Value` to rank
+* permutation scores, where a negative is noise rather than an effect. A summed Other row follows `shap.plots.bar`; it is only meaningful where the scores add up.
+*/
+var FeatureImportanceChart = class extends BandChart {
+	static meta = {
+		id: "feature-importance",
+		name: "Feature importance",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Ranks the features of a fitted model by importance or coefficient, with uncertainty whiskers and the tail folded into an Other row.",
+		tags: [
+			"machine learning",
+			"explainability",
+			"permutation importance",
+			"shap",
+			"coefficients"
+		],
+		sample: (seed) => ExplainabilitySamples.importance(seed),
+		variants: {
+			sign: Object.values(FeatureImportanceSign),
+			whiskers: [true, false],
+			other: Object.values(FeatureImportanceOther)
+		}
+	};
+	defaults() {
+		return {
+			x: "feature",
+			y: "importance",
+			error: "error",
+			low: "low",
+			high: "high",
+			orientation: Orientation.Horizontal,
+			sign: FeatureImportanceSign.Signed,
+			whiskers: true,
+			top: 10,
+			other: FeatureImportanceOther.Sum
+		};
+	}
+	get bars() {
+		const { data, x, y, error, low, high, sign, other, top } = this.options;
+		return ImportanceRanking.rank(Array.isArray(data) ? data : [], {
+			feature: x,
+			value: y,
+			error,
+			low,
+			high
+		}, {
+			sign,
+			other,
+			top
+		});
+	}
+	/** Scores that are all positive have no polarity to show, so they take one identity colour. */
+	get signColoured() {
+		return this.options.sign !== FeatureImportanceSign.Value && this.bars.some((bar) => bar.polarity < 0);
+	}
+	bandNames() {
+		return [...new Set(this.bars.map((bar) => bar.band))];
+	}
+	valueExtent() {
+		const { whiskers } = this.options;
+		const reach = this.bars.flatMap((bar) => [bar.value, ...whiskers ? [bar.low ?? 0, bar.high ?? 0] : []]);
+		return [Math.min(0, ...reach), Math.max(0, ...reach)];
+	}
+	/** Room for the widest label: core's gutter counts characters, which is too few for CJK. */
+	plotMargin() {
+		const base = super.plotMargin();
+		if (this.vertical) return base;
+		const widest = max(this.bandNames(), (name) => WideLabel.width(WideLabel.fit(name, LABEL_ROOM))) ?? 0;
+		return {
+			...base,
+			left: Math.max(base.left, Math.ceil(widest) + TICK_GAP + (this.options.yLabel ? TITLE_GAP : 0))
+		};
+	}
+	tickFormat(scale) {
+		const names = scale.domain?.() ?? [];
+		if (!this.vertical && typeof names[0] === "string") {
+			const every = Math.ceil(LABEL_LINE / Math.max(1, scale.step()));
+			return (name) => names.indexOf(name) % every ? "" : WideLabel.fit(String(name), LABEL_ROOM);
+		}
+		const base = super.tickFormat(scale);
+		if (!base || !("ticks" in scale)) return base;
+		const fine = scale;
+		return (max(fine.domain(), Math.abs) ?? 0) < 10 ? (value) => fine.tickFormat(this.xTicks())(+value) : base;
+	}
+	legendItems() {
+		if (!this.signColoured) return super.legendItems();
+		const present = new Set(this.bars.map((bar) => bar.polarity));
+		return [{
+			key: "Positive",
+			color: this.palette.diverging(1)
+		}, {
+			key: "Negative",
+			color: this.palette.diverging(-1)
+		}].filter((_, i) => present.has(i ? -1 : 1));
+	}
+	fill(ctx, bar) {
+		if (bar.folded && (!bar.polarity || !this.signColoured)) return ctx.theme.inkMuted;
+		return this.signColoured ? ctx.palette.diverging(bar.polarity) : ctx.palette.color(this.options.y);
+	}
+	drawBands(ctx, frame) {
+		const bars = this.bars;
+		const band = (d) => frame.band(d.band) ?? 0;
+		const shape = (d, to) => frame.bar(band(d), frame.thick, 0, to, 4);
+		const marks = ctx.marks("bars", "path", bars, (d) => d.key).attr("fill", (d) => this.fill(ctx, d));
+		ctx.set(marks, { d: (d) => shape(d, d.value) }, { d: (d) => shape(d, 0) }, 12);
+		ctx.hover(marks, (d) => ({
+			title: d.band,
+			color: this.fill(ctx, d),
+			rows: this.tipRows(d)
+		}));
+		this.drawWhiskers(ctx, frame, this.options.whiskers ? bars.filter((d) => d.low !== null) : []);
+	}
+	tipRows(d) {
+		if (d.folded) return [[this.options.other === FeatureImportanceOther.Mean ? "Mean" : "Sum", figure(d.source)], ["Features", d.folded]];
+		return [["Value", figure(d.source)], ...d.low === null ? [] : [["Interval", `${figure(d.low)} to ${figure(d.high)}`]]];
+	}
+	drawWhiskers(ctx, frame, bars) {
+		const cap = Math.min(CAP, frame.thick / 3);
+		const tick = (d, value) => {
+			const at = frame.center(d.band), { x1, y1, x2, y2 } = frame.rule(value, at - cap, at + cap);
+			return `M${x1},${y1}L${x2},${y2}`;
+		};
+		const stem = (d, low, high) => {
+			const { x1, y1, x2, y2 } = frame.stem(frame.center(d.band), low, high);
+			return `M${x1},${y1}L${x2},${y2}${tick(d, low)}${tick(d, high)}`;
+		};
+		const whiskers = ctx.marks("whiskers", "path", bars, (d) => d.key).attr("fill", "none").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("pointer-events", "none");
+		ctx.set(whiskers, { d: (d) => stem(d, d.low, d.high) }, { d: (d) => stem(d, d.value, d.value) }, 12);
+	}
+};
+export { FeatureImportanceChart };

package/dist/charts/mlcharts/ImportanceRanking.js

@@ -0,0 +1,98 @@
+import { BarRows } from "../bars/BarRows.js";
+import { group, mean, sum } from "d3";
+// src/charts/mlcharts/ImportanceRanking.ts
+/** How a signed score maps to bars and rank. */
+var FeatureImportanceSign = /* @__PURE__ */ function(FeatureImportanceSign) {
+	/** Ranked by size, drawn either side of zero: the usual read of coefficients. */
+	FeatureImportanceSign["Signed"] = "signed";
+	/** Ranked high to low as supplied, so a negative permutation importance stays below zero. */
+	FeatureImportanceSign["Value"] = "value";
+	/** Ranked and drawn by size, with the sign kept as colour. */
+	FeatureImportanceSign["Magnitude"] = "magnitude";
+	return FeatureImportanceSign;
+}({});
+/** What the row for features past `top` shows. */
+var FeatureImportanceOther = /* @__PURE__ */ function(FeatureImportanceOther) {
+	FeatureImportanceOther["Sum"] = "sum";
+	FeatureImportanceOther["Mean"] = "mean";
+	FeatureImportanceOther["None"] = "none";
+	return FeatureImportanceOther;
+}({});
+/** Turns rows into ranked bars: repeated features merged, the tail folded into an Other row. */
+var ImportanceRanking = class {
+	/**
+	* Repeated rows for a feature, as from CV folds or permutation repeats, are averaged. Without
+	* interval columns they get the population SD across repeats, as scikit-learn's `importances_std`.
+	*/
+	static merge(rows, columns) {
+		const named = (row) => row?.[columns.feature] !== null && row?.[columns.feature] !== void 0 && row[columns.feature] !== "";
+		const usable = rows.filter((row) => named(row) && BarRows.number(row[columns.value]) !== null);
+		return [...group(usable, (row) => String(row[columns.feature]))].map(([feature, set]) => {
+			const values = set.map((row) => BarRows.number(row[columns.value]));
+			const value = mean(values);
+			const low = mean(set, (row) => BarRows.number(row[columns.low])), high = mean(set, (row) => BarRows.number(row[columns.high]));
+			if (low !== void 0 && high !== void 0) return {
+				feature,
+				value,
+				low: Math.min(low, high),
+				high: Math.max(low, high)
+			};
+			const reach = mean(set, (row) => {
+				const cell = BarRows.number(row[columns.error]);
+				return cell === null ? null : Math.abs(cell);
+			}) ?? (values.length > 1 ? Math.sqrt(mean(values, (v) => (v - value) ** 2)) : null);
+			return {
+				feature,
+				value,
+				low: reach === null ? null : value - reach,
+				high: reach === null ? null : value + reach
+			};
+		});
+	}
+	static rank(rows, columns, { sign, other, top }) {
+		const size = sign === "value" ? (d) => d.value : (d) => Math.abs(d.value);
+		const sorted = this.merge(rows, columns).sort((a, b) => size(b) - size(a));
+		const limit = top >= 1 ? Math.floor(top) : 1;
+		const cut = other !== "none" && sorted.length === limit + 1 ? sorted.length : limit;
+		return [...sorted.slice(0, cut).map((d) => this.bar(d, sign)), ...this.folded(sorted.slice(cut), sign, other)];
+	}
+	static bar({ feature, value, low, high }, sign) {
+		const entry = {
+			key: `feature ${feature}`,
+			band: feature,
+			source: value,
+			polarity: Math.sign(value),
+			folded: 0
+		};
+		if (sign !== "magnitude" || low === null || high === null) return {
+			...entry,
+			value: sign === "magnitude" ? Math.abs(value) : value,
+			low,
+			high
+		};
+		const near = low <= 0 && high >= 0 ? 0 : Math.min(Math.abs(low), Math.abs(high));
+		return {
+			...entry,
+			value: Math.abs(value),
+			low: near,
+			high: Math.max(Math.abs(low), Math.abs(high))
+		};
+	}
+	/** No interval here: the spread of a sum needs covariances the rows do not hold. A signed Other splits into its two sides. */
+	static folded(rest, sign, other) {
+		if (!rest.length || other === "none") return [];
+		const band = `Other (${rest.length})`, scale = other === "mean" ? 1 / rest.length : 1;
+		const take = (pick) => sum(rest, pick) * scale;
+		return (sign === "signed" ? [take((d) => Math.max(0, d.value)), take((d) => Math.min(0, d.value))].filter(Boolean) : [take(sign === "magnitude" ? (d) => Math.abs(d.value) : (d) => d.value)]).map((value) => ({
+			key: `other ${Math.sign(value)}`,
+			band,
+			value,
+			source: value,
+			polarity: sign === "signed" ? Math.sign(value) : 0,
+			low: null,
+			high: null,
+			folded: rest.length
+		}));
+	}
+};
+export { FeatureImportanceOther, FeatureImportanceSign, ImportanceRanking };