@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/mlcharts/LearningCurveChart.js

@@ -0,0 +1,276 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension, ScaleKind } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { TrendHover } from "../linesareas/TrendHover.js";
+import { cellNumber } from "./CellNumber.js";
+import { CurveDiagnosticSamples } from "./CurveDiagnosticSamples.js";
+import { MetricGoal, OverfitShading, RunSpread } from "./curveDiagnosticEnums.js";
+import { CurvePickMark } from "./CurvePickMark.js";
+import { DistinctTicks } from "./DistinctTicks.js";
+import { LearningCurveMath } from "./LearningCurveMath.js";
+import { WideLabel } from "./WideLabel.js";
+import { area, extent, line, min, scaleLinear, ticks } from "d3";
+// src/charts/mlcharts/LearningCurveChart.ts
+var TRAINING = "Training";
+var VALIDATION = "Validation";
+var LINE = 16;
+var GAP_NAME = {
+	[OverfitShading.None]: "",
+	[OverfitShading.Generalization]: "Generalization gap",
+	[OverfitShading.AfterBest]: "Overfit gap"
+};
+/**
+* Diagnoses training over epochs: mean training and validation metric with a spread band across runs, the best validation
+* epoch, and the generalization gap. Follows the usual early-stopping reading (Prechelt 1998): the best epoch is the
+* earliest with the best mean validation metric, computed after any smoothing, and overfitting is validation worsening
+* while training still improves. Smoothing is TensorBoard's debiased EMA. Runs that stop early shrink the mean's sample.
+*/
+var LearningCurveChart = class extends CartesianChart {
+	static meta = {
+		id: "learning-curve",
+		name: "Learning curve",
+		family: ChartFamily.Trend,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Shows a training and validation metric by epoch across runs, with a spread band, the best epoch and the overfitting gap.",
+		tags: [
+			"machine learning",
+			"training",
+			"validation",
+			"overfitting",
+			"early stopping",
+			"loss curve"
+		],
+		sample: (seed) => CurveDiagnosticSamples.trainingRuns(seed),
+		variants: {
+			spread: [
+				RunSpread.StandardDeviation,
+				RunSpread.Confidence95,
+				RunSpread.Range
+			],
+			gap: [
+				OverfitShading.AfterBest,
+				OverfitShading.Generalization,
+				OverfitShading.None
+			],
+			best: [true, false],
+			runs: [false, true],
+			scale: [ScaleKind.Linear, ScaleKind.Log],
+			smoothing: [0, .6]
+		}
+	};
+	#view = null;
+	#valueAxis = null;
+	defaults() {
+		return {
+			x: "epoch",
+			y: "value",
+			run: "run",
+			split: "split",
+			trainSplit: "train",
+			validationSplit: "validation",
+			xLabel: "Epoch",
+			yLabel: "Loss",
+			goal: MetricGoal.Minimize,
+			spread: RunSpread.StandardDeviation,
+			gap: OverfitShading.AfterBest,
+			best: true,
+			runs: false,
+			scale: ScaleKind.Linear,
+			smoothing: 0
+		};
+	}
+	get logarithmic() {
+		return this.options.scale === ScaleKind.Log;
+	}
+	xTicks() {
+		const stats = [...this.#view?.train.stats ?? [], ...this.#view?.validation.stats ?? []];
+		const [lo = 0, hi = 1] = extent(stats, (stat) => stat.epoch);
+		return lo === hi ? 2 : Math.min(7, Math.ceil(hi - lo));
+	}
+	curvesOf(split) {
+		const { data, x, y, run, split: column } = this.options, wanted = String(split);
+		const smoothing = Math.min(.999, Math.max(0, this.options.smoothing || 0));
+		const runs = /* @__PURE__ */ new Map();
+		for (const row of Array.isArray(data) ? data : []) {
+			if (!row || String(row[column]) !== wanted) continue;
+			const epoch = cellNumber(row[x]), value = cellNumber(row[y]);
+			if (epoch === null || value === null || this.logarithmic && value <= 0) continue;
+			const name = String(row[run] ?? ""), rows = runs.get(name) ?? runs.set(name, /* @__PURE__ */ new Map()).get(name);
+			(rows.get(epoch) ?? rows.set(epoch, []).get(epoch)).push(value);
+		}
+		return [...runs].map(([name, rows]) => {
+			const epochs = [...rows.keys()].sort((a, b) => a - b);
+			const values = LearningCurveMath.smooth(epochs.map((epoch) => rows.get(epoch).reduce((a, b) => a + b, 0) / rows.get(epoch).length), smoothing);
+			return {
+				run: name,
+				points: epochs.map((epoch, i) => ({
+					epoch,
+					value: values[i]
+				}))
+			};
+		});
+	}
+	/** Rows the split names failed to match, so a curve is not lost without a word. Another split, like test, is fine beside both. */
+	get absentSplits() {
+		const { data, split, trainSplit, validationSplit } = this.options;
+		const named = [String(trainSplit), String(validationSplit)];
+		const seen = new Set((Array.isArray(data) ? data : []).flatMap((row) => row?.[split] === null || row?.[split] === void 0 ? [] : [String(row[split])]));
+		const absent = named.filter((name) => !seen.has(name)), others = [...seen].filter((name) => !named.includes(name));
+		return absent.length && others.length ? `No '${absent.join("' or '")}' rows. Found: ${others.slice(0, 4).join(", ")}` : "";
+	}
+	read() {
+		const { trainSplit, validationSplit, spread, goal, gap } = this.options;
+		const parts = [{
+			key: TRAINING,
+			curves: this.curvesOf(trainSplit)
+		}, {
+			key: VALIDATION,
+			curves: this.curvesOf(validationSplit)
+		}];
+		const floor = LearningCurveMath.floor(parts.flatMap(({ curves }) => curves.flatMap((curve) => curve.points.map((point) => point.value))), this.logarithmic);
+		const [train, validation] = parts.map(({ key, curves }) => ({
+			key,
+			curves,
+			stats: LearningCurveMath.summarize(curves, spread).map((stat) => floor === void 0 ? stat : {
+				...stat,
+				low: Math.max(stat.low, floor)
+			})
+		}));
+		const best = LearningCurveMath.best(validation.stats, goal);
+		return {
+			train,
+			validation,
+			best,
+			gaps: LearningCurveMath.gaps(train.stats, validation.stats, goal, gap, best?.epoch ?? null)
+		};
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot;
+		const { train, validation } = this.#view = this.read();
+		const splits = [train, validation], log = this.logarithmic;
+		const epochs = splits.flatMap(({ stats }) => stats.map((stat) => stat.epoch));
+		const values = splits.flatMap(({ stats, curves }) => [...stats.flatMap((stat) => [stat.low, stat.high]), ...this.options.runs ? curves.flatMap((curve) => curve.points.map((point) => point.value)) : []]);
+		let [left, right] = extent(epochs), [lo, hi] = extent(values);
+		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] = log ? [1, 10] : [0, 1];
+		if (lo === hi) {
+			const pad = Math.abs(lo) * .1 || 1;
+			[lo, hi] = [log ? lo / 2 : lo - pad, hi + pad];
+		}
+		const scale = Scales.continuous(this.options.scale).domain([lo, hi]).range([height, 0]);
+		const y = !log ? scale.nice() : hi / lo < 10 ? Object.assign(scale, { ticks: () => ticks(lo, hi, this.yTicks()) }) : scale;
+		this.#valueAxis = y;
+		return {
+			x: scaleLinear([left, right], [0, width]),
+			y
+		};
+	}
+	/** On a wide log axis only 1, 2 and 5 keep a label; the rest would collide. */
+	tickFormat(scale) {
+		const format = super.tickFormat(scale), [lo, hi] = scale.domain?.() ?? [];
+		if (!this.logarithmic || scale !== this.#valueAxis) return DistinctTicks.format(scale, format);
+		if (!format || !(hi / lo > 20)) return format;
+		return (value) => [
+			1,
+			2,
+			5
+		].includes(Math.round(+value / 10 ** Math.floor(Math.log10(+value) + 1e-9))) ? format(value) : "";
+	}
+	legendItems() {
+		const gap = this.#view?.gaps.length ? [{
+			key: GAP_NAME[this.options.gap],
+			color: this.palette.diverging(.7)
+		}] : [];
+		return [...super.legendItems(), ...gap];
+	}
+	plotMarks(ctx, axes) {
+		const { goal } = this.options;
+		const view = this.#view, { train, validation, best, gaps } = view;
+		const px = (epoch) => axes.x(epoch) ?? 0, py = (value) => axes.y(value) ?? 0;
+		const splits = [train, validation].filter((split) => split.stats.length);
+		const color = (split) => ctx.palette.color(split.key);
+		for (const split of splits) color(split);
+		const gapShape = area().x((d) => px(d.epoch)).y0((d) => py(d.train)).y1((d) => py(d.validation));
+		const gapFlat = area().x((d) => px(d.epoch)).y0((d) => py(d.train)).y1((d) => py(d.train));
+		const gapFills = ctx.marks("gap", "path", gaps, (_, i) => i).attr("fill", ctx.palette.diverging(.7)).attr("fill-opacity", .3);
+		ctx.set(gapFills, { d: (d) => gapShape(d) ?? "" }, { d: (d) => gapFlat(d) ?? "" });
+		const band = area().x((d) => px(d.epoch)).y0((d) => py(d.low)).y1((d) => py(d.high));
+		const flat = area().x((d) => px(d.epoch)).y0((d) => py(d.center)).y1((d) => py(d.center));
+		const bands = ctx.marks("bands", "path", splits.filter((split) => split.curves.length > 1), (d) => d.key).attr("fill", color).attr("fill-opacity", .2);
+		ctx.set(bands, { d: (d) => band(d.stats) ?? "" }, { d: (d) => flat(d.stats) ?? "" });
+		const trace = line().x((d) => px(d.epoch)).y((d) => py(d.value));
+		const every = this.options.runs ? splits.flatMap((split) => split.curves.map((curve) => ({
+			...curve,
+			split
+		}))) : [];
+		const runs = ctx.marks("runs", "path", every, (d) => `${d.split.key}/${d.run}`).attr("fill", "none").attr("stroke", (d) => color(d.split)).attr("stroke-width", 1).attr("stroke-opacity", .4).attr("stroke-linejoin", "round");
+		ctx.set(runs, { d: (d) => trace(d.points) ?? "" });
+		const center = line().x((d) => px(d.epoch)).y((d) => py(d.center));
+		const means = ctx.marks("means", "path", splits, (d) => d.key).attr("fill", "none").attr("stroke", color).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-linecap", "round");
+		ctx.set(means, { d: (d) => center(d.stats) ?? "" });
+		ctx.drawOn(means);
+		this.drawLoneEpochs(ctx, splits.filter((split) => split.stats.length === 1), px, py);
+		const pick = this.options.best && best ? {
+			x: px(best.epoch),
+			y: py(best.center),
+			text: `Best epoch ${TrendHover.title(best.epoch)} · ${TrendHover.value(best.center)}`
+		} : null;
+		CurvePickMark.draw(ctx, "best", pick, goal === MetricGoal.Maximize ? ctx.plot.height - 8 : 12);
+		this.drawSplitNote(ctx);
+		TrendHover.attach(ctx, this.slices(ctx, view, px, py), ctx.plot.width, ctx.plot.height);
+	}
+	/** A line through one epoch draws nothing, so that mean is a dot and its band a stem. */
+	drawLoneEpochs(ctx, splits, px, py) {
+		const color = (split) => ctx.palette.color(split.key), only = (split) => split.stats[0];
+		const stems = ctx.marks("lone-bands", "line", splits.filter((split) => only(split).high > only(split).low), (d) => d.key).attr("stroke", color).attr("stroke-width", 2).attr("stroke-opacity", .4);
+		ctx.set(stems, {
+			x1: (d) => px(only(d).epoch),
+			x2: (d) => px(only(d).epoch),
+			y1: (d) => py(only(d).low),
+			y2: (d) => py(only(d).high)
+		});
+		const dots = ctx.marks("lone-means", "circle", splits, (d) => d.key).attr("fill", color).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => px(only(d).epoch),
+			cy: (d) => py(only(d).center),
+			r: 5
+		}, { r: 0 });
+	}
+	/** Sits where a curve with this goal ends up empty, and clear of the best-epoch label. */
+	drawSplitNote(ctx) {
+		const { width, height } = ctx.plot, note = this.absentSplits;
+		const { goal, best } = this.options, clear = best && this.#view?.best ? LINE : 0;
+		const y = goal === MetricGoal.Maximize ? height - 8 - clear : 12 + clear;
+		ctx.text(ctx.marks("missing-split", "text", note ? [WideLabel.fit(note, width - 4)] : []), 11, "muted").attr("text-anchor", "end").attr("x", width - 2).attr("y", y).attr("paint-order", "stroke").attr("stroke", ctx.theme.surface).attr("stroke-width", 3).text((d) => d);
+	}
+	slices(ctx, { train, validation }, px, py) {
+		const trained = new Map(train.stats.map((stat) => [stat.epoch, stat])), held = new Map(validation.stats.map((stat) => [stat.epoch, stat]));
+		const spreadRow = (name, stat) => [`${name} band`, `${TrendHover.value(stat.low)} – ${TrendHover.value(stat.high)}`];
+		return [.../* @__PURE__ */ new Set([...trained.keys(), ...held.keys()])].sort((a, b) => a - b).map((epoch) => {
+			const a = trained.get(epoch), b = held.get(epoch);
+			const rows = [];
+			if (a) rows.push([TRAINING, TrendHover.value(a.center)], spreadRow(TRAINING, a));
+			if (b) rows.push([VALIDATION, TrendHover.value(b.center)], spreadRow(VALIDATION, b));
+			if (a && b) rows.push(["Gap", TrendHover.value(Math.abs(b.center - a.center))]);
+			rows.push(["Runs", min([a?.runs ?? Infinity, b?.runs ?? Infinity])]);
+			const marks = [...a ? [{
+				x: px(epoch),
+				y: py(a.center),
+				color: ctx.palette.color(TRAINING)
+			}] : [], ...b ? [{
+				x: px(epoch),
+				y: py(b.center),
+				color: ctx.palette.color(VALIDATION)
+			}] : []];
+			return {
+				x: px(epoch),
+				title: `Epoch ${TrendHover.title(epoch)}`,
+				rows,
+				marks
+			};
+		});
+	}
+};
+export { LearningCurveChart };

