@mstone6969/graph 0.1.0 → 0.2.0

package/dist/charts/mlcharts/DecisionBoundaryChart.js

@@ -0,0 +1,316 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FieldContours } from "../density/FieldContours.js";
+import { DistinctTicks } from "./DistinctTicks.js";
+import { DecisionSamples } from "./DecisionSamples.js";
+import { DecisionSurface } from "./DecisionSurface.js";
+import { extent, scaleLinear, symbol, symbolCircle, symbolCross } from "d3";
+// src/charts/mlcharts/DecisionBoundaryChart.ts
+/** How the feature plane shows the model. `Confidence` deepens each region with the margin; `Cells` shows the evaluated grid unsmoothed. */
+var DecisionFill = /* @__PURE__ */ function(DecisionFill) {
+	DecisionFill["Regions"] = "regions";
+	DecisionFill["Confidence"] = "confidence";
+	DecisionFill["Cells"] = "cells";
+	DecisionFill["None"] = "no-fill";
+	return DecisionFill;
+}({});
+/** Which observations sit on the surface. */
+var DecisionOverlay = /* @__PURE__ */ function(DecisionOverlay) {
+	DecisionOverlay["All"] = "all-points";
+	DecisionOverlay["Errors"] = "errors-only";
+	DecisionOverlay["None"] = "no-points";
+	return DecisionOverlay;
+}({});
+var MARGINS = [
+	.25,
+	.5,
+	.75
+];
+var REGION_TINT = .24;
+var BAND_TINT = .13;
+var LABEL_ROOM = 24;
+var dot = symbol(symbolCircle, 64)();
+var cross = symbol(symbolCross, 130)();
+var text = (value) => value === null || value === void 0 || value === "" ? null : String(value);
+var number = (value) => value === null || value === void 0 || value === "" ? NaN : Number(value);
+var percent = (value) => `${(value * 100).toFixed(1)}%`;
+/**
+* Draws what a classifier decides across two features: regions, the boundary where the top two classes tie, and points marked right or wrong.
+* Same reading as Hastie, Tibshirani & Friedman, ESL ch. 2, and scikit-learn's `DecisionBoundaryDisplay`. Each region is the zero contour of
+* `p(class) − max p(other)`, so it works for any number of classes; `Confidence` adds that margin's upper contours (best-versus-second-best).
+* A model with more than two features is shown only through the slice the caller evaluated.
+*/
+var DecisionBoundaryChart = class extends CartesianChart {
+	static meta = {
+		id: "decision-boundary",
+		name: "Decision boundary",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Grid,
+		description: "Maps where a classifier predicts each class across two features, with its boundary and the points it gets right or wrong.",
+		tags: [
+			"classifier",
+			"machine learning",
+			"decision region",
+			"misclassification",
+			"predict_proba"
+		],
+		sample: (seed) => DecisionSamples.clusters(seed),
+		variants: {
+			fill: [
+				"regions",
+				"confidence",
+				"cells",
+				"no-fill"
+			],
+			overlay: [
+				"all-points",
+				"errors-only",
+				"no-points"
+			],
+			boundary: [true, false]
+		},
+		valid: ({ fill, boundary }) => fill !== "no-fill" || boundary === true
+	};
+	#memo = null;
+	#key = [];
+	defaults() {
+		return {
+			x: "x",
+			y: "y",
+			label: "group",
+			fill: "regions",
+			overlay: "all-points",
+			boundary: true,
+			resolution: 80
+		};
+	}
+	legendItems() {
+		const short = (name) => name.length > LABEL_ROOM ? `${name.slice(0, 23)}…` : name;
+		return [...super.legendItems().map((item) => ({
+			...item,
+			label: short(item.key)
+		})), ...this.#key];
+	}
+	/** `predict` may be slow, and a render paints more than once, so the sweep lasts until its inputs change. */
+	#view() {
+		const { data, x, y, label, predicted, resolution, xDomain, yDomain } = this.options;
+		const key = [
+			data,
+			x,
+			y,
+			label,
+			predicted,
+			resolution,
+			xDomain,
+			yDomain
+		];
+		if (this.#memo?.key.every((value, i) => value === key[i])) return this.#memo.view;
+		const view = this.#build();
+		this.#memo = {
+			key,
+			view
+		};
+		return view;
+	}
+	#build() {
+		const { data, x, y, label, predicted, resolution, xDomain, yDomain } = this.options;
+		const rows = (data?.points ?? []).flatMap((row) => {
+			const vx = number(row?.[x]), vy = number(row?.[y]), actual = text(row?.[label]);
+			return Number.isFinite(vx) && Number.isFinite(vy) && actual !== null ? [{
+				x: vx,
+				y: vy,
+				actual,
+				stated: predicted ? text(row[predicted]) : null
+			}] : [];
+		});
+		const given = data?.grid ? DecisionSurface.fromGrid(data.grid) : null;
+		const reach = (values, frame) => {
+			const [low = 0, high = 1] = extent([...values, ...frame ?? []].filter(Number.isFinite));
+			if (low === high) return [low - 1, high + 1];
+			const pad = frame ? 0 : (high - low) * .05;
+			return [low - pad, high + pad];
+		};
+		const rangeX = reach(rows.map((row) => row.x), given?.x ?? xDomain), rangeY = reach(rows.map((row) => row.y), given?.y ?? yDomain);
+		const known = [...new Set(rows.map((row) => row.actual))];
+		const surface = given ?? (data?.predict ? DecisionSurface.fromPredict(data.predict, rangeX, rangeY, resolution, known) : null);
+		const points = rows.map(({ stated, ...row }, index) => {
+			const call = surface?.classify(row.x, row.y) ?? null;
+			const label = stated ?? call?.label ?? null;
+			return {
+				...row,
+				index,
+				predicted: label,
+				probability: call?.label === label ? call?.probability ?? null : null,
+				correct: label === null ? null : label === row.actual
+			};
+		});
+		const named = points.flatMap((point) => [point.actual, ...point.predicted === null ? [] : [point.predicted]]);
+		return {
+			surface,
+			points,
+			classes: [.../* @__PURE__ */ new Set([...surface?.classes ?? [], ...named])],
+			x: rangeX,
+			y: rangeY
+		};
+	}
+	tickFormat(scale) {
+		return DistinctTicks.format(scale, super.tickFormat(scale));
+	}
+	scales(ctx) {
+		const { x, y } = this.#view();
+		return {
+			x: scaleLinear(x, [0, ctx.plot.width]),
+			y: scaleLinear(y, [ctx.plot.height, 0])
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { surface, classes } = this.#view();
+		for (const name of classes) ctx.palette.color(name);
+		this.#regions(ctx, axes, surface);
+		this.#cells(ctx, axes, surface);
+		this.#boundary(ctx, axes, surface);
+		this.#points(ctx, axes);
+	}
+	/** `FieldContours` drops line vertices on its outer nodes, so a repeated ring of nodes lets the boundary reach the edge of the grid. */
+	#contours(axes, surface, index) {
+		const { columns, rows } = surface, margin = surface.margin(index);
+		const across = scaleLinear(surface.x.map((_, i) => i), surface.x.map((v) => axes.x(v))).clamp(true);
+		const down = scaleLinear(surface.y.map((_, j) => j), surface.y.map((v) => axes.y(v))).clamp(true);
+		const inner = (value, size) => Math.max(0, Math.min(size - 1, value - 1));
+		const ringed = Array.from({ length: (rows + 2) * (columns + 2) }, (_, node) => margin[inner(node % (columns + 2), columns) + inner(Math.floor(node / (columns + 2)), rows) * columns]);
+		return new FieldContours(ringed, columns + 2, rows + 2, (i, j) => [across(i - 1), down(j - 1)]);
+	}
+	#regions(ctx, axes, surface) {
+		const { fill } = this.options;
+		const levels = fill === "confidence" ? [0, ...MARGINS] : fill === "regions" ? [0] : [];
+		const bands = !surface || !levels.length ? [] : surface.classes.flatMap((name, index) => {
+			const contours = this.#contours(axes, surface, index);
+			return levels.map((level) => ({
+				name,
+				index,
+				level,
+				d: contours.at(level).area
+			}));
+		});
+		const tint = fill === "confidence" ? BAND_TINT : REGION_TINT;
+		const paths = ctx.marks("regions", "path", bands, (d) => `${d.name}/${d.level}`).attr("fill", (d) => ctx.palette.color(d.name)).attr("fill-opacity", tint);
+		ctx.set(paths, {
+			d: (d) => d.d,
+			opacity: 1
+		}, {
+			d: (d) => d.d,
+			opacity: 0
+		});
+		ctx.hover(paths, (d) => ({
+			title: `Predicted ${d.name}`,
+			color: ctx.palette.color(d.name),
+			rows: [["Share of grid", percent(surface.share(d.index))], ...d.level ? [["Margin at least", d.level]] : []]
+		}));
+	}
+	#cells(ctx, axes, surface) {
+		const tiles = surface && this.options.fill === "cells" ? surface.tiles(axes.x, axes.y) : [];
+		const name = (index) => surface.classes[index];
+		const paths = ctx.marks("cells", "path", tiles, (d) => d.index).attr("fill", (d) => ctx.palette.color(name(d.index))).attr("fill-opacity", REGION_TINT);
+		ctx.set(paths, {
+			d: (d) => d.d,
+			opacity: 1
+		}, {
+			d: (d) => d.d,
+			opacity: 0
+		});
+		ctx.hover(paths, (d) => ({
+			title: `Predicted ${name(d.index)}`,
+			color: ctx.palette.color(name(d.index)),
+			rows: [["Share of grid", percent(surface.share(d.index))]]
+		}));
+	}
+	/** Every stretch of boundary has a class on each side, so the last class's outline would only repeat the others. */
+	#boundary(ctx, axes, surface) {
+		const edges = surface && this.options.boundary ? surface.classes.slice(0, -1).map((name, index) => ({
+			name,
+			d: this.#contours(axes, surface, index).at(0).line
+		})) : [];
+		const lines = ctx.marks("boundary", "path", edges.filter((edge) => edge.d), (d) => d.name).attr("fill", "none").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-linecap", "round");
+		ctx.set(lines, { d: (d) => d.d });
+		ctx.drawOn(lines);
+		ctx.hover(lines, () => ({
+			title: "Decision boundary",
+			rows: [["Meaning", "Top two classes tie"]]
+		}));
+	}
+	#points(ctx, axes) {
+		const { overlay } = this.options, { points, classes } = this.#view();
+		const wrong = points.filter((point) => point.correct === false), right = points.filter((point) => point.correct === true);
+		const unscored = points.length - wrong.length - right.length, scored = points.length > unscored;
+		const shown = overlay === "no-points" ? [] : overlay === "errors-only" ? wrong : [...points.filter((point) => point.correct !== false), ...wrong];
+		const hollow = (d) => d.correct === null;
+		const marks = ctx.marks("points", "path", shown, (d) => d.index).attr("fill", (d) => hollow(d) ? ctx.theme.surface : ctx.palette.color(d.actual)).attr("stroke", (d) => hollow(d) ? ctx.palette.color(d.actual) : ctx.theme.surface).attr("stroke-width", 2).attr("paint-order", "stroke").attr("stroke-linejoin", "round");
+		const place = (d) => `translate(${axes.x(d.x)},${axes.y(d.y)})${d.correct === false ? " rotate(45)" : ""}`;
+		const shape = (d) => d.correct === false ? cross : dot;
+		ctx.set(marks, {
+			d: shape,
+			transform: place,
+			opacity: 1
+		}, {
+			d: shape,
+			transform: place,
+			opacity: 0
+		});
+		ctx.hover(marks, (d) => ({
+			title: d.correct === null ? "Not scored" : d.correct ? "Correct" : "Wrong",
+			color: ctx.palette.color(d.actual),
+			rows: [
+				["Actual", d.actual],
+				["Predicted", d.predicted ?? "None"],
+				...d.probability === null ? [] : [["Probability", percent(d.probability)]],
+				[this.options.xLabel ?? this.options.x, d.x],
+				[this.options.yLabel ?? this.options.y, d.y]
+			]
+		}));
+		const legend = overlay === "no-points" ? [] : [
+			...scored && overlay === "all-points" ? [{
+				key: "right",
+				label: `● correct ${right.length}`
+			}] : [],
+			...scored ? [{
+				key: "wrong",
+				label: `✕ wrong ${wrong.length}`
+			}] : [],
+			...unscored && overlay === "all-points" ? [{
+				key: "unscored",
+				label: `○ not scored ${unscored}`
+			}] : []
+		];
+		const band = this.options.fill === "confidence" && classes.length ? [{
+			key: "margin",
+			label: "deeper tint: larger margin"
+		}] : [];
+		this.#key = [...legend, ...band].map((item) => ({
+			...item,
+			color: "none"
+		}));
+	}
+	table() {
+		const { x, y, label, predicted } = this.options, { points } = this.#view();
+		return {
+			columns: [
+				x,
+				y,
+				label,
+				predicted ?? "predicted",
+				"probability",
+				"correct"
+			],
+			rows: points.map((point) => [
+				point.x,
+				point.y,
+				point.actual,
+				point.predicted,
+				point.probability,
+				point.correct === null ? null : String(point.correct)
+			])
+		};
+	}
+};
+export { DecisionBoundaryChart, DecisionFill, DecisionOverlay };

