@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/statistics/SilhouettePlot.js

@@ -0,0 +1,217 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { StatisticalChart } from "./StatisticalChart.js";
+import { ascending, descending, group, mean } from "d3";
+// src/charts/statistics/SilhouettePlot.ts
+/** Distance used to compare observations. */
+var SilhouetteDistance = /* @__PURE__ */ function(SilhouetteDistance) {
+	SilhouetteDistance["Euclidean"] = "euclidean";
+	SilhouetteDistance["Manhattan"] = "manhattan";
+	SilhouetteDistance["Chebyshev"] = "chebyshev";
+	return SilhouetteDistance;
+}({});
+/** Order of observations within each cluster. */
+var SilhouetteOrder = /* @__PURE__ */ function(SilhouetteOrder) {
+	SilhouetteOrder["Descending"] = "descending";
+	SilhouetteOrder["Ascending"] = "ascending";
+	SilhouetteOrder["Input"] = "input-order";
+	return SilhouetteOrder;
+}({});
+/** How silhouette widths are drawn. */
+var SilhouetteMarks = /* @__PURE__ */ function(SilhouetteMarks) {
+	SilhouetteMarks["Knife"] = "knife";
+	SilhouetteMarks["Bars"] = "bars";
+	return SilhouetteMarks;
+}({});
+var measure = {
+	["euclidean"]: (a, b) => Math.sqrt(a.reduce((total, v, i) => total + (v - b[i]) ** 2, 0)),
+	["manhattan"]: (a, b) => a.reduce((total, v, i) => total + Math.abs(v - b[i]), 0),
+	["chebyshev"]: (a, b) => a.reduce((most, v, i) => Math.max(most, Math.abs(v - b[i])), 0)
+};
+/** Judges a clustering: each point's fit to its own cluster against the nearest other one, cluster by cluster. */
+var SilhouettePlot = class extends StatisticalChart {
+	static meta = {
+		id: "silhouette-plot",
+		name: "Silhouette plot",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Shows how well each observation fits its assigned cluster, to choose and validate a clustering.",
+		tags: [
+			"clustering",
+			"k-means",
+			"cluster validation",
+			"machine learning"
+		],
+		sample: (seed) => SampleData.points(seed, 54, 3),
+		variants: {
+			distance: Object.values(SilhouetteDistance),
+			order: Object.values(SilhouetteOrder),
+			marks: Object.values(SilhouetteMarks),
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			meanLine: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			features: ["x", "y"],
+			group: "group",
+			distance: "euclidean",
+			order: "descending",
+			marks: "knife",
+			orientation: Orientation.Horizontal,
+			meanLine: true
+		};
+	}
+	get flat() {
+		return this.options.orientation === Orientation.Horizontal;
+	}
+	axisTitles() {
+		return this.flat ? {
+			x: "Silhouette width",
+			y: "Observations by cluster"
+		} : {
+			x: "Observations by cluster",
+			y: "Silhouette width"
+		};
+	}
+	bars() {
+		const { data, features, group: field, distance, order } = this.options;
+		const points = this.complete(data, ...features).map((row, index) => ({
+			index,
+			cluster: String(row[field] ?? "All"),
+			at: features.map((name) => +row[name])
+		}));
+		const clusters = [...group(points, (d) => d.cluster)];
+		const gap = 3, far = measure[distance];
+		let slot = 0;
+		return {
+			bars: clusters.flatMap(([cluster, members]) => {
+				const widths = members.map((d) => {
+					if (members.length < 2) return {
+						cluster,
+						index: d.index,
+						width: 0,
+						slot: 0
+					};
+					const own = mean(members.filter((m) => m !== d), (m) => far(d.at, m.at));
+					const other = Math.min(...clusters.filter(([name]) => name !== cluster).map(([, set]) => mean(set, (m) => far(d.at, m.at))));
+					const worst = Math.max(own, other);
+					return {
+						cluster,
+						index: d.index,
+						width: Number.isFinite(other) && worst ? (other - own) / worst : 0,
+						slot: 0
+					};
+				});
+				if (order !== "input-order") widths.sort((a, b) => (order === "descending" ? descending : ascending)(a.width, b.width));
+				const placed = widths.map((d) => ({
+					...d,
+					slot: slot++
+				}));
+				slot += gap;
+				return placed;
+			}),
+			slots: Math.max(1, slot - gap)
+		};
+	}
+	scales(ctx) {
+		const { bars, slots } = this.bars();
+		const domain = [Math.min(-.1, ...bars.map((d) => d.width)) * 1.05, 1];
+		const { width, height } = ctx.plot;
+		return this.flat ? {
+			x: this.linear(domain, [0, width]),
+			y: this.labelled(this.linear([-.5, slots - .5], [0, height]), [])
+		} : {
+			x: this.labelled(this.linear([-.5, slots - .5], [0, width]), []),
+			y: this.linear(domain, [height, 0])
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { marks, meanLine } = this.options;
+		const { bars } = this.bars(), flat = this.flat;
+		const widthScale = flat ? axes.x : axes.y, slotScale = flat ? axes.y : axes.x;
+		const at = (slot, width) => flat ? [widthScale(width), slotScale(slot)] : [slotScale(slot), widthScale(width)];
+		const color = (cluster) => ctx.palette.color(cluster);
+		const clusters = [...group(bars, (d) => d.cluster)];
+		const shape = ([, members]) => {
+			const edge = members.flatMap((d) => [at(d.slot - .5, d.width), at(d.slot + .5, d.width)]);
+			return `M${[
+				at(members[0].slot - .5, 0),
+				...edge,
+				at(members.at(-1).slot + .5, 0)
+			].join("L")}Z`;
+		};
+		const knives = ctx.marks("knives", "path", marks === "knife" ? clusters : [], ([cluster]) => cluster).attr("fill", ([cluster]) => color(cluster));
+		ctx.set(knives, { d: shape }, { d: shape });
+		ctx.hover(knives, ([cluster, members]) => ({
+			title: cluster,
+			color: color(cluster),
+			rows: [["Observations", members.length], ["Mean width", +mean(members, (d) => d.width).toFixed(3)]]
+		}));
+		const thick = Math.abs(slotScale(1) - slotScale(0));
+		const rects = ctx.marks("bars", "rect", marks === "bars" ? bars : [], (d) => d.index).attr("fill", (d) => color(d.cluster));
+		const inner = thick > 3 ? thick - 1 : thick;
+		const box = (d) => {
+			const [x0, y0] = at(d.slot, 0), [x1, y1] = at(d.slot, d.width);
+			return flat ? {
+				x: Math.min(x0, x1),
+				y: y0 - inner / 2,
+				width: Math.abs(x1 - x0),
+				height: inner
+			} : {
+				x: x0 - inner / 2,
+				y: Math.min(y0, y1),
+				width: inner,
+				height: Math.abs(y1 - y0)
+			};
+		};
+		ctx.set(rects, {
+			x: (d) => box(d).x,
+			y: (d) => box(d).y,
+			width: (d) => box(d).width,
+			height: (d) => box(d).height
+		});
+		ctx.hover(rects, (d) => ({
+			title: `Observation ${d.index + 1}`,
+			color: color(d.cluster),
+			rows: [[d.cluster, +d.width.toFixed(3)]]
+		}));
+		const [start, end] = slotScale.domain();
+		const line = ctx.marks("zero", "line", [0]).attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		ctx.set(line, {
+			x1: at(start, 0)[0],
+			y1: at(start, 0)[1],
+			x2: at(end, 0)[0],
+			y2: at(end, 0)[1]
+		});
+		const average = mean(bars, (d) => d.width) ?? 0;
+		const guide = ctx.marks("mean", "line", meanLine && bars.length ? [average] : []).attr("stroke", ctx.theme.ink).attr("stroke-width", 1.5).attr("stroke-dasharray", "5 4");
+		ctx.set(guide, {
+			x1: (d) => at(start, d)[0],
+			y1: (d) => at(start, d)[1],
+			x2: (d) => at(end, d)[0],
+			y2: (d) => at(end, d)[1]
+		});
+		this.notes(ctx, "mean-label", meanLine && bars.length ? [{
+			key: "mean",
+			text: `Mean ${average.toFixed(2)}`,
+			x: flat ? widthScale(average) + 5 : ctx.plot.width - 4,
+			y: flat ? 12 : widthScale(average) - 5,
+			anchor: flat ? "start" : "end",
+			tone: "ink"
+		}] : []);
+		const names = clusters.map(([cluster, members]) => {
+			const middle = (members[0].slot + members.at(-1).slot) / 2;
+			return {
+				key: cluster,
+				text: cluster,
+				x: flat ? widthScale(0) - 6 : slotScale(middle),
+				y: flat ? slotScale(middle) + 4 : widthScale(0) + 14,
+				anchor: flat ? "end" : "middle"
+			};
+		});
+		this.notes(ctx, "cluster-names", names);
+	}
+};
+export { SilhouetteDistance, SilhouetteMarks, SilhouetteOrder, SilhouettePlot };

package/dist/charts/statistics/StatMath.js

@@ -0,0 +1,202 @@
+import { ascending, mean } from "d3";
+// src/charts/statistics/StatMath.ts
+var A = [
+	-39.69683028665376,
+	220.9460984245205,
+	-275.9285104469687,
+	138.357751867269,
+	-30.66479806614716,
+	2.506628277459239
+];
+var B = [
+	-54.47609879822406,
+	161.5858368580409,
+	-155.6989798598866,
+	66.80131188771972,
+	-13.28068155288572
+];
+var C = [
+	-.007784894002430293,
+	-.3223964580411365,
+	-2.400758277161838,
+	-2.549732539343734,
+	4.374664141464968,
+	2.938163982698783
+];
+var D = [
+	.007784695709041462,
+	.3224671290700398,
+	2.445134137142996,
+	3.754408661907416
+];
+var horner = (coefficients, x) => coefficients.reduce((sum, c) => sum * x + c, 0);
+/** Distribution functions and time-series estimators shared by the statistics charts. */
+var StatMath = class StatMath {
+	static normalPdf(z) {
+		return Math.exp(-.5 * z * z) / Math.sqrt(2 * Math.PI);
+	}
+	/** Complementary error function, accurate into the far tails that p-value charts need. */
+	static erfc(x) {
+		const z = Math.abs(x), t = 1 / (1 + .5 * z);
+		const r = t * Math.exp(-z * z + horner([
+			.17087277,
+			-.82215223,
+			1.48851587,
+			-1.13520398,
+			.27886807,
+			-.18628806,
+			.09678418,
+			.37409196,
+			1.00002368,
+			-1.26551223
+		], t));
+		return x >= 0 ? r : 2 - r;
+	}
+	static normalCdf(z) {
+		return .5 * StatMath.erfc(-z / Math.SQRT2);
+	}
+	/** Two-sided p-value of a z statistic. */
+	static twoSided(z) {
+		return StatMath.erfc(Math.abs(z) / Math.SQRT2);
+	}
+	/** Inverse normal CDF (Acklam's rational approximation). */
+	static normalQuantile(p) {
+		if (p <= 0) return -Infinity;
+		if (p >= 1) return Infinity;
+		if (p < .02425) {
+			const q = Math.sqrt(-2 * Math.log(p));
+			return horner(C, q) / (horner(D, q) * q + 1);
+		}
+		if (p > .97575) {
+			const q = Math.sqrt(-2 * Math.log(1 - p));
+			return -horner(C, q) / (horner(D, q) * q + 1);
+		}
+		const q = p - .5, r = q * q;
+		return horner(A, r) * q / (horner(B, r) * r + 1);
+	}
+	/** Student t quantile: exact for 1 and 2 df, Cornish-Fisher above. */
+	static tQuantile(p, df) {
+		if (df === 1) return Math.tan(Math.PI * (p - .5));
+		if (df === 2) return (2 * p - 1) * Math.sqrt(2 / (4 * p * (1 - p)));
+		const z = StatMath.normalQuantile(p), z3 = z ** 3, z5 = z ** 5, z7 = z ** 7, z9 = z ** 9;
+		return z + (z3 + z) / (4 * df) + (5 * z5 + 16 * z3 + 3 * z) / (96 * df ** 2) + (3 * z7 + 19 * z5 + 17 * z3 - 15 * z) / (384 * df ** 3) + (79 * z9 + 776 * z7 + 1482 * z5 - 1920 * z3 - 945 * z) / (92160 * df ** 4);
+	}
+	/** Wilson score interval for a binomial proportion. */
+	static wilson(successes, trials, z = 1.96) {
+		if (!trials) return [0, 1];
+		const p = successes / trials, n = trials, z2 = z * z, centre = p + z2 / (2 * n);
+		const spread = z * Math.sqrt(p * (1 - p) / n + z2 / (4 * n * n)), scale = 1 + z2 / n;
+		return [Math.max(0, (centre - spread) / scale), Math.min(1, (centre + spread) / scale)];
+	}
+	/** Locally weighted linear regression evaluated at each distinct x. */
+	static lowess(points, span = .66) {
+		const sorted = [...points].sort((a, b) => ascending(a[0], b[0]));
+		const reach = Math.max(2, Math.ceil(span * sorted.length));
+		const seen = /* @__PURE__ */ new Set();
+		return sorted.filter(([x]) => !seen.has(x) && !!seen.add(x)).map(([at]) => {
+			const nearest = sorted.map(([x, y]) => [
+				Math.abs(x - at),
+				x,
+				y
+			]).sort((a, b) => a[0] - b[0]).slice(0, reach);
+			const h = nearest.at(-1)[0] || 1;
+			let sw = 0, sx = 0, sy = 0, sxx = 0, sxy = 0;
+			for (const [d, x, y] of nearest) {
+				const w = (1 - (d / h) ** 3) ** 3 + 1e-9;
+				sw += w;
+				sx += w * x;
+				sy += w * y;
+				sxx += w * x * x;
+				sxy += w * x * y;
+			}
+			const denominator = sw * sxx - sx * sx;
+			const slope = Math.abs(denominator) < 1e-12 ? 0 : (sw * sxy - sx * sy) / denominator;
+			return [at, (sy - slope * sx) / sw + slope * at];
+		});
+	}
+	/** Sample autocorrelation at lags 0..maxLag. */
+	static acf(series, maxLag) {
+		return StatMath.ccf(series, series, 0, maxLag);
+	}
+	/** Sample cross-correlation of `a` leading `b`, for lags from..to. */
+	static ccf(a, b, from, to) {
+		const n = Math.min(a.length, b.length), ma = mean(a) ?? 0, mb = mean(b) ?? 0;
+		let sa = 0, sb = 0;
+		for (let i = 0; i < n; i++) {
+			sa += (a[i] - ma) ** 2;
+			sb += (b[i] - mb) ** 2;
+		}
+		const scale = Math.sqrt(sa * sb) || 1;
+		return Array.from({ length: to - from + 1 }, (_, k) => {
+			const lag = from + k;
+			let total = 0;
+			for (let i = Math.max(0, -lag); i < n - Math.max(0, lag); i++) total += (a[i] - ma) * (b[i + lag] - mb);
+			return total / scale;
+		});
+	}
+	/** Partial autocorrelation at lags 1..maxLag from the autocorrelations (Durbin-Levinson). */
+	static pacfYuleWalker(rho) {
+		const out = [];
+		let phi = [];
+		for (let k = 1; k < rho.length; k++) {
+			const top = rho[k] - phi.reduce((sum, c, j) => sum + c * rho[k - 1 - j], 0);
+			const bottom = 1 - phi.reduce((sum, c, j) => sum + c * rho[j + 1], 0);
+			const reflection = Math.abs(bottom) < 1e-12 ? 0 : top / bottom;
+			phi = [...phi.map((c, j) => c - reflection * phi[k - 2 - j]), reflection];
+			out.push(reflection);
+		}
+		return out;
+	}
+	/** Partial autocorrelation at lags 1..maxLag as Burg reflection coefficients. */
+	static pacfBurg(series, maxLag) {
+		const centre = mean(series) ?? 0;
+		let forward = series.map((value) => value - centre), backward = [...forward];
+		return Array.from({ length: maxLag }, () => {
+			const f = forward.slice(1), b = backward.slice(0, -1);
+			const top = 2 * f.reduce((sum, value, i) => sum + value * b[i], 0);
+			const bottom = f.reduce((sum, value, i) => sum + value * value + b[i] * b[i], 0);
+			const reflection = bottom ? top / bottom : 0;
+			forward = f.map((value, i) => value - reflection * b[i]);
+			backward = b.map((value, i) => value - reflection * f[i]);
+			return reflection;
+		});
+	}
+	/** Benjamini-Hochberg adjusted p-values, in input order. */
+	static benjaminiHochberg(values) {
+		const order = values.map((_, i) => i).sort((a, b) => values[b] - values[a]);
+		const out = new Array(values.length);
+		let lowest = 1;
+		order.forEach((index, rank) => {
+			lowest = Math.min(lowest, values[index] * values.length / (values.length - rank));
+			out[index] = lowest;
+		});
+		return out;
+	}
+	/** Eigenvalues of a symmetric matrix, largest first (cyclic Jacobi rotations). */
+	static eigenvalues(matrix) {
+		const a = matrix.map((row) => [...row]), n = a.length;
+		for (let sweep = 0; sweep < 60; sweep++) {
+			let off = 0;
+			for (let p = 0; p < n; p++) for (let q = p + 1; q < n; q++) off += a[p][q] ** 2;
+			if (off < 1e-12) break;
+			for (let p = 0; p < n; p++) for (let q = p + 1; q < n; q++) {
+				if (Math.abs(a[p][q]) < 1e-14) continue;
+				const theta = (a[q][q] - a[p][p]) / (2 * a[p][q]);
+				const t = Math.sign(theta || 1) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
+				const c = 1 / Math.sqrt(t * t + 1), s = t * c;
+				for (let k = 0; k < n; k++) {
+					const x = a[k][p], y = a[k][q];
+					a[k][p] = c * x - s * y;
+					a[k][q] = s * x + c * y;
+				}
+				for (let k = 0; k < n; k++) {
+					const x = a[p][k], y = a[q][k];
+					a[p][k] = c * x - s * y;
+					a[q][k] = s * x + c * y;
+				}
+			}
+		}
+		return a.map((row, i) => row[i]).sort((x, y) => y - x);
+	}
+};
+export { StatMath };

package/dist/charts/statistics/StatisticalChart.js

@@ -0,0 +1,197 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { Scales } from "../../core/Scales.js";
+import { StatMath } from "./StatMath.js";
+import { area, line, scaleLinear, scaleLog } from "d3";
+// src/charts/statistics/StatisticalChart.ts
+/** Width of a label at 11px. */
+var textWidth = (text) => text.length * 6.2;
+/** Marks shared by every statistical plot: traces, ribbons, dots, reference rules and notes on numeric axes. */
+var StatisticalChart = class extends CartesianChart {
+	titled = {};
+	/** Default axis titles, which can depend on the variant. A title passed by the user wins. */
+	axisTitles() {
+		return {};
+	}
+	render() {
+		const titles = this.axisTitles(), given = this.options;
+		const xLabel = given.xLabel === void 0 || given.xLabel === this.titled.x ? titles.x : given.xLabel;
+		const yLabel = given.yLabel === void 0 || given.yLabel === this.titled.y ? titles.y : given.yLabel;
+		this.titled = titles;
+		this.options = {
+			...given,
+			xLabel,
+			yLabel
+		};
+		return super.render();
+	}
+	/** Reads a numeric cell, treating nulls, blanks and non-numbers as missing. */
+	number(cell) {
+		if (cell === null || cell === void 0 || cell === "") return null;
+		const value = +cell;
+		return Number.isFinite(value) ? value : null;
+	}
+	/** The option's rows, keeping only those with a finite number in every field. */
+	complete(rows, ...fields) {
+		return (rows ?? []).filter((row) => fields.every((field) => this.number(row[field]) !== null));
+	}
+	/** Domain of `values` with fractional padding and a usable fallback for empty or flat data. */
+	span(values, pad = .06) {
+		const finite = values.filter(Number.isFinite);
+		if (!finite.length) return [0, 1];
+		const low = Math.min(...finite), high = Math.max(...finite), reach = high - low || Math.abs(high) || 1;
+		return [low - reach * pad, high + reach * pad];
+	}
+	linear(domain, range) {
+		return scaleLinear(domain, range);
+	}
+	/** Log axis ticked at 1-2-5 stops, or decades alone when those would crowd it. */
+	logarithmic(domain, range) {
+		const scale = scaleLog(domain, range).clamp(true);
+		const first = Math.floor(Math.log10(domain[0])), last = Math.ceil(Math.log10(domain[1]));
+		const decades = Array.from({ length: last - first + 1 }, (_, i) => 10 ** (first + i));
+		const inside = (value) => value >= domain[0] * .999 && value <= domain[1] * 1.001;
+		const stops = decades.flatMap((decade) => [
+			decade,
+			2 * decade,
+			5 * decade
+		]).filter(inside);
+		return Object.assign(scale, { ticks: () => stops.length <= 7 ? stops : decades.filter(inside) });
+	}
+	/** Normal-deviate axis for probabilities: straight lines for binormal data. */
+	probit(domain, range) {
+		const z = scaleLinear(domain.map(StatMath.normalQuantile), range).clamp(true);
+		const stops = [
+			.001,
+			.002,
+			.005,
+			.01,
+			.02,
+			.05,
+			.1,
+			.2,
+			.4,
+			.6,
+			.8,
+			.9,
+			.95,
+			.98,
+			.99,
+			.995,
+			.999
+		];
+		const scale = ((value) => z(StatMath.normalQuantile(value)));
+		return Object.assign(scale, {
+			probit: true,
+			domain: () => [...domain],
+			range: () => [...range],
+			copy: () => scale,
+			ticks: () => {
+				const inside = stops.filter((p) => p >= domain[0] && p <= domain[1]);
+				return inside.filter((_, i) => inside.length < 8 || i % 2 === 0);
+			}
+		});
+	}
+	/** A scale whose ticks are named stops, for categories and chromosomes on a numeric axis. */
+	labelled(scale, stops) {
+		return Object.assign(scale, {
+			stops,
+			ticks: () => stops.map((stop) => stop[0])
+		});
+	}
+	tickFormat(scale) {
+		if ("stops" in scale) {
+			const names = new Map(scale.stops);
+			return (value) => names.get(+value) ?? "";
+		}
+		if ("probit" in scale) return (value) => `${+(+value * 100).toFixed(1)}%`;
+		if ("base" in scale) return (value) => `${+(+value).toPrecision(2)}`;
+		const domain = scale.domain?.() ?? [];
+		if (typeof domain[0] === "number" && Math.max(...domain.map(Math.abs)) < .1) return (value) => (+value).toPrecision(2).replace(/\.?0+$/, "");
+		return super.tickFormat(scale);
+	}
+	scaleX(axes) {
+		return (value) => axes.x(value);
+	}
+	scaleY(axes) {
+		return (value) => axes.y(value);
+	}
+	traces(ctx, name, specs, axes) {
+		const fx = this.scaleX(axes), fy = this.scaleY(axes);
+		const shape = (spec) => line((d) => fx(d[0]), (d) => fy(d[1])).curve(Scales.curve(spec.curve))(spec.points);
+		const paths = ctx.marks(name, "path", specs, (spec) => spec.key).attr("fill", "none").attr("stroke", (spec) => spec.color).attr("stroke-width", (spec) => spec.width ?? 2).attr("stroke-dasharray", (spec) => spec.dash ?? null).attr("stroke-linejoin", "round").attr("stroke-linecap", "round");
+		ctx.set(paths, { d: shape }, { d: shape });
+		ctx.drawOn(paths);
+		ctx.hover(paths, (spec) => spec.tip ?? {
+			title: spec.key,
+			color: spec.color
+		});
+	}
+	ribbons(ctx, name, specs, axes) {
+		const fx = this.scaleX(axes), fy = this.scaleY(axes);
+		const shape = (spec) => area().x((d) => fx(d[0])).y0((d) => fy(d[1])).y1((d) => fy(d[2])).curve(Scales.curve(spec.curve))(spec.points);
+		const paths = ctx.marks(name, "path", specs, (spec) => spec.key).attr("fill", (spec) => spec.color).attr("fill-opacity", (spec) => spec.opacity ?? .16).attr("stroke", "none");
+		ctx.set(paths, { d: shape }, { d: shape });
+		paths.lower();
+	}
+	dots(ctx, name, data, at, color, tip, style = {}) {
+		const { r = 4, ring = data.length <= 60, opacity = ring ? 1 : .72, stagger = 0, key = (_, i) => i } = style;
+		const radius = (datum) => typeof r === "function" ? r(datum) : r;
+		const marks = ctx.marks(name, "circle", data, key).attr("fill", color).attr("fill-opacity", opacity).attr("stroke", ring ? ctx.theme.surface : "none").attr("stroke-width", ring ? 2 : 0);
+		const cx = (d) => at(d)[0], cy = (d) => at(d)[1];
+		ctx.set(marks, {
+			cx,
+			cy,
+			r: radius
+		}, {
+			cx,
+			cy,
+			r: 0
+		}, stagger);
+		ctx.hover(marks, tip);
+	}
+	rules(ctx, name, specs, axes) {
+		const fx = this.scaleX(axes), fy = this.scaleY(axes);
+		const lines = ctx.marks(name, "line", specs, (spec) => spec.key).attr("stroke", (spec) => spec.strong ? ctx.theme.inkSecondary : ctx.theme.inkMuted).attr("stroke-width", 1).attr("stroke-dasharray", (spec) => spec.dash ?? null);
+		ctx.set(lines, {
+			x1: (s) => fx(s.from[0]),
+			y1: (s) => fy(s.from[1]),
+			x2: (s) => fx(s.to[0]),
+			y2: (s) => fy(s.to[1])
+		});
+		lines.style("pointer-events", "none");
+	}
+	/** Text kept inside the plot by shifting it inward; earlier notes win where two would collide. */
+	notes(ctx, name, specs) {
+		const { width, height } = ctx.plot;
+		const left = (spec) => ({
+			start: 0,
+			middle: .5,
+			end: 1
+		})[spec.anchor ?? "start"] * textWidth(spec.text);
+		const x = (spec) => Math.max(left(spec), Math.min(width - textWidth(spec.text) + left(spec), spec.x));
+		const box = (spec) => {
+			const start = x(spec) - left(spec);
+			return [
+				start,
+				start + textWidth(spec.text),
+				spec.y
+			];
+		};
+		const placed = [];
+		for (const spec of specs) {
+			const [a0, a1, ay] = box(spec);
+			if (!placed.some((other) => {
+				const [b0, b1, by] = box(other);
+				return a0 < b1 + 2 && b0 < a1 + 2 && Math.abs(ay - by) < 12;
+			})) placed.push(spec);
+		}
+		const marks = ctx.marks(name, "text", placed, (spec) => spec.key).attr("text-anchor", (spec) => spec.anchor ?? "start").attr("x", x).attr("y", (spec) => Math.max(10, Math.min(height - 3, spec.y))).text((spec) => spec.text).attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").style("pointer-events", "none");
+		const fills = {
+			ink: ctx.theme.ink,
+			secondary: ctx.theme.inkSecondary,
+			muted: ctx.theme.inkMuted
+		};
+		ctx.text(marks).attr("fill", (spec) => fills[spec.tone ?? "secondary"]);
+	}
+};
+export { StatisticalChart, textWidth };