package/dist/charts/mlcharts/LearningCurveMath.js

@@ -0,0 +1,92 @@
+import { StatMath } from "../statistics/StatMath.js";
+import { MetricGoal, OverfitShading, RunSpread } from "./curveDiagnosticEnums.js";
+import { mean, min, sum } from "d3";
+// src/charts/mlcharts/LearningCurveMath.ts
+/** The calculations behind a learning curve, free of drawing. */
+var LearningCurveMath = class {
+	/** TensorBoard's debiased exponential moving average. `weight` 0 returns the input; the first value is never pulled towards zero. */
+	static smooth(values, weight) {
+		if (!(weight > 0)) return [...values];
+		let last = 0;
+		return values.map((value, i) => {
+			last = last * weight + (1 - weight) * value;
+			return last / (1 - weight ** (i + 1));
+		});
+	}
+	/** Band around `center`: mean ± one sample SD, a Student-t 95% CI of the mean, or the observed min and max. One run has no width. */
+	static interval(values, center, spread) {
+		const n = values.length;
+		if (n < 2) return [center, center];
+		if (spread === RunSpread.Range) return [Math.min(...values), Math.max(...values)];
+		const sd = Math.sqrt(sum(values, (value) => (value - center) ** 2) / (n - 1));
+		const reach = spread === RunSpread.Confidence95 ? StatMath.tQuantile(.975, n - 1) * sd / Math.sqrt(n) : sd;
+		return [center - reach, center + reach];
+	}
+	/** Mean and band per epoch. Runs that stopped early leave later epochs with a smaller `runs`. */
+	static summarize(curves, spread) {
+		const epochs = /* @__PURE__ */ new Map();
+		for (const { points } of curves) for (const { epoch, value } of points) (epochs.get(epoch) ?? epochs.set(epoch, []).get(epoch)).push(value);
+		return [...epochs].sort(([a], [b]) => a - b).map(([epoch, values]) => {
+			const center = mean(values);
+			const [low, high] = this.interval(values, center, spread);
+			return {
+				epoch,
+				center,
+				low,
+				high,
+				runs: values.length
+			};
+		});
+	}
+	/** The earliest epoch with the best mean, the checkpoint early stopping would restore. */
+	static best(stats, goal) {
+		const sign = goal === MetricGoal.Minimize ? 1 : -1;
+		return stats.reduce((top, stat) => !top || sign * stat.center < sign * top.center ? stat : top, null);
+	}
+	/**
+	* Stretches where validation is worse than training, ending on the exact crossings of the two straight mean lines.
+	* `AfterBest` keeps only epochs from the best one on, where further training no longer helps validation.
+	*/
+	static gaps(train, validation, goal, shading, best) {
+		if (shading === OverfitShading.None) return [];
+		const sign = goal === MetricGoal.Minimize ? 1 : -1;
+		const trained = new Map(train.map((stat) => [stat.epoch, stat.center]));
+		const shared = validation.flatMap(({ epoch, center }) => {
+			const value = trained.get(epoch);
+			return value === void 0 || shading === OverfitShading.AfterBest && (best === null || epoch < best) ? [] : [{
+				epoch,
+				train: value,
+				validation: center
+			}];
+		});
+		const excess = (point) => sign * (point.validation - point.train);
+		const stretches = [];
+		let open = [];
+		shared.forEach((point, i) => {
+			const before = shared[i - 1];
+			if (before && excess(before) > 0 !== excess(point) > 0) {
+				const share = excess(before) / (excess(before) - excess(point));
+				const level = before.train + share * (point.train - before.train);
+				const crossing = {
+					epoch: before.epoch + share * (point.epoch - before.epoch),
+					train: level,
+					validation: level
+				};
+				if (excess(point) > 0) open = [crossing];
+				else {
+					stretches.push([...open, crossing]);
+					open = [];
+				}
+			}
+			if (excess(point) > 0) open.push(point);
+		});
+		if (open.length) stretches.push(open);
+		return stretches.filter((stretch) => stretch.length > 1);
+	}
+	/** Lowest value a log axis or a non-negative metric lets a band reach: `undefined` when nothing bounds it. */
+	static floor(values, logarithmic) {
+		if (logarithmic) return min(values.filter((value) => value > 0));
+		return min(values) >= 0 ? 0 : void 0;
+	}
+};
+export { LearningCurveMath };