package/dist/charts/mlcharts/DecisionSamples.js

@@ -0,0 +1,60 @@
+import { SampleData } from "../../data/SampleData.js";
+import { extent, group, mean, range, variance } from "d3";
+// src/charts/mlcharts/DecisionSamples.ts
+var GRID = 61;
+var FLOOR = 1e-6;
+/**
+* Synthetic demo only: seeded `SampleData` clusters and a toy classifier fitted to them. Not a real model or measurement.
+* The classifier is Gaussian naive Bayes (Hastie, Tibshirani & Friedman, ESL §6.6.3): per-class axis-aligned normals, priors from class counts.
+*/
+var DecisionSamples = class {
+	/** Fits Gaussian naive Bayes on two numeric columns. */
+	static naiveBayes(rows, x, y, label) {
+		const classes = [...group(rows, (row) => String(row[label]))].map(([name, members]) => {
+			const fit = (column) => {
+				const values = members.map((row) => Number(row[column]));
+				return {
+					mean: mean(values) ?? 0,
+					variance: Math.max(FLOOR, variance(values) ?? FLOOR)
+				};
+			};
+			return {
+				name,
+				prior: Math.log(members.length / rows.length),
+				x: fit(x),
+				y: fit(y)
+			};
+		});
+		const logNormal = (value, fit) => -.5 * (Math.log(2 * Math.PI * fit.variance) + (value - fit.mean) ** 2 / fit.variance);
+		return (vx, vy) => {
+			const scores = classes.map((c) => c.prior + logNormal(vx, c.x) + logNormal(vy, c.y));
+			const top = Math.max(...scores);
+			return Object.fromEntries(classes.map((c, k) => [c.name, Math.exp(scores[k] - top)]));
+		};
+	}
+	/** Three overlapping clusters with that classifier's probabilities evaluated onto a grid. */
+	static clusters(seed) {
+		const points = SampleData.points(seed, 150, 3);
+		const predict = this.naiveBayes(points, "x", "y", "group");
+		const sweep = (column) => {
+			const [low = 0, high = 1] = extent(points, (row) => Number(row[column])), pad = (high - low) * .05;
+			return range(GRID).map((i) => low - pad + (high - low + 2 * pad) * i / 60);
+		};
+		const x = sweep("x"), y = sweep("y");
+		const classes = [...new Set(points.map((row) => String(row.group)))];
+		return {
+			points,
+			grid: {
+				x,
+				y,
+				classes,
+				probabilities: y.map((vy) => x.map((vx) => {
+					const scores = predict(vx, vy);
+					const total = classes.reduce((sum, name) => sum + scores[name], 0);
+					return classes.map((name) => scores[name] / total);
+				}))
+			}
+		};
+	}
+};
+export { DecisionSamples };

