@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/mlcharts/AttentionHeatmap.js

@@ -0,0 +1,329 @@
+import { ChartFamily, ColorScale, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { MatrixChart } from "../matrix/MatrixChart.js";
+import { MatrixGlyph, MatrixMarginal } from "../matrix/matrixEnums.js";
+import { AttentionGrid } from "./AttentionGrid.js";
+import { AttentionModel } from "./AttentionModel.js";
+import { AttentionSamples } from "./AttentionSamples.js";
+import { WideLabel } from "./WideLabel.js";
+import { scaleLinear } from "d3";
+// src/charts/mlcharts/AttentionHeatmap.ts
+var AttentionHeadView = /* @__PURE__ */ function(AttentionHeadView) {
+	AttentionHeadView["Mean"] = "mean-of-heads";
+	AttentionHeadView["SmallMultiples"] = "small-multiples";
+	return AttentionHeadView;
+}({});
+var AttentionAspect = /* @__PURE__ */ function(AttentionAspect) {
+	AttentionAspect["Square"] = "square-cells";
+	AttentionAspect["Fit"] = "fit";
+	return AttentionAspect;
+}({});
+var NOTE_SPACE = 16;
+var COVERAGE_GUTTER = 52;
+var PEAK = 4;
+var ROOM = 36;
+var TOLERANCE = .01;
+/**
+* Soft alignment between two token sequences, as in Bahdanau, Cho & Bengio (2015) and the scaled
+* dot-product attention of Vaswani et al. (2017). Rows are target tokens (queries), columns are source
+* tokens (keys), so each row is one softmax and should sum to 1. Weights are drawn as given: `check()`
+* and a note under the plot report what is off, nothing is renormalised. Tokens keep sequence order.
+* Coverage is the sum of a source token's attention over all targets (Tu et al., 2016).
+*/
+var AttentionHeatmap = class extends MatrixChart {
+	static meta = {
+		id: "attention-heatmap",
+		name: "Attention heatmap",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Matrix,
+		description: "Shows how much each target token attends to each source token, per head or averaged, to inspect what a sequence model looks at.",
+		tags: [
+			"attention",
+			"transformer",
+			"alignment",
+			"multi-head",
+			"machine learning",
+			"nlp"
+		],
+		sample: (seed) => AttentionSamples.crossAttention(seed),
+		variants: {
+			headView: ["mean-of-heads", "small-multiples"],
+			glyph: [MatrixGlyph.Tile, MatrixGlyph.Circle],
+			aspect: ["square-cells", "fit"],
+			marginals: [
+				MatrixMarginal.None,
+				MatrixMarginal.Rows,
+				MatrixMarginal.Columns,
+				MatrixMarginal.Both
+			],
+			alignment: [false, true],
+			cellValues: [false, true]
+		},
+		valid: (v) => !(v.headView === "small-multiples" && (v.marginals !== MatrixMarginal.None || v.cellValues)) && !(v.cellValues && (v.alignment || v.glyph !== MatrixGlyph.Tile))
+	};
+	#panels = 0;
+	defaults() {
+		return {
+			...super.defaults(),
+			source: "source",
+			target: "target",
+			weight: "weight",
+			head: "head",
+			sourceIndex: "sourceIndex",
+			targetIndex: "targetIndex",
+			headView: "mean-of-heads",
+			glyph: MatrixGlyph.Tile,
+			aspect: "square-cells",
+			marginals: MatrixMarginal.None,
+			alignment: false,
+			cellValues: false,
+			colorScale: ColorScale.Sequential,
+			sumTolerance: TOLERANCE
+		};
+	}
+	get attention() {
+		return AttentionModel.from(this.options.data, this.options);
+	}
+	get model() {
+		return this.attention.pooled;
+	}
+	get blank() {
+		return this.attention.empty;
+	}
+	/** Whether each row is a distribution, across every head. Reports only: the weights are never changed. */
+	check() {
+		const { sumTolerance } = this.options;
+		return this.attention.check(sumTolerance >= 0 ? sumTolerance : TOLERANCE);
+	}
+	table() {
+		const { heads } = this.attention;
+		return {
+			columns: [
+				"head",
+				"targetIndex",
+				"target",
+				"sourceIndex",
+				"source",
+				"weight"
+			],
+			rows: heads.flatMap(({ name, model }) => model.cells.map((cell) => [
+				name,
+				cell.r,
+				cell.row,
+				cell.c,
+				cell.column,
+				cell.value
+			]))
+		};
+	}
+	views(attention) {
+		const { headView, focusHead } = this.options, { heads } = attention;
+		if (headView === "small-multiples") return heads.map(({ name, model }) => ({
+			title: name,
+			model
+		}));
+		const focused = heads[focusHead ?? -1];
+		if (focused) return [{
+			title: focused.name,
+			model: focused.model
+		}];
+		return [{
+			title: heads.length > 1 ? `Mean of ${heads.length} heads` : heads[0].name,
+			model: attention.pooled
+		}];
+	}
+	domain(views) {
+		const low = Math.min(0, ...views.map(({ model }) => model.domain[0]));
+		const top = this.options.scaleMax ?? Math.max(...views.map(({ model }) => model.domain[1]));
+		return [low, top > low ? top : low + 1];
+	}
+	note({ checked, failing, tolerance, blankRows, missing, negative, irregular }) {
+		return [
+			failing.length && `Row sums off 1 by more than ${tolerance}: ${failing.length} of ${checked}`,
+			blankRows && `Blank rows: ${blankRows}`,
+			missing && `Missing weights: ${missing}`,
+			negative && `Negative weights: ${negative}`,
+			irregular && `Irregular entries: ${irregular}`
+		].filter(Boolean).join(" · ");
+	}
+	drawMatrix(ctx) {
+		const { aspect, marginals, cellValues, glyph } = this.options;
+		const attention = this.attention, views = this.views(attention);
+		if (views.length !== this.#panels) ctx.root.selectAll("*").remove();
+		this.#panels = views.length;
+		const note = this.note(this.check());
+		const onRight = marginals === MatrixMarginal.Rows || marginals === MatrixMarginal.Both;
+		const onTop = marginals === MatrixMarginal.Columns || marginals === MatrixMarginal.Both;
+		const layout = AttentionGrid.plan({
+			plot: ctx.plot,
+			rows: attention.target,
+			columns: attention.source,
+			panels: views.length,
+			square: aspect === "square-cells",
+			titled: views.some((view) => view.title),
+			right: onRight ? 44 : 0,
+			top: onTop ? 44 : 0,
+			bottom: 22 + (note ? NOTE_SPACE : 0),
+			minGutter: onTop ? COVERAGE_GUTTER : 0
+		});
+		const domain = this.domain(views), fill = this.heat(ctx, domain);
+		const hasTitles = views.length > 1;
+		this.tokens(ctx, attention, layout);
+		views.forEach((view, panel) => this.cells(ctx, view, layout.frames[panel], panel, domain, fill, hasTitles));
+		this.titles(ctx, views, layout);
+		this.peaks(ctx, views, layout, fill);
+		if (views.length === 1) {
+			this.rails(ctx, views[0].model, layout.frames[0], onRight, onTop);
+			const shown = cellValues && glyph === MatrixGlyph.Tile ? views[0].model.cells.filter((cell) => cell.value !== null) : [];
+			this.cellText(ctx, "cell-values", shown, layout.frames[0], (cell) => cell.value.toFixed(2), (cell) => this.inkOn(ctx, fill(cell.value)));
+		}
+		const rampAt = layout.bottom + 6;
+		this.ramp(ctx, domain, layout.frames[0].x, rampAt, (value) => value !== 0 && Math.abs(domain[1]) < 1 ? value.toPrecision(2) : Scales.format(value, Math.abs(domain[1])));
+		ctx.text(ctx.marks("check-note", "text", note ? [note] : []), 10.5, "secondary").attr("x", 0).attr("y", rampAt + 27).text((text) => WideLabel.fit(text, ctx.plot.width, 5.8));
+	}
+	cells(ctx, { title, model }, frame, panel, [, top], fill, multiple) {
+		const sums = model.rowTotals;
+		this.glyphs(ctx, `cells-${panel}`, model.cells, frame, {
+			glyph: this.options.glyph,
+			size: (cell) => Math.max(0, cell.value ?? 0) / top,
+			fill: (cell) => fill(cell.value),
+			tip: (cell) => ({
+				title: `${cell.row} → ${cell.column}`,
+				color: fill(cell.value),
+				rows: [
+					...multiple ? [["Head", title]] : [],
+					["Weight", cell.value === null ? "no data" : cell.value.toFixed(3)],
+					["Target position", cell.r + 1],
+					["Source position", cell.c + 1],
+					["Row sum", sums[cell.r].toFixed(3)]
+				]
+			})
+		});
+	}
+	tokens(ctx, { target, source }, { frames, across, gutter, header, flatHeader, below, rowStep, columnStep }) {
+		const rows = frames.flatMap((frame, panel) => panel % across ? [] : target.flatMap((token, r) => r % rowStep ? [] : [{
+			key: `${panel}/${r}`,
+			token,
+			x: frame.x - 6,
+			y: frame.cy(r)
+		}]));
+		ctx.text(ctx.marks("row-labels", "text", rows, (d) => d.key)).attr("text-anchor", "end").attr("dy", "0.32em").attr("x", (d) => d.x).attr("y", (d) => d.y).text((d) => WideLabel.fit(d.token, gutter - 6));
+		const columns = frames.slice(0, across).flatMap((frame, panel) => source.flatMap((token, c) => {
+			if (c % columnStep) return [];
+			const y = below ? frame.y + frame.height + (flatHeader ? 13 : 5) : frame.y - 5;
+			return [{
+				key: `${panel}/${c}`,
+				token,
+				transform: `translate(${frame.cx(c)},${y})${flatHeader ? "" : " rotate(-90)"}`
+			}];
+		}));
+		const anchor = flatHeader ? "middle" : below ? "end" : "start";
+		ctx.text(ctx.marks("column-labels", "text", columns, (d) => d.key)).attr("text-anchor", anchor).attr("dy", flatHeader ? null : "0.32em").attr("transform", (d) => d.transform).text((d) => WideLabel.fit(d.token, flatHeader ? frames[0].cw : header - 4));
+	}
+	titles(ctx, views, { frames, across, header, below }) {
+		const placed = views.flatMap(({ title }, panel) => {
+			const frame = frames[panel], lifted = panel < across ? below ? 44 : header : 0;
+			return title ? [{
+				panel,
+				title,
+				frame,
+				y: frame.y - lifted - 5
+			}] : [];
+		});
+		ctx.text(ctx.marks("panel-titles", "text", placed, (d) => d.panel), 11, "ink").attr("x", (d) => d.frame.x).attr("y", (d) => d.y).text((d) => WideLabel.fit(d.title, d.frame.width));
+	}
+	/** The hard alignment: each row's largest weight, as a dot on a tile or a full-size ring round a sized glyph. A flat row has no peak. */
+	peaks(ctx, views, { frames }, fill) {
+		const peaks = this.options.alignment ? views.flatMap(({ model }, panel) => model.values.flatMap((row, r) => {
+			const present = row.filter((value) => value !== null);
+			if (new Set(present).size < 2) return [];
+			const value = Math.max(...present);
+			return [{
+				key: `${panel}/${r}`,
+				frame: frames[panel],
+				r,
+				c: row.indexOf(value),
+				value
+			}];
+		})) : [];
+		const tile = this.options.glyph === MatrixGlyph.Tile;
+		const room = (frame) => Math.min(frame.cw, frame.ch) / 2 - 1;
+		const marks = ctx.marks("peaks", "circle", peaks, (d) => d.key).attr("pointer-events", "none").attr("fill", (d) => tile ? this.inkOn(ctx, fill(d.value)) : "none").attr("stroke", tile ? null : ctx.theme.ink).attr("stroke-width", tile ? null : 1.5);
+		ctx.set(marks, {
+			cx: (d) => d.frame.cx(d.c),
+			cy: (d) => d.frame.cy(d.r),
+			r: (d) => Math.max(1.5, tile ? Math.min(PEAK, room(d.frame)) : room(d.frame))
+		}, { r: 0 });
+	}
+	/** Bars from zero, with a tick at 1 so a row sum or a full share of coverage can be read against it. */
+	rails(ctx, model, frame, onRight, onTop) {
+		const scale = (totals) => scaleLinear([Math.min(0, ...totals), Math.max(1, ...totals)], [0, ROOM]);
+		const format = (value) => value.toFixed(3);
+		const rowTotals = onRight ? model.rowTotals : [], across = scale(rowTotals), left = frame.x + frame.width + 6, thick = Math.max(1, Math.min(10, frame.ch - 2));
+		const rowBars = ctx.marks("row-rail", "rect", rowTotals.map((total, index) => ({
+			total,
+			index
+		})), (d) => d.index).attr("fill", ctx.palette.sequential(.62)).attr("rx", 2);
+		ctx.set(rowBars, {
+			x: (d) => left + Math.min(across(0), across(d.total)),
+			y: (d) => frame.cy(d.index) - thick / 2,
+			width: (d) => Math.abs(across(d.total) - across(0)),
+			height: thick
+		}, {
+			x: left + across(0),
+			y: (d) => frame.cy(d.index) - thick / 2,
+			width: 0,
+			height: thick
+		});
+		ctx.hover(rowBars, (d) => ({
+			title: model.rows[d.index],
+			rows: [["Row sum", format(d.total)]]
+		}));
+		const columnTotals = onTop ? model.columnTotals : [], up = scale(columnTotals), base = frame.y - 6, wide = Math.max(1, Math.min(10, frame.cw - 2));
+		const columnBars = ctx.marks("column-rail", "rect", columnTotals.map((total, index) => ({
+			total,
+			index
+		})), (d) => d.index).attr("fill", ctx.palette.sequential(.62)).attr("rx", 2);
+		ctx.set(columnBars, {
+			x: (d) => frame.cx(d.index) - wide / 2,
+			y: (d) => base - Math.max(up(0), up(d.total)),
+			width: wide,
+			height: (d) => Math.abs(up(d.total) - up(0))
+		}, {
+			x: (d) => frame.cx(d.index) - wide / 2,
+			y: base - up(0),
+			width: wide,
+			height: 0
+		});
+		ctx.hover(columnBars, (d) => ({
+			title: model.columns[d.index],
+			rows: [["Coverage", format(d.total)]]
+		}));
+		const ticks = [...onRight ? [{
+			key: "row",
+			x1: left + across(1),
+			x2: left + across(1),
+			y1: frame.y,
+			y2: frame.y + frame.height
+		}] : [], ...onTop ? [{
+			key: "column",
+			x1: frame.x,
+			x2: frame.x + frame.width,
+			y1: base - up(1),
+			y2: base - up(1)
+		}] : []];
+		ctx.marks("rail-ticks", "line", ticks, (d) => d.key).attr("stroke", ctx.theme.axis).attr("stroke-width", 1).attr("x1", (d) => d.x1).attr("x2", (d) => d.x2).attr("y1", (d) => d.y1).attr("y2", (d) => d.y2);
+		const titles = [...onRight ? [{
+			text: "Row sum",
+			x: left,
+			anchor: "start"
+		}] : [], ...onTop ? [{
+			text: "Coverage",
+			x: frame.x - 6,
+			anchor: "end"
+		}] : []];
+		ctx.text(ctx.marks("rail-titles", "text", titles, (d) => d.text), 10.5, "muted").attr("x", (d) => d.x).attr("y", base).attr("text-anchor", (d) => d.anchor).text((d) => d.text);
+	}
+};
+export { AttentionAspect, AttentionHeadView, AttentionHeatmap };

package/dist/charts/mlcharts/AttentionModel.js

@@ -0,0 +1,132 @@
+import { MatrixModel } from "../matrix/MatrixModel.js";
+import { sum } from "d3";
+// src/charts/mlcharts/AttentionModel.ts
+var token = (value) => value === null || value === void 0 ? "" : String(value);
+var finite = (value) => value !== null && value !== void 0 && value !== "" && Number.isFinite(+value);
+/** Attention weights per head on one pair of token axes. Rows are targets (queries) and columns are sources (keys). */
+var AttentionModel = class AttentionModel {
+	source;
+	target;
+	heads;
+	irregular;
+	constructor(source, target, heads, irregular) {
+		this.source = source;
+		this.target = target;
+		this.heads = heads;
+		this.irregular = irregular;
+	}
+	static from(data, fields = {}) {
+		if (!data || typeof data !== "object") return AttentionModel.grids({
+			source: [],
+			target: [],
+			heads: []
+		});
+		if (Array.isArray(data)) return AttentionModel.long(data, fields);
+		if ("heads" in data) return AttentionModel.grids(data);
+		const { rows = [], columns = [], values = [] } = data;
+		return AttentionModel.grids({
+			source: columns,
+			target: rows,
+			heads: [{ weights: values }]
+		});
+	}
+	static grids({ source: sources, target: targets, heads }, extra = 0) {
+		const source = Array.isArray(sources) ? sources.map(token) : [], target = Array.isArray(targets) ? targets.map(token) : [];
+		const list = Array.isArray(heads) ? heads : [];
+		let irregular = extra;
+		const models = list.map((head, h) => {
+			const weights = Array.isArray(head?.weights) ? head.weights : [];
+			irregular += Math.abs(weights.length - target.length);
+			for (const row of weights.slice(0, target.length)) if (row?.length !== source.length) irregular++;
+			return {
+				name: head?.name ?? (list.length > 1 ? `Head ${h + 1}` : ""),
+				model: MatrixModel.from({
+					rows: target,
+					columns: source,
+					values: weights
+				})
+			};
+		});
+		return new AttentionModel(source, target, models, irregular);
+	}
+	static long(rows, { source = "source", target = "target", weight = "weight", head = "head", sourceIndex = "sourceIndex", targetIndex = "targetIndex" }) {
+		const placed = rows.filter((row) => row && row[source] != null && row[target] != null);
+		const sources = AttentionModel.axis(placed, source, sourceIndex), targets = AttentionModel.axis(placed, target, targetIndex);
+		const heads = /* @__PURE__ */ new Map(), seen = /* @__PURE__ */ new Set();
+		let irregular = rows.length - placed.length;
+		for (const row of placed) {
+			const name = token(row[head]);
+			if (!heads.has(name)) heads.set(name, targets.tokens.map(() => sources.tokens.map(() => null)));
+			const t = targets.at(row), s = sources.at(row), cell = `${name}/${t}/${s}`;
+			if (seen.has(cell)) irregular++;
+			seen.add(cell);
+			heads.get(name)[t][s] = row[weight];
+		}
+		return AttentionModel.grids({
+			source: sources.tokens,
+			target: targets.tokens,
+			heads: [...heads].map(([name, weights]) => ({
+				name,
+				weights
+			}))
+		}, irregular);
+	}
+	/** Token order along one axis: by position when every row has one, otherwise first seen. */
+	static axis(rows, text, position) {
+		const positional = rows.every((row) => finite(row[position]));
+		const keyOf = (row) => positional ? +row[position] : token(row[text]);
+		const slots = /* @__PURE__ */ new Map();
+		for (const row of rows) if (!slots.has(keyOf(row))) slots.set(keyOf(row), token(row[text]));
+		const keys = positional ? [...slots.keys()].sort((a, b) => +a - +b) : [...slots.keys()];
+		const index = new Map(keys.map((key, i) => [key, i]));
+		return {
+			tokens: keys.map((key) => slots.get(key)),
+			at: (row) => index.get(keyOf(row))
+		};
+	}
+	get empty() {
+		return !this.source.length || !this.target.length || !this.heads.length;
+	}
+	/** The cell-wise mean over heads, ignoring heads with no value at that cell. */
+	get pooled() {
+		if (this.heads.length === 1) return this.heads[0].model;
+		const values = this.target.map((_, t) => this.source.map((_, s) => {
+			const present = this.heads.map(({ model }) => model.values[t][s]).filter((value) => value !== null);
+			return present.length ? sum(present) / present.length : null;
+		}));
+		return new MatrixModel(this.target, this.source, values);
+	}
+	/** Checks each head's rows against the softmax property that a row sums to 1, without changing a weight. */
+	check(tolerance = .01) {
+		const failing = [];
+		let checked = 0, blankRows = 0, missing = 0, negative = 0;
+		for (const { name, model } of this.heads) model.values.forEach((row, r) => {
+			const present = row.filter((value) => value !== null);
+			missing += row.length - present.length;
+			negative += present.filter((value) => value < 0).length;
+			if (!present.length) {
+				blankRows++;
+				return;
+			}
+			checked++;
+			const total = sum(present);
+			if (Math.abs(total - 1) > tolerance) failing.push({
+				head: name,
+				row: r,
+				token: this.target[r],
+				sum: total
+			});
+		});
+		return {
+			tolerance,
+			checked,
+			failing,
+			blankRows,
+			missing,
+			negative,
+			irregular: this.irregular,
+			ok: !failing.length && !blankRows && !missing && !negative && !this.irregular
+		};
+	}
+};
+export { AttentionModel };

package/dist/charts/mlcharts/AttentionSamples.js

@@ -0,0 +1,82 @@
+import { SampleData } from "../../data/SampleData.js";
+// src/charts/mlcharts/AttentionSamples.ts
+var SOURCE = [
+	"the",
+	"cat",
+	"sat",
+	"on",
+	"the",
+	"mat",
+	".",
+	"</s>"
+];
+var TARGET = [
+	"le",
+	"chat",
+	"était",
+	"assis",
+	"sur",
+	"le",
+	"tapis",
+	".",
+	"</s>"
+];
+/** Which source position each target token translates. */
+var ALIGNED = [
+	0,
+	1,
+	2,
+	2,
+	3,
+	4,
+	5,
+	6,
+	7
+];
+/** Each head's focus on the source and how wide it spreads, as a Gaussian in logit space. */
+var HEADS = [
+	{
+		name: "Head 1",
+		focus: (aligned) => aligned,
+		spread: .6
+	},
+	{
+		name: "Head 2",
+		focus: (aligned) => aligned - 1,
+		spread: .8
+	},
+	{
+		name: "Head 3",
+		focus: (aligned) => aligned,
+		spread: 2.5
+	},
+	{
+		name: "Head 4",
+		focus: () => 1,
+		spread: 1.2
+	}
+];
+var NOISE = .3;
+/** SYNTHETIC. Invented weights for an invented sentence pair, not the output of any model. */
+var AttentionSamples = class AttentionSamples {
+	/** Softmax over noisy logits, so each row is a true probability distribution. */
+	static crossAttention(seed = 1) {
+		return {
+			source: SOURCE,
+			target: TARGET,
+			heads: HEADS.map(({ name, focus, spread }, h) => {
+				const { values } = SampleData.matrix(seed + h, TARGET.length, SOURCE.length);
+				return {
+					name,
+					weights: TARGET.map((_, t) => AttentionSamples.softmax(SOURCE.map((_, s) => -((s - focus(ALIGNED[t])) ** 2) / (2 * spread ** 2) + NOISE * values[t][s])))
+				};
+			})
+		};
+	}
+	static softmax(logits) {
+		const peak = Math.max(...logits), raised = logits.map((logit) => Math.exp(logit - peak));
+		const total = raised.reduce((sum, value) => sum + value, 0);
+		return raised.map((value) => value / total);
+	}
+};
+export { AttentionSamples };

package/dist/charts/mlcharts/CellNumber.js

@@ -0,0 +1,8 @@
+// src/charts/mlcharts/CellNumber.ts
+/** A table cell as a finite number, or `null` for blanks, text and dates. */
+var cellNumber = (cell) => {
+	if (typeof cell === "string" && !cell.trim()) return null;
+	const value = typeof cell === "number" || typeof cell === "string" ? Number(cell) : NaN;
+	return Number.isFinite(value) ? value : null;
+};
+export { cellNumber };

package/dist/charts/mlcharts/CurveDiagnosticSamples.js

@@ -0,0 +1,95 @@
+import { SampleData } from "../../data/SampleData.js";
+// src/charts/mlcharts/CurveDiagnosticSamples.ts
+var squared = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2;
+/** Synthetic demo data: nothing here is a real measurement. */
+var CurveDiagnosticSamples = class {
+	/** Standard normal draws from `SampleData`, since its generators are the only seeded source. */
+	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];
+	}
+	/**
+	* `{ epoch, run, split, value }`: a made-up loss from exponential decay, with validation drifting upward after a
+	* run-specific epoch so that it overfits. Not the output of any model.
+	*/
+	static trainingRuns(seed, epochs = 60, runs = 5) {
+		const z = this.#normals(seed, runs * (3 + epochs * 2));
+		return Array.from({ length: runs }, (_, r) => {
+			const run = `seed-${r + 1}`, tau = 9 + z() * .8, turn = 24 + z() * 3, level = .33 + z() * .025;
+			return Array.from({ length: epochs }, (_, i) => {
+				const epoch = i + 1, decay = 2.2 * Math.exp(-epoch / tau), noise = .25 + Math.exp(-epoch / 20);
+				const train = decay + .09 * Math.exp(-epoch / 60) + z() * .012 * noise;
+				const drift = 45e-5 * Math.max(0, epoch - turn) ** 2;
+				const validation = decay + level + drift + z() * .03 * noise;
+				return [{
+					epoch,
+					run,
+					split: "train",
+					value: +Math.max(.001, train).toFixed(4)
+				}, {
+					epoch,
+					run,
+					split: "validation",
+					value: +validation.toFixed(4)
+				}];
+			}).flat();
+		}).flat();
+	}
+	/** `{ k, inertia, silhouette }` from running k-means and the silhouette on `SampleData.points`, which is itself synthetic. */
+	static clusterSweep(seed, most = 10) {
+		const points = SampleData.points(seed, 160, 4).map((row, i) => [row.x, row.y - .8 * row.x + i % 2 * 42]);
+		return Array.from({ length: most }, (_, i) => {
+			const k = i + 1, { labels, inertia } = this.#kMeans(points, k);
+			return {
+				k,
+				inertia: +inertia.toFixed(1),
+				silhouette: k > 1 ? +this.#silhouette(points, labels, k).toFixed(4) : null
+			};
+		});
+	}
+	/** Lloyd's algorithm from farthest-first seeds, so that one seed always gives one answer. */
+	static #kMeans(points, k) {
+		const centers = [points[0]];
+		while (centers.length < k) {
+			const reach = points.map((point) => Math.min(...centers.map((center) => squared(point, center))));
+			centers.push(points[reach.indexOf(Math.max(...reach))]);
+		}
+		let labels = [];
+		for (let pass = 0; pass < 40; pass++) {
+			const next = points.map((point) => {
+				const reach = centers.map((center) => squared(point, center));
+				return reach.indexOf(Math.min(...reach));
+			});
+			if (next.every((label, i) => label === labels[i])) break;
+			labels = next;
+			centers.forEach((_, c) => {
+				const members = points.filter((__, i) => labels[i] === c);
+				if (members.length) centers[c] = [members.reduce((a, p) => a + p[0], 0) / members.length, members.reduce((a, p) => a + p[1], 0) / members.length];
+			});
+		}
+		return {
+			labels,
+			inertia: points.reduce((a, point, i) => a + squared(point, centers[labels[i]]), 0)
+		};
+	}
+	/** Mean silhouette width (Rousseeuw 1987); a point alone in its cluster scores zero. */
+	static #silhouette(points, labels, k) {
+		const widths = points.map((point, i) => {
+			const totals = new Array(k).fill(0), sizes = new Array(k).fill(0);
+			points.forEach((other, j) => {
+				if (j !== i) {
+					totals[labels[j]] += Math.sqrt(squared(point, other));
+					sizes[labels[j]]++;
+				}
+			});
+			const own = labels[i];
+			if (!sizes[own]) return 0;
+			const a = totals[own] / sizes[own];
+			const b = Math.min(...totals.flatMap((total, c) => c === own || !sizes[c] ? [] : [total / sizes[c]]));
+			return (b - a) / Math.max(a, b);
+		});
+		return widths.reduce((a, b) => a + b, 0) / widths.length;
+	}
+};
+export { CurveDiagnosticSamples };