package/dist/charts/mlcharts/PartialDependence.js

@@ -0,0 +1,92 @@
+import { BarRows } from "../bars/BarRows.js";
+import { ascending, mean } from "d3";
+// src/charts/mlcharts/PartialDependence.ts
+var PLOTTING_POSITION = .4;
+/** Where a model is evaluated: evenly across the value range, or at evenly spaced quantiles. */
+var PartialDependenceGrid = /* @__PURE__ */ function(PartialDependenceGrid) {
+	PartialDependenceGrid["Uniform"] = "uniform";
+	PartialDependenceGrid["Quantile"] = "quantile";
+	return PartialDependenceGrid;
+}({});
+/** The partial dependence calculation of Friedman (2001) with ICE curves (Goldstein et al. 2015). */
+var PartialDependence = class PartialDependence {
+	grid;
+	curves;
+	observed;
+	/** The average at each grid value, over the instances predicted there. */
+	average;
+	constructor(grid, curves, observed) {
+		this.grid = grid;
+		this.curves = curves;
+		this.observed = observed;
+		this.average = grid.flatMap((x, i) => {
+			const values = curves.flatMap((curve) => curve.values[i] ?? []);
+			return values.length ? [{
+				x,
+				y: mean(values),
+				instances: values.length
+			}] : [];
+		});
+	}
+	/** The Cunnane quantile of `scipy.stats.mstats.mquantiles` with its default plotting positions, which `partial_dependence` uses. */
+	static quantile(sorted, p) {
+		const n = sorted.length, position = n * p + PLOTTING_POSITION + p * (1 - 2 * PLOTTING_POSITION);
+		const k = Math.floor(Math.min(n - 1, Math.max(1, position))), share = Math.min(1, Math.max(0, position - k));
+		return (1 - share) * sorted[k - 1] + share * sorted[k];
+	}
+	/**
+	* Grid values as scikit-learn's `_grid_from_X`: the distinct values when there are fewer than `points`,
+	* otherwise `points` steps between the `range` quantiles of the data. The Quantile method is this library's.
+	*/
+	static gridOf(values, { method, points, range }) {
+		const sorted = [...values].sort(ascending), distinct = [...new Set(sorted)];
+		const count = Math.max(2, Math.floor(points) || 2);
+		if (distinct.length < count || sorted.length < 2) return distinct;
+		const at = (p) => this.quantile(sorted, p);
+		const [from, to] = [Math.min(...range), Math.max(...range)];
+		const steps = Array.from({ length: count }, (_, i) => i / (count - 1));
+		const grid = method === "quantile" ? steps.map((t) => at(from + (to - from) * t)) : steps.map((t) => at(from) + (at(to) - at(from)) * t);
+		return [...new Set(grid)];
+	}
+	/** From a `predict` callback: every row is swept across the grid with the feature overwritten and the rest held. */
+	static fromModel(rows, x, predict, grid) {
+		const observed = rows.flatMap((row) => BarRows.number(row[x]) ?? []);
+		const axis = this.gridOf(observed, grid);
+		const curves = rows.map((row, i) => ({
+			instance: String(i + 1),
+			values: axis.map((value) => BarRows.number(predict({
+				...row,
+				[x]: value
+			})))
+		}));
+		return new PartialDependence(axis, curves, observed.sort(ascending));
+	}
+	/** From rows that already hold predictions, one per instance and grid value. Repeats of a pair are averaged. */
+	static fromPredictions(rows, { x, y, instance, observed }) {
+		const sweeps = /* @__PURE__ */ new Map(), seen = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const at = BarRows.number(row[x]), value = BarRows.number(row[y]), id = BarRows.label(row[instance]);
+			if (at === null || value === null) continue;
+			const sweep = sweeps.get(id) ?? sweeps.set(id, /* @__PURE__ */ new Map()).get(id);
+			sweep.set(at, [...sweep.get(at) ?? [], value]);
+			const feature = BarRows.number(row[observed]);
+			if (feature !== null && !seen.has(id)) seen.set(id, feature);
+		}
+		const grid = [...new Set([...sweeps.values()].flatMap((sweep) => [...sweep.keys()]))].sort(ascending);
+		const curves = [...sweeps].map(([id, sweep]) => ({
+			instance: id,
+			values: grid.map((at) => mean(sweep.get(at) ?? []) ?? null)
+		}));
+		return new PartialDependence(grid, curves, [...seen.values()].sort(ascending));
+	}
+	/** Centred ICE: each curve minus its value at the lowest grid value every instance reaches. */
+	centered() {
+		const index = Math.max(0, this.grid.findIndex((_, i) => this.curves.every((curve) => curve.values[i] !== null)));
+		const curves = this.curves.filter((curve) => curve.values[index] !== null).map(({ instance, values }) => ({
+			instance,
+			values: values.map((value) => value === null ? null : value - values[index])
+		}));
+		return new PartialDependence(this.grid, curves, this.observed);
+	}
+};
+export { PartialDependence, PartialDependenceGrid };