package/dist/charts/mlcharts/DecisionSurface.js

@@ -0,0 +1,130 @@
+import { ascending, bisectRight, range } from "d3";
+// src/charts/mlcharts/DecisionSurface.ts
+var answer = (value) => typeof value === "object" ? Object.entries(value ?? {}) : value === void 0 ? [] : [[String(value), 1]];
+/** Ranks scores. Anything but finite non-negative numbers with a positive total means no call. */
+var rank = (scores) => {
+	if (!scores.length || scores.some(([, p]) => !Number.isFinite(p) || p < 0)) return null;
+	const total = scores.reduce((sum, [, p]) => sum + p, 0);
+	if (!(total > 0)) return null;
+	const [first, second] = [...scores].sort((a, b) => b[1] - a[1]);
+	return {
+		label: first[0],
+		probability: first[1] / total,
+		margin: (first[1] - (second?.[1] ?? 0)) / total
+	};
+};
+/** Class probabilities on a rectilinear grid, in ascending x and y. Where a class leads is its decision region. */
+var DecisionSurface = class DecisionSurface {
+	x;
+	y;
+	classes;
+	cells;
+	exact;
+	columns;
+	rows;
+	/** `cells[(i + j * columns) * classes.length + k]` holds a probability, NaN over a gap. */
+	constructor(x, y, classes, cells, exact) {
+		this.x = x;
+		this.y = y;
+		this.classes = classes;
+		this.cells = cells;
+		this.exact = exact;
+		this.columns = x.length;
+		this.rows = y.length;
+	}
+	/** A grid that can be read at all: two or more distinct finite coordinates per axis, any order, and at least one class. */
+	static fromGrid({ x, y, classes, probabilities }) {
+		const across = DecisionSurface.axis(x), down = DecisionSurface.axis(y), labels = (classes ?? []).map(String);
+		if (!across || !down || !labels.length) return null;
+		const width = labels.length, cells = new Float64Array(across.length * down.length * width).fill(NaN);
+		down.forEach((j, row) => across.forEach((i, column) => {
+			const source = probabilities?.[j]?.[i];
+			if (source?.length !== width) return;
+			DecisionSurface.write(cells, (column + row * across.length) * width, source.map((p, k) => [labels[k], p ?? NaN]));
+		}));
+		return new DecisionSurface(across.map((i) => x[i]), down.map((j) => y[j]), labels, cells);
+	}
+	/** Sweeps `predict` over a `resolution × resolution` grid. Points are then scored by `predict` itself, not read off the grid. */
+	static fromPredict(predict, xDomain, yDomain, resolution, known = []) {
+		const size = Math.max(2, Math.min(400, Math.round(resolution) || 2));
+		const steps = ([low, high]) => range(size).map((i) => low + (high - low) * i / (size - 1));
+		const x = steps(xDomain), y = steps(yDomain);
+		const seen = new Set(known);
+		const answers = y.flatMap((vy) => x.map((vx) => answer(predict(vx, vy))));
+		for (const scores of answers) for (const [label] of scores) seen.add(label);
+		const labels = [...seen], cells = new Float64Array(size * size * labels.length).fill(NaN);
+		answers.forEach((scores, cell) => {
+			const given = new Map(scores);
+			DecisionSurface.write(cells, cell * labels.length, labels.map((label) => [label, given.get(label) ?? 0]));
+		});
+		return new DecisionSurface(x, y, labels, cells, predict);
+	}
+	/** Indexes that sort a coordinate array, or null when it cannot be a grid axis. */
+	static axis(values) {
+		if (!values || values.length < 2 || !values.every(Number.isFinite)) return null;
+		const order = range(values.length).sort((a, b) => ascending(values[a], values[b]));
+		return order.every((index, i) => !i || values[index] > values[order[i - 1]]) ? order : null;
+	}
+	static write(cells, offset, scores) {
+		if (!rank(scores)) return;
+		const total = scores.reduce((sum, [, p]) => sum + p, 0);
+		scores.forEach(([, p], k) => {
+			cells[offset + k] = p / total;
+		});
+	}
+	/** `p(class) − max p(other)` per node: its zero contour is the edge of that class's region. NaN over gaps. */
+	margin(index) {
+		const { classes: { length: width }, cells } = this;
+		return Array.from({ length: this.columns * this.rows }, (_, node) => {
+			let rival = Number.NEGATIVE_INFINITY;
+			for (let k = 0; k < width; k++) if (k !== index) rival = Math.max(rival, cells[node * width + k]);
+			const own = cells[node * width + index];
+			return width > 1 ? own - rival : own;
+		});
+	}
+	/** Index of the leading class per node, -1 over gaps. */
+	leaders() {
+		const { classes: { length: width }, cells } = this;
+		return Int32Array.from({ length: this.columns * this.rows }, (_, node) => {
+			if (Number.isNaN(cells[node * width])) return -1;
+			let best = 0;
+			for (let k = 1; k < width; k++) if (cells[node * width + k] > cells[node * width + best]) best = k;
+			return best;
+		});
+	}
+	/** The model's call at a location. A grid is read bilinearly and makes no call outside its extent or next to a gap. */
+	classify(x, y) {
+		if (this.exact) return rank(answer(this.exact(x, y)));
+		const { x: xs, y: ys, classes, columns, cells } = this, width = classes.length;
+		if (x < xs[0] || x > xs.at(-1) || y < ys[0] || y > ys.at(-1)) return null;
+		const i = Math.min(columns - 2, bisectRight(xs, x) - 1), j = Math.min(this.rows - 2, bisectRight(ys, y) - 1);
+		const u = (x - xs[i]) / (xs[i + 1] - xs[i]), v = (y - ys[j]) / (ys[j + 1] - ys[j]);
+		const at = (a, b, k) => cells[(a + b * columns) * width + k];
+		return rank(classes.map((label, k) => [label, (at(i, j, k) * (1 - u) + at(i + 1, j, k) * u) * (1 - v) + (at(i, j + 1, k) * (1 - u) + at(i + 1, j + 1, k) * u) * v]));
+	}
+	/** One crisp path per class with a node in it, each node owning the area nearest it. Edges land on whole pixels so tiles leave no seams. */
+	tiles(sx, sy) {
+		const { columns, rows } = this, leaders = this.leaders();
+		const edges = (values, scale) => values.map((value, i) => Math.round(scale(i ? (values[i - 1] + value) / 2 : value))).concat(Math.round(scale(values.at(-1))));
+		const across = edges(this.x, sx), down = edges(this.y, sy);
+		const runs = /* @__PURE__ */ new Map();
+		for (let j = 0; j < rows; j++) for (let i = 0, end; i < columns; i = end) {
+			const leader = leaders[i + j * columns];
+			end = i + 1;
+			while (end < columns && leaders[end + j * columns] === leader) end++;
+			if (leader < 0) continue;
+			if (!runs.has(leader)) runs.set(leader, []);
+			runs.get(leader).push(`M${across[i]} ${down[j]}H${across[end]}V${down[j + 1]}H${across[i]}Z`);
+		}
+		return [...runs].sort(([a], [b]) => a - b).map(([index, list]) => ({
+			index,
+			d: list.join("")
+		}));
+	}
+	/** Share of scored nodes won by a class. */
+	share(index) {
+		const leaders = this.leaders(), scored = leaders.filter((leader) => leader >= 0).length;
+		return scored ? leaders.filter((leader) => leader === index).length / scored : 0;
+	}
+};
+export { DecisionSurface };