package/dist/charts/mlcharts/CurvePickMark.js

@@ -0,0 +1,31 @@
+// src/charts/mlcharts/CurvePickMark.ts
+var CHAR = 6.2;
+var OFFSET = 7;
+/** Dashed rule, ringed dot and one label, shared by the charts that single out a point on a curve. */
+var CurvePickMark = class {
+	/** `labelY` is the text baseline, so the caller can keep the label off its curve. */
+	static draw(ctx, name, pick, labelY) {
+		const { width, height } = ctx.plot, picks = pick ? [pick] : [];
+		const rule = ctx.marks(`${name}-rule`, "line", picks).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1).attr("stroke-dasharray", "4 3");
+		ctx.set(rule, {
+			x1: (d) => d.x,
+			x2: (d) => d.x,
+			y1: 0,
+			y2: height
+		});
+		const dot = ctx.marks(`${name}-dot`, "circle", picks).attr("fill", ctx.theme.ink).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dot, {
+			cx: (d) => d.x,
+			cy: (d) => d.y,
+			r: 6
+		}, { r: 0 });
+		const reach = (d) => d.text.length * CHAR;
+		const flip = (d) => d.x + OFFSET + reach(d) > width;
+		const label = ctx.text(ctx.marks(`${name}-label`, "text", picks.filter((d) => reach(d) <= width)), 11, "ink").attr("text-anchor", (d) => flip(d) ? "end" : "start").attr("paint-order", "stroke").attr("stroke", ctx.theme.surface).attr("stroke-width", 3).text((d) => d.text);
+		ctx.set(label, {
+			x: (d) => flip(d) ? Math.max(reach(d), d.x - OFFSET) : d.x + OFFSET,
+			y: labelY
+		});
+	}
+};
+export { CurvePickMark };