package/dist/charts/mlcharts/PartialDependencePlot.js

@@ -0,0 +1,225 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { TrendHover } from "../linesareas/TrendHover.js";
+import { DistinctTicks } from "./DistinctTicks.js";
+import { ExplainabilitySamples } from "./ExplainabilitySamples.js";
+import { PartialDependence, PartialDependenceGrid } from "./PartialDependence.js";
+import { extent, format, line, max, quantileSorted, scaleLinear } from "d3";
+// src/charts/mlcharts/PartialDependencePlot.ts
+/** Which curves are drawn: the names follow scikit-learn's `kind`. */
+var PartialDependenceKind = /* @__PURE__ */ function(PartialDependenceKind) {
+	PartialDependenceKind["Both"] = "both";
+	PartialDependenceKind["Average"] = "average";
+	PartialDependenceKind["Individual"] = "individual";
+	return PartialDependenceKind;
+}({});
+/** Ticks along the x axis showing where the feature has data. */
+var PartialDependenceRug = /* @__PURE__ */ function(PartialDependenceRug) {
+	PartialDependenceRug["Observations"] = "observations";
+	PartialDependenceRug["Deciles"] = "deciles";
+	PartialDependenceRug["None"] = "none";
+	return PartialDependenceRug;
+}({});
+var AVERAGE = "Average (PDP)";
+var INDIVIDUAL = "Individual (ICE)";
+var RUG_HEIGHT = 8;
+var RUG_ROOM = 12;
+var RUG_LIMIT = 400;
+var DECILES = Array.from({ length: 9 }, (_, i) => (i + 1) / 10);
+var figure = format(".4~g");
+/**
+* Shows how a model's prediction moves with one numeric feature, others held at their observed
+* values: partial dependence (Friedman 2001) with ICE curves (Goldstein et al. 2015). Pass rows of
+* precomputed predictions, or background rows and `predict`. Curves that fan or cross mean the
+* average hides an interaction, and any PDP is unreliable where the rug is empty or the feature
+* is correlated with others (Apley & Zhu 2020). The axis spans the grid, so `gridRange` keeps outliers off it.
+*/
+var PartialDependencePlot = class extends CartesianChart {
+	static meta = {
+		id: "partial-dependence",
+		name: "Partial dependence plot",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Shows a model's average prediction across one feature, with individual conditional expectation curves and a rug of the data.",
+		tags: [
+			"machine learning",
+			"explainability",
+			"pdp",
+			"ice",
+			"marginal effect"
+		],
+		sample: (seed) => ExplainabilitySamples.iceCurves(seed),
+		variants: {
+			kind: Object.values(PartialDependenceKind),
+			centered: [false, true],
+			rug: Object.values(PartialDependenceRug)
+		}
+	};
+	#cache = null;
+	#titled = "";
+	defaults() {
+		return {
+			x: "x",
+			y: "prediction",
+			instance: "instance",
+			observed: "observed",
+			gridMethod: PartialDependenceGrid.Uniform,
+			gridPoints: 50,
+			gridRange: [.05, .95],
+			kind: "both",
+			centered: false,
+			rug: "observations",
+			maxCurves: 80
+		};
+	}
+	render() {
+		const { yLabel, centered } = this.options;
+		if (yLabel === void 0 || yLabel === this.#titled) this.options = {
+			...this.options,
+			yLabel: this.#titled = centered ? "Change in prediction" : "Prediction"
+		};
+		return super.render();
+	}
+	/** Sweeping rows through a model is costly, and zoom and resize repaint without changing it. */
+	get model() {
+		const { data, x, y, instance, observed, predict, gridMethod, gridPoints, gridRange, centered } = this.options;
+		const rows = Array.isArray(data) ? data.filter(Boolean) : [];
+		const key = [
+			data,
+			rows.length,
+			x,
+			y,
+			instance,
+			observed,
+			predict,
+			gridMethod,
+			gridPoints,
+			gridRange?.[0],
+			gridRange?.[1],
+			centered
+		];
+		if (this.#cache?.key.every((value, i) => value === key[i])) return this.#cache.model;
+		const base = predict ? PartialDependence.fromModel(rows, x, predict, {
+			method: gridMethod,
+			points: gridPoints,
+			range: gridRange
+		}) : PartialDependence.fromPredictions(rows, {
+			x,
+			y,
+			instance,
+			observed
+		});
+		const model = centered ? base.centered() : base;
+		this.#cache = {
+			key,
+			model
+		};
+		return model;
+	}
+	get drawnCurves() {
+		const { curves } = this.model;
+		if (this.options.kind === "average") return [];
+		const limit = Math.max(1, Math.floor(this.options.maxCurves) || 1);
+		if (curves.length <= limit) return curves;
+		return Array.from({ length: limit }, (_, i) => curves[Math.floor(i * curves.length / limit)]);
+	}
+	get rugValues() {
+		const { observed, grid } = this.model, { rug } = this.options;
+		if (rug === "none" || !observed.length || !grid.length) return [];
+		const within = (value) => value >= grid[0] && value <= grid.at(-1);
+		if (rug === "deciles") return DECILES.map((p) => quantileSorted(observed, p)).filter(within);
+		const kept = observed.filter(within), stride = Math.max(1, kept.length / RUG_LIMIT);
+		return Array.from({ length: Math.min(kept.length, RUG_LIMIT) }, (_, i) => kept[Math.floor(i * stride)]);
+	}
+	table() {
+		return {
+			columns: [
+				this.options.x,
+				"partial_dependence",
+				"instances"
+			],
+			rows: this.model.average.map((point) => [
+				point.x,
+				point.y,
+				point.instances
+			])
+		};
+	}
+	tickFormat(scale) {
+		const base = super.tickFormat(scale);
+		if (!base) return base;
+		const fine = scale;
+		return (max(fine.domain(), Math.abs) ?? 0) < 10 ? (value) => fine.tickFormat(this.xTicks())(+value) : DistinctTicks.format(scale, base);
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot;
+		const { grid, average } = this.model;
+		const showAverage = this.options.kind !== "individual";
+		const heights = [...this.drawnCurves.flatMap((curve) => curve.values.flatMap((value) => value ?? [])), ...showAverage ? average.map((point) => point.y) : []];
+		const [left = 0, right = 1] = extent(grid);
+		const [low = 0, high = 1] = extent(heights);
+		const room = this.options.rug === "none" ? 0 : RUG_ROOM;
+		return {
+			x: scaleLinear().domain(left === right ? [left - 1, right + 1] : [left, right]).range([0, width]),
+			y: scaleLinear().domain(low === high ? [low - 1, high + 1] : [low, high]).nice().range([height - room, 0])
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { kind, centered } = this.options, { grid, average } = this.model;
+		const showAverage = kind !== "individual", showCurves = kind !== "average";
+		const averageInk = showAverage && average.length ? ctx.palette.color(AVERAGE) : "";
+		const curveInk = showCurves && average.length ? ctx.palette.color(INDIVIDUAL) : "";
+		const trace = line().defined((value) => value !== null).x((_, i) => axes.x(grid[i])).y((value) => axes.y(value));
+		const path = line().x((point) => axes.x(point.x)).y((point) => axes.y(point.y));
+		this.drawAnchor(ctx, axes, centered);
+		this.drawRug(ctx, axes);
+		const curves = ctx.marks("ice", "path", this.drawnCurves, (curve) => curve.instance).attr("fill", "none").attr("stroke", curveInk).attr("stroke-width", 1).attr("stroke-opacity", showAverage ? .32 : .5).attr("pointer-events", "none");
+		ctx.set(curves, { d: (curve) => trace(curve.values) }, { d: (curve) => trace(curve.values) });
+		const lines = showAverage && average.length > 1 ? [average] : [];
+		const halo = ctx.marks("average-halo", "path", lines).attr("fill", "none").attr("stroke", ctx.theme.surface).attr("stroke-width", 5).attr("stroke-linejoin", "round").attr("pointer-events", "none");
+		const stroke = ctx.marks("average", "path", lines).attr("fill", "none").attr("stroke", averageInk).attr("stroke-width", 2).attr("stroke-linecap", "round").attr("stroke-linejoin", "round").attr("pointer-events", "none");
+		ctx.set(halo, { d: (points) => path(points) }, { d: (points) => path(points) });
+		stroke.filter(function() {
+			return !this.getAttribute("d");
+		}).attr("d", (points) => path(points));
+		ctx.drawOn(stroke);
+		ctx.set(stroke, { d: (points) => path(points) });
+		const lone = ctx.marks("lone-point", "circle", showAverage && average.length === 1 ? average : []).attr("fill", averageInk).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(lone, {
+			cx: (point) => axes.x(point.x),
+			cy: (point) => axes.y(point.y),
+			r: 5
+		});
+		TrendHover.attach(ctx, average.map((point) => ({
+			x: axes.x(point.x),
+			title: `${this.options.xLabel ?? this.options.x} ${figure(point.x)}`,
+			rows: [["Average", figure(point.y)], ["Instances", point.instances]],
+			marks: showAverage ? [{
+				x: axes.x(point.x),
+				y: axes.y(point.y),
+				color: averageInk
+			}] : []
+		})), ctx.plot.width, ctx.plot.height);
+	}
+	drawAnchor(ctx, axes, centered) {
+		const rule = ctx.marks("anchor", "line", centered && this.model.curves.length ? [0] : []).attr("stroke", ctx.theme.axis).attr("stroke-width", 1).attr("stroke-dasharray", "4 3");
+		ctx.set(rule, {
+			x1: 0,
+			x2: ctx.plot.width,
+			y1: axes.y(0),
+			y2: axes.y(0)
+		});
+	}
+	drawRug(ctx, axes) {
+		const { height } = ctx.plot, deciles = this.options.rug === "deciles";
+		const ticks = ctx.marks("rug", "line", this.rugValues).attr("stroke", ctx.theme.inkSecondary).attr("stroke-width", deciles ? 2 : 1).attr("stroke-opacity", deciles ? 1 : .55).attr("pointer-events", "none");
+		ctx.set(ticks, {
+			x1: (value) => axes.x(value),
+			x2: (value) => axes.x(value),
+			y1: height,
+			y2: height - RUG_HEIGHT
+		});
+	}
+};
+export { PartialDependenceKind, PartialDependencePlot, PartialDependenceRug };