package/dist/charts/mlcharts/DistinctTicks.js

@@ -0,0 +1,13 @@
+// src/charts/mlcharts/DistinctTicks.ts
+var COUNT = 10;
+/** The axis format from core rounds to whole numbers from 10 up, so a narrow range would repeat a label. */
+var DistinctTicks = class {
+	/** Keeps `format` unless it gives two ticks one label; then uses the precision of the scale's own tick step. */
+	static format(scale, format) {
+		if (!format || !("ticks" in scale) || !("tickFormat" in scale)) return format;
+		const fine = scale;
+		const labels = fine.ticks(COUNT).map(format);
+		return new Set(labels).size < labels.length ? (value) => fine.tickFormat(COUNT)(+value) : format;
+	}
+};
+export { DistinctTicks };

package/dist/charts/mlcharts/ElbowMath.js

@@ -0,0 +1,153 @@
+import { ElbowMethod } from "./curveDiagnosticEnums.js";
+// src/charts/mlcharts/ElbowMath.ts
+var TINY = 1e-12;
+var NONE = {
+	index: null,
+	trace: [],
+	segments: []
+};
+/** Elbow detectors for a score-by-k curve, in either direction. Points must be sorted by k with distinct k. */
+var ElbowMath = class {
+	/** Unit-square form with x rising and the curve bending like a concave rise. `null` if x or y is constant. */
+	static unit(points) {
+		if (points.length < 3) return null;
+		const falling = points.at(-1).score <= points[0].score;
+		const scores = points.map((point) => falling ? -point.score : point.score);
+		const low = Math.min(...scores), high = Math.max(...scores), first = points[0].k, last = points.at(-1).k;
+		if (high - low < TINY || last - first < TINY) return null;
+		return {
+			x: points.map((point) => (point.k - first) / (last - first)),
+			y: scores.map((score) => (score - low) / (high - low))
+		};
+	}
+	/**
+	* Kneedle (Satopää, Albrecht, Irwin and Raghavan 2011), offline form without the smoothing step. Local maxima of the
+	* difference curve are candidates; the first whose difference drops below `d - S / (n - 1)` before the next maximum is the knee.
+	*/
+	static kneedle(points, sensitivity = 1) {
+		const unit = this.unit(points);
+		if (!unit) return NONE;
+		const { x, y } = unit, n = x.length;
+		const trace = y.map((value, i) => value - x[i]);
+		const maxima = [];
+		for (let i = 1; i < n - 1; i++) if (trace[i] > TINY && trace[i] > trace[i - 1] && trace[i] >= trace[i + 1]) maxima.push(i);
+		const step = 1 / (n - 1);
+		for (const [slot, candidate] of maxima.entries()) {
+			const threshold = trace[candidate] - sensitivity * step;
+			for (let j = candidate + 1; j < (maxima[slot + 1] ?? n); j++) if (trace[j] < threshold) return {
+				index: candidate,
+				trace,
+				segments: []
+			};
+		}
+		return {
+			index: null,
+			trace,
+			segments: []
+		};
+	}
+	/**
+	* L method (Salvador and Chan 2004): two least-squares lines, one per side of each split c, keeping the split with the
+	* lowest size-weighted RMSE. Each side has at least two points, and the elbow is c, the last point of the left line.
+	* Only splits where the curve flattens count, so a straight line has no elbow. The paper's iterative cutoff is not applied.
+	*/
+	static lMethod(points) {
+		const n = points.length;
+		if (n < 4 || !this.unit(points)) return NONE;
+		const sign = points.at(-1).score <= points[0].score ? -1 : 1;
+		let top = null;
+		for (let c = 1; c <= n - 3; c++) {
+			const left = this.#fit(points.slice(0, c + 1)), right = this.#fit(points.slice(c + 1));
+			const error = ((c + 1) * left.rmse + (n - c - 1) * right.rmse) / n;
+			if (sign * (left.slope - right.slope) > 1e-9 * (Math.abs(left.slope) + Math.abs(right.slope)) && (!top || error < top.error)) top = {
+				index: c,
+				error,
+				left: left.segment,
+				right: right.segment
+			};
+		}
+		return top ? {
+			index: top.index,
+			trace: [],
+			segments: [top.left, top.right]
+		} : NONE;
+	}
+	static #fit(points) {
+		const n = points.length, meanX = points.reduce((a, p) => a + p.k, 0) / n, meanY = points.reduce((a, p) => a + p.score, 0) / n;
+		const spread = points.reduce((a, p) => a + (p.k - meanX) ** 2, 0);
+		const slope = points.reduce((a, p) => a + (p.k - meanX) * (p.score - meanY), 0) / spread;
+		const at = (k) => meanY + slope * (k - meanX);
+		const first = points[0].k, last = points.at(-1).k;
+		return {
+			slope,
+			rmse: Math.sqrt(points.reduce((a, p) => a + (p.score - at(p.k)) ** 2, 0) / n),
+			segment: {
+				x1: first,
+				y1: at(first),
+				x2: last,
+				y2: at(last)
+			}
+		};
+	}
+	/** Point furthest above the chord from first to last in the unit square: the triangle method of Rosin (2001). */
+	static chord(points) {
+		const unit = this.unit(points);
+		if (!unit) return NONE;
+		const { x, y } = unit, rise = y.at(-1) - y[0], length = Math.hypot(1, rise);
+		const trace = y.map((value, i) => (value - y[0] - rise * x[i]) / length);
+		const index = this.#peak(trace), first = points[0], last = points.at(-1);
+		const chord = {
+			x1: first.k,
+			y1: first.score,
+			x2: last.k,
+			y2: last.score
+		};
+		if (index === null) return {
+			index,
+			trace,
+			segments: [chord]
+		};
+		const { k, score } = points[index];
+		return {
+			index,
+			trace,
+			segments: [chord, {
+				x1: k,
+				y1: score,
+				x2: k,
+				y2: first.score + (last.score - first.score) * (k - first.k) / (last.k - first.k)
+			}]
+		};
+	}
+	/** Sharpest bend: the largest second divided difference of the unit curve, which handles uneven k. Ends have none. */
+	static secondDifference(points) {
+		const unit = this.unit(points);
+		if (!unit) return NONE;
+		const { x, y } = unit;
+		const trace = y.map((value, i) => {
+			if (i === 0 || i === y.length - 1) return null;
+			return 2 * ((value - y[i - 1]) / (x[i] - x[i - 1]) - (y[i + 1] - value) / (x[i + 1] - x[i])) / (x[i + 1] - x[i - 1]);
+		});
+		return {
+			index: this.#peak(trace),
+			trace,
+			segments: []
+		};
+	}
+	static #peak(values) {
+		let top = null;
+		values.forEach((value, i) => {
+			if (value !== null && value > TINY && (top === null || value > values[top])) top = i;
+		});
+		return top;
+	}
+	static fit(points, method, sensitivity = 1) {
+		switch (method) {
+			case ElbowMethod.LMethod: return this.lMethod(points);
+			case ElbowMethod.Chord: return this.chord(points);
+			case ElbowMethod.SecondDifference: return this.secondDifference(points);
+			default: return this.kneedle(points, sensitivity);
+		}
+	}
+};
+export { ElbowMath };