@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/multivariate/MultiDimensionalScaling.js

@@ -0,0 +1,93 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { MultivariateKit, ProjectionOverlay } from "./MultivariateKit.js";
+import { DistanceMetric, MultivariateMath } from "./MultivariateMath.js";
+import { MultivariateSample } from "./MultivariateSample.js";
+import { ProjectionChart } from "./ProjectionChart.js";
+import { WideNormal } from "./WideTable.js";
+// src/charts/multivariate/MultiDimensionalScaling.ts
+var ScalingMethod = /* @__PURE__ */ function(ScalingMethod) {
+	ScalingMethod["Classical"] = "classical";
+	ScalingMethod["Stress"] = "stress-majorisation";
+	return ScalingMethod;
+}({});
+/** Map observations so that similar ones sit close: for seeing clusters when axes carry no meaning of their own. */
+var MultiDimensionalScaling = class extends ProjectionChart {
+	static meta = {
+		id: "multidimensional-scaling",
+		name: "Multidimensional scaling",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Places observations in a plane so that on-screen distances approximate their pairwise distances across all measures.",
+		tags: [
+			"multivariate",
+			"mds",
+			"smacof",
+			"dimensionality reduction",
+			"similarity"
+		],
+		sample: (seed) => MultivariateSample.wide(seed),
+		variants: {
+			method: ["classical", "stress-majorisation"],
+			metric: [
+				DistanceMetric.Euclidean,
+				DistanceMetric.Manhattan,
+				DistanceMetric.Correlation
+			],
+			overlay: [
+				ProjectionOverlay.Points,
+				ProjectionOverlay.Hulls,
+				ProjectionOverlay.Contours
+			],
+			neighbours: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			group: "group",
+			method: "classical",
+			metric: DistanceMetric.Euclidean,
+			overlay: ProjectionOverlay.Points,
+			neighbours: false
+		};
+	}
+	distances = [];
+	fitness = 0;
+	embed(table, records) {
+		const standard = table.normalised(WideNormal.ZScore, records);
+		this.distances = MultivariateMath.distances(standard, this.options.metric);
+		const start = MultivariateMath.classicalScaling(this.distances);
+		const points = this.options.method === "stress-majorisation" ? MultivariateMath.stressMajorisation(this.distances, start) : start;
+		this.fitness = MultivariateMath.stress(this.distances, points);
+		return {
+			points,
+			xLabel: "Dimension 1",
+			yLabel: "Dimension 2"
+		};
+	}
+	annotate(ctx, { points }) {
+		const pairs = this.options.neighbours ? points.flatMap((point, i) => {
+			const row = this.distances[i];
+			const j = row.reduce((best, value, k) => k !== i && (best < 0 || value < row[best]) ? k : best, -1);
+			return j < 0 ? [] : [{
+				a: point,
+				b: points[j]
+			}];
+		}) : [];
+		const links = ctx.marks("links", "line", pairs, (d) => d.a.record.index).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1).attr("stroke-opacity", .7);
+		ctx.set(links, {
+			x1: (d) => d.a.x,
+			y1: (d) => d.a.y,
+			x2: (d) => d.b.x,
+			y2: (d) => d.b.y
+		});
+		ctx.root.select("g.m-links").lower();
+		const note = ctx.marks("stress", "text", [`stress ${this.fitness.toFixed(3)}`]).attr("text-anchor", "end").text((d) => d);
+		MultivariateKit.halo(ctx.text(note, 10, "muted"), ctx);
+		ctx.set(note, {
+			x: ctx.plot.width - 4,
+			y: 12
+		});
+	}
+};
+export { MultiDimensionalScaling, ScalingMethod };

package/dist/charts/multivariate/MultivariateKit.js

@@ -0,0 +1,168 @@
+import { Scales } from "../../core/Scales.js";
+import { MultivariateMath } from "./MultivariateMath.js";
+import { axisBottom, axisLeft, color, contourDensity, curveCatmullRomClosed, curveLinearClosed, geoPath, group, line, max } from "d3";
+// src/charts/multivariate/MultivariateKit.ts
+var ProjectionOverlay = /* @__PURE__ */ function(ProjectionOverlay) {
+	ProjectionOverlay["Points"] = "points";
+	ProjectionOverlay["Hulls"] = "hulls";
+	ProjectionOverlay["Ellipses"] = "ellipses";
+	ProjectionOverlay["Contours"] = "contours";
+	return ProjectionOverlay;
+}({});
+var PanelLayout = /* @__PURE__ */ function(PanelLayout) {
+	PanelLayout["Row"] = "row";
+	PanelLayout["Column"] = "column";
+	PanelLayout["Wrap"] = "wrap";
+	return PanelLayout;
+}({});
+var CHAR = .565;
+/** Drawing routines shared across the module, so charts stay about their own geometry. */
+var MultivariateKit = class {
+	/** Fits a label to `px`, or blanks it when even a stub would not fit. */
+	static trim(text, px, size = 11) {
+		const room = Math.floor(px / (size * CHAR));
+		if (text.length <= room) return text;
+		return room < 3 ? "" : `${text.slice(0, room - 1)}…`;
+	}
+	static tooltip(table, record, color, title = record.group) {
+		return {
+			title,
+			color,
+			rows: table.dimensions.map((name, i) => [name, Number.isFinite(record.values[i]) ? record.values[i] : "–"])
+		};
+	}
+	/** Surface-coloured halo so a label stays readable over marks. */
+	static halo(selection, ctx) {
+		return selection.attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").attr("stroke-linejoin", "round");
+	}
+	/** Ink for text on a filled mark, whatever colour notation the fill uses. */
+	static inkOn(ctx, fill) {
+		return ctx.palette.inkOn(color(fill)?.formatHex() ?? fill);
+	}
+	/** Recessive frame for an x/y panel: bottom axis, left labels, horizontal grid. */
+	static axes(ctx, x, y, frame) {
+		const { width, height, showX = true, showY = true, xTicks = Math.max(2, Math.floor(width / 70)), yTicks = Math.max(2, Math.floor(height / 36)) } = frame;
+		const { theme } = ctx;
+		const format = (scale) => {
+			const reach = max(scale.domain(), (value) => Math.abs(value)) ?? 0;
+			return (value) => Scales.format(+value, reach);
+		};
+		ctx.group("grid").lower().selectAll("line").data(y.ticks(yTicks)).join("line").attr("x1", 0).attr("x2", width).attr("y1", (tick) => y(tick)).attr("y2", (tick) => y(tick)).attr("stroke", theme.grid);
+		const bottom = ctx.group("axis-x").attr("transform", `translate(0,${height})`);
+		const left = ctx.group("axis-y");
+		if (showX) bottom.call(axisBottom(x).ticks(xTicks).tickSizeOuter(0).tickSize(3).tickFormat(format(x)));
+		ctx.marks("axis-floor", "line", showX ? [] : [width]).attr("x1", 0).attr("x2", width).attr("y1", height).attr("y2", height).attr("stroke", theme.axis);
+		if (showY) left.call(axisLeft(y).ticks(yTicks).tickSize(0).tickFormat(format(y)));
+		for (const axis of [bottom, left]) {
+			axis.selectAll(".tick line").attr("stroke", theme.axis);
+			axis.selectAll("text").attr("fill", theme.inkSecondary).attr("font-size", 10).attr("font-family", theme.fontFamily);
+		}
+		bottom.select(".domain").attr("stroke", theme.axis);
+		left.select(".domain").attr("stroke", "none");
+		const titles = [frame.xLabel && {
+			key: "x",
+			text: frame.xLabel,
+			transform: `translate(${width / 2},${height + 28})`
+		}, frame.yLabel && {
+			key: "y",
+			text: frame.yLabel,
+			transform: `translate(-32,${height / 2}) rotate(-90)`
+		}].filter(Boolean);
+		ctx.text(ctx.marks("axis-title", "text", titles, (d) => d.key).attr("text-anchor", "middle").attr("transform", (d) => d.transform).text((d) => d.text), 11);
+	}
+	/** Splits a rectangle into `count` panels with shared gutters. */
+	static panels(count, width, height, layout, gap = 10) {
+		const columns = layout === "column" ? 1 : layout === "row" ? count : Math.ceil(Math.sqrt(count * (width / Math.max(1, height)) * .8));
+		const cols = Math.max(1, Math.min(count, columns)), rows = Math.max(1, Math.ceil(count / cols));
+		const w = (width - gap * (cols - 1)) / cols, h = (height - gap * (rows - 1)) / rows;
+		return Array.from({ length: count }, (_, index) => {
+			const c = index % cols, r = Math.floor(index / cols);
+			return {
+				index,
+				x: c * (w + gap),
+				y: r * (h + gap),
+				width: w,
+				height: h,
+				left: c === 0,
+				bottom: r === rows - 1 || index + cols >= count
+			};
+		});
+	}
+	/** Group shapes under a cloud of points: hull, covariance ellipse or density contours. */
+	static overlay(ctx, points, overlay, bounds) {
+		const groups = [...group(points, (point) => point.record.group)];
+		const coords = (rows) => rows.map((p) => [p.x, p.y]);
+		const closed = (shape, smooth) => line().curve(smooth ? curveCatmullRomClosed : curveLinearClosed)(shape) ?? "";
+		if (overlay === "hulls" || overlay === "ellipses") {
+			const hulls = overlay === "hulls";
+			const shapes = groups.flatMap(([name, rows]) => {
+				const shape = hulls ? MultivariateMath.hull(coords(rows)) : MultivariateMath.ellipse(coords(rows));
+				return shape.length ? [{
+					name,
+					d: closed(shape, !hulls)
+				}] : [];
+			});
+			const paths = ctx.marks("shapes", "path", shapes, (d) => d.name).attr("fill", (d) => ctx.palette.color(d.name)).attr("fill-opacity", .12).attr("stroke", (d) => ctx.palette.color(d.name)).attr("stroke-width", 2).attr("stroke-linejoin", "round");
+			ctx.set(paths, { d: (d) => d.d });
+		}
+		if (overlay === "contours") {
+			const shapes = groups.flatMap(([name, rows]) => {
+				return contourDensity().x((p) => p.x - bounds.x).y((p) => p.y - bounds.y).size([bounds.width, bounds.height]).bandwidth(Math.max(8, bounds.height / 12)).thresholds(4)(rows).slice(1).map((contour, level) => ({
+					name,
+					level,
+					d: geoPath()(contour) ?? ""
+				})).filter((shape) => shape.d);
+			});
+			const paths = ctx.marks("shapes", "path", shapes, (d) => `${d.name}/${d.level}`).attr("transform", `translate(${bounds.x},${bounds.y})`).attr("fill", (d) => ctx.palette.color(d.name)).attr("fill-opacity", .1).attr("stroke", (d) => ctx.palette.color(d.name)).attr("stroke-width", 1).attr("stroke-opacity", .7);
+			ctx.set(paths, { d: (d) => d.d });
+		}
+	}
+	/** Ringed dots for a projected cloud; hides nothing and keeps a tooltip on each. */
+	static dots(ctx, points, tip, radius = 4) {
+		const dots = ctx.marks("dots", "circle", points, (point) => point.record.index).attr("fill", (point) => ctx.palette.color(point.record.group)).attr("stroke", ctx.theme.surface).attr("stroke-width", radius >= 3 ? 1.5 : .75);
+		ctx.set(dots, {
+			cx: (point) => point.x,
+			cy: (point) => point.y,
+			r: radius
+		}, { r: 0 }, 3);
+		ctx.hover(dots, tip);
+	}
+	/** Vertical list of a glyph's key beside the plot. */
+	static key(ctx, heading, entries, x, width) {
+		const lines = [{
+			text: heading,
+			tone: true
+		}, ...entries.map((text) => ({
+			text,
+			tone: false
+		}))];
+		const rows = ctx.marks("key", "text", lines, (_, i) => i).attr("x", x).attr("y", (_, i) => 10 + i * 15).text((d) => this.trim(d.text, width, 10.5));
+		ctx.text(rows, 10.5);
+		rows.attr("fill", (d) => d.tone ? ctx.theme.ink : ctx.theme.inkSecondary).attr("font-weight", (d) => d.tone ? 600 : 400);
+	}
+	/** Sequential key: a small one-hue ramp with its end values. */
+	static ramp(ctx, x, y, width, low, high, name) {
+		const steps = Array.from({ length: 16 }, (_, i) => i / 15);
+		const box = (width - 2) / steps.length;
+		ctx.marks("ramp", "rect", steps, (t) => t).attr("x", (_, i) => x + i * box).attr("y", y).attr("width", box + .5).attr("height", 7).attr("fill", (t) => ctx.palette.sequential(t));
+		const labels = [{
+			key: "low",
+			text: low,
+			x: x - 5,
+			anchor: "end"
+		}, {
+			key: "high",
+			text: name ? `${high} ${name}` : high,
+			x: x + width + 3,
+			anchor: "start"
+		}];
+		ctx.text(ctx.marks("ramp-labels", "text", labels, (d) => d.key).attr("x", (d) => d.x).attr("y", y + 7).attr("text-anchor", (d) => d.anchor).text((d) => d.text), 10, "muted");
+	}
+	/** Closed band between two cross-sections, curved or straight, in either flow direction. */
+	static ribbon(from, topA, bottomA, to, topB, bottomB, curved, flip) {
+		const p = (along, across) => flip ? `${across},${along}` : `${along},${across}`;
+		const edge = (a, b, start, end) => curved ? `C${p((start + end) / 2, a)} ${p((start + end) / 2, b)} ${p(end, b)}` : `L${p(end, b)}`;
+		return `M${p(from, topA)}${edge(topA, topB, from, to)}L${p(to, bottomB)}${edge(bottomB, bottomA, to, from)}Z`;
+	}
+};
+export { MultivariateKit, PanelLayout, ProjectionOverlay };

package/dist/charts/multivariate/MultivariateMath.js

@@ -0,0 +1,196 @@
+import { deviation, mean, polygonHull, sum } from "d3";
+// src/charts/multivariate/MultivariateMath.ts
+var DistanceMetric = /* @__PURE__ */ function(DistanceMetric) {
+	DistanceMetric["Euclidean"] = "euclidean";
+	DistanceMetric["Manhattan"] = "manhattan";
+	DistanceMetric["Correlation"] = "correlation";
+	return DistanceMetric;
+}({});
+/** Linear algebra and smoothing behind the projection charts. Inputs are plain numeric matrices. */
+var MultivariateMath = class {
+	static correlation(a, b) {
+		const pairs = a.flatMap((value, i) => Number.isFinite(value) && Number.isFinite(b[i]) ? [[value, b[i]]] : []);
+		if (pairs.length < 2) return 0;
+		const meanA = mean(pairs, (p) => p[0]), meanB = mean(pairs, (p) => p[1]);
+		const cov = sum(pairs, (p) => (p[0] - meanA) * (p[1] - meanB));
+		const scale = Math.sqrt(sum(pairs, (p) => (p[0] - meanA) ** 2) * sum(pairs, (p) => (p[1] - meanB) ** 2));
+		return scale ? cov / scale : 0;
+	}
+	/** Greedy chain through columns so that strongly related columns sit next to each other. */
+	static chain(columns) {
+		const n = columns.length;
+		if (n < 3) return columns.map((_, i) => i);
+		const r = columns.map((a) => columns.map((b) => Math.abs(this.correlation(a, b))));
+		let best = [0, 1];
+		for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) if (r[i][j] > r[best[0]][best[1]]) best = [i, j];
+		const order = [...best];
+		while (order.length < n) {
+			const tail = order[order.length - 1];
+			const next = columns.map((_, i) => i).filter((i) => !order.includes(i)).sort((a, b) => r[tail][b] - r[tail][a])[0];
+			order.push(next);
+		}
+		return order;
+	}
+	/** Eigen-decomposition of a symmetric matrix by cyclic Jacobi rotations, largest eigenvalue first. */
+	static eigen(input) {
+		const n = input.length;
+		const a = input.map((row) => [...row]);
+		const v = a.map((_, i) => a.map((__, j) => i === j ? 1 : 0));
+		for (let sweep = 0; sweep < 40; 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-14) 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 akp = a[k][p], akq = a[k][q];
+					a[k][p] = c * akp - s * akq;
+					a[k][q] = s * akp + c * akq;
+				}
+				for (let k = 0; k < n; k++) {
+					const apk = a[p][k], aqk = a[q][k];
+					a[p][k] = c * apk - s * aqk;
+					a[q][k] = s * apk + c * aqk;
+				}
+				for (let k = 0; k < n; k++) {
+					const vkp = v[k][p], vkq = v[k][q];
+					v[k][p] = c * vkp - s * vkq;
+					v[k][q] = s * vkp + c * vkq;
+				}
+			}
+		}
+		const order = a.map((_, i) => i).sort((x, y) => a[y][y] - a[x][x]);
+		return {
+			values: order.map((i) => a[i][i]),
+			vectors: order.map((i) => v.map((row) => row[i]))
+		};
+	}
+	/** Principal components of a records-by-columns matrix; `standardise` works from correlation. */
+	static pca(matrix, standardise) {
+		const k = matrix[0]?.length ?? 0, n = matrix.length;
+		const stats = Array.from({ length: k }, (_, c) => {
+			const column = matrix.map((row) => row[c]);
+			return {
+				centre: mean(column) ?? 0,
+				spread: standardise ? deviation(column) || 1 : 1
+			};
+		});
+		const x = matrix.map((row) => row.map((value, c) => (value - stats[c].centre) / stats[c].spread));
+		const cov = stats.map((_, a) => stats.map((__, b) => sum(x, (row) => row[a] * row[b]) / Math.max(1, n - 1)));
+		const { values, vectors } = this.eigen(cov);
+		const eigenvalues = values.map((value) => Math.max(0, value));
+		const total = sum(eigenvalues) || 1;
+		const signs = vectors.map((vector) => Math.sign(vector[vector.reduce((best, value, i) => Math.abs(value) > Math.abs(vector[best]) ? i : best, 0)]) || 1);
+		const loadings = vectors.map((vector, c) => vector.map((value) => value * signs[c]));
+		return {
+			loadings,
+			eigenvalues,
+			explained: eigenvalues.map((value) => value / total),
+			scores: x.map((row) => loadings.map((vector) => sum(vector, (value, c) => value * row[c])))
+		};
+	}
+	static distances(matrix, metric) {
+		const between = (a, b) => {
+			if (metric === "manhattan") return sum(a, (value, i) => Math.abs(value - b[i]));
+			if (metric === "correlation") return 1 - this.correlation(a, b);
+			return Math.sqrt(sum(a, (value, i) => (value - b[i]) ** 2));
+		};
+		return matrix.map((a) => matrix.map((b) => between(a, b)));
+	}
+	/** Torgerson's classical scaling into two dimensions. */
+	static classicalScaling(d) {
+		const n = d.length;
+		const squared = d.map((row) => row.map((value) => value * value));
+		const rowMeans = squared.map((row) => mean(row) ?? 0);
+		const grand = mean(rowMeans) ?? 0;
+		const b = squared.map((row, i) => row.map((value, j) => -.5 * (value - rowMeans[i] - rowMeans[j] + grand)));
+		const { values, vectors } = this.eigen(b);
+		return Array.from({ length: n }, (_, i) => [(vectors[0]?.[i] ?? 0) * Math.sqrt(Math.max(0, values[0] ?? 0)), (vectors[1]?.[i] ?? 0) * Math.sqrt(Math.max(0, values[1] ?? 0))]);
+	}
+	/** Stress majorisation (SMACOF) refining `start`. */
+	static stressMajorisation(d, start, iterations = 60) {
+		const n = d.length;
+		let x = start.map((p) => [p[0], p[1]]);
+		for (let step = 0; step < iterations; step++) x = x.map((p, i) => {
+			const next = [0, 0];
+			for (let j = 0; j < n; j++) {
+				if (j === i) continue;
+				const q = x[j], gap = Math.hypot(p[0] - q[0], p[1] - q[1]);
+				const ratio = gap > 1e-9 ? d[i][j] / gap : 0;
+				next[0] += q[0] + ratio * (p[0] - q[0]);
+				next[1] += q[1] + ratio * (p[1] - q[1]);
+			}
+			return [next[0] / Math.max(1, n - 1), next[1] / Math.max(1, n - 1)];
+		});
+		return x;
+	}
+	/** Normalised stress of an embedding against target distances. */
+	static stress(d, x) {
+		let fit = 0, total = 0;
+		for (let i = 0; i < x.length; i++) for (let j = i + 1; j < x.length; j++) {
+			fit += (d[i][j] - Math.hypot(x[i][0] - x[j][0], x[i][1] - x[j][1])) ** 2;
+			total += d[i][j] ** 2;
+		}
+		return total ? Math.sqrt(fit / total) : 0;
+	}
+	/** Outline of the covariance ellipse at `z` standard deviations. */
+	static ellipse(points, z = 1.5, steps = 48) {
+		if (points.length < 3) return [];
+		const cx = mean(points, (p) => p[0]), cy = mean(points, (p) => p[1]);
+		const xx = sum(points, (p) => (p[0] - cx) ** 2) / points.length, yy = sum(points, (p) => (p[1] - cy) ** 2) / points.length;
+		const xy = sum(points, (p) => (p[0] - cx) * (p[1] - cy)) / points.length;
+		const { values, vectors } = this.eigen([[xx, xy], [xy, yy]]);
+		const major = Math.sqrt(Math.max(0, values[0])) * z, minor = Math.sqrt(Math.max(0, values[1])) * z;
+		const [ux, uy] = vectors[0];
+		return Array.from({ length: steps }, (_, i) => {
+			const t = i / steps * Math.PI * 2, a = Math.cos(t) * major, b = Math.sin(t) * minor;
+			return [cx + a * ux - b * uy, cy + a * uy + b * ux];
+		});
+	}
+	static hull(points) {
+		return points.length >= 3 ? polygonHull(points) ?? [] : [];
+	}
+	/** Least-squares line, returned as its two ends over the x range. */
+	static linearFit(points) {
+		if (points.length < 2) return [];
+		const mx = mean(points, (p) => p[0]), my = mean(points, (p) => p[1]);
+		const ss = sum(points, (p) => (p[0] - mx) ** 2);
+		if (!ss) return [];
+		const slope = sum(points, (p) => (p[0] - mx) * (p[1] - my)) / ss;
+		const xs = points.map((p) => p[0]);
+		return [Math.min(...xs), Math.max(...xs)].map((x) => [x, my + slope * (x - mx)]);
+	}
+	/** Locally weighted linear regression with tricube weights, sampled across the x range. */
+	static loess(points, span = .75, steps = 24) {
+		if (points.length < 4) return this.linearFit(points);
+		const sorted = [...points].sort((a, b) => a[0] - b[0]);
+		const low = sorted[0][0], high = sorted[sorted.length - 1][0];
+		if (low === high) return [];
+		const reach = Math.max(3, Math.ceil(span * sorted.length));
+		return Array.from({ length: steps }, (_, s) => {
+			const x = low + (high - low) * s / (steps - 1);
+			const near = sorted.map((p) => Math.abs(p[0] - x)).sort((a, b) => a - b);
+			const band = near[Math.min(reach, near.length) - 1] || 1;
+			let w = 0, wx = 0, wy = 0, wxx = 0, wxy = 0;
+			for (const [px, py] of sorted) {
+				const u = Math.abs(px - x) / band;
+				if (u >= 1) continue;
+				const weight = (1 - u ** 3) ** 3;
+				w += weight;
+				wx += weight * px;
+				wy += weight * py;
+				wxx += weight * px * px;
+				wxy += weight * px * py;
+			}
+			const denominator = w * wxx - wx * wx;
+			if (!w) return [x, mean(sorted, (p) => p[1])];
+			if (Math.abs(denominator) < 1e-9) return [x, wy / w];
+			const slope = (w * wxy - wx * wy) / denominator;
+			return [x, (wy - slope * wx) / w + slope * x];
+		});
+	}
+};
+export { DistanceMetric, MultivariateMath };

package/dist/charts/multivariate/MultivariateSample.js

@@ -0,0 +1,42 @@
+import { SampleData } from "../../data/SampleData.js";
+import { quantile } from "d3";
+// src/charts/multivariate/MultivariateSample.ts
+var pick = (value, cuts, names) => names[value < cuts[0] ? 0 : value < cuts[1] ? 1 : 2];
+/** Reshapes `SampleData` into the wide and nominal tables multivariate charts need. */
+var MultivariateSample = class {
+	/** One row per observation: five correlated measures plus `group`. */
+	static wide(seed = 1, count = 60, groups = 3) {
+		const first = SampleData.points(seed, count, groups), second = SampleData.points(seed + 11, count, groups);
+		return first.map((row, i) => ({
+			group: row.group,
+			Speed: row.x,
+			Power: +(+row.y * 1.6).toFixed(1),
+			Range: +(130 - +second[i].x).toFixed(1),
+			Mass: +(+second[i].y * 4).toFixed(1),
+			Cost: +(+row.size * 2 + +row.x).toFixed(1)
+		}));
+	}
+	/** One row per observation: four categorical columns plus `value` and `score` measures. */
+	static nominal(seed = 1, count = 400) {
+		const rows = SampleData.points(seed, count, 3), mix = SampleData.points(seed + 5, count, 3);
+		const cuts = (column) => [quantile(column, .4), quantile(column, .75)];
+		const size = cuts(rows.map((row) => +row.size)), ys = cuts(rows.map((row) => +row.y)), other = cuts(mix.map((row) => +row.size));
+		return rows.map((row, i) => ({
+			Plan: row.group,
+			Channel: pick(+mix[i].size, other, [
+				"Web",
+				"Store",
+				"Partner"
+			]),
+			Tier: pick(+row.y, ys, [
+				"Basic",
+				"Plus",
+				"Pro"
+			]),
+			Outcome: +row.size + +row.y / 4 > size[0] + 18 ? "Renewed" : "Churned",
+			value: +row.size,
+			score: +row.y
+		}));
+	}
+};
+export { MultivariateSample };

package/dist/charts/multivariate/PCABiplot.js

@@ -0,0 +1,141 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { MultivariateKit, ProjectionOverlay } from "./MultivariateKit.js";
+import { MultivariateMath } from "./MultivariateMath.js";
+import { MultivariateSample } from "./MultivariateSample.js";
+import { ProjectionChart } from "./ProjectionChart.js";
+import { max } from "d3";
+// src/charts/multivariate/PCABiplot.ts
+var BiplotComponents = /* @__PURE__ */ function(BiplotComponents) {
+	BiplotComponents["First"] = "pc1-pc2";
+	BiplotComponents["Wide"] = "pc1-pc3";
+	BiplotComponents["Minor"] = "pc2-pc3";
+	return BiplotComponents;
+}({});
+var BiplotScaling = /* @__PURE__ */ function(BiplotScaling) {
+	BiplotScaling["Symmetric"] = "symmetric";
+	BiplotScaling["Distance"] = "distance";
+	BiplotScaling["Variable"] = "variable";
+	return BiplotScaling;
+}({});
+var BiplotBasis = /* @__PURE__ */ function(BiplotBasis) {
+	BiplotBasis["Correlation"] = "correlation";
+	BiplotBasis["Covariance"] = "covariance";
+	return BiplotBasis;
+}({});
+var PAIRS = {
+	["pc1-pc2"]: [0, 1],
+	["pc1-pc3"]: [0, 2],
+	["pc2-pc3"]: [1, 2]
+};
+/** See observations and the measures that separate them on one plane. */
+var PCABiplot = class extends ProjectionChart {
+	static meta = {
+		id: "pca-biplot",
+		name: "PCA biplot",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Projects observations on principal components and overlays arrows showing how each measure loads on them.",
+		tags: [
+			"multivariate",
+			"principal components",
+			"dimensionality reduction",
+			"loadings"
+		],
+		sample: (seed) => MultivariateSample.wide(seed),
+		variants: {
+			components: [
+				"pc1-pc2",
+				"pc1-pc3",
+				"pc2-pc3"
+			],
+			scaling: [
+				"symmetric",
+				"distance",
+				"variable"
+			],
+			basis: ["correlation", "covariance"],
+			overlay: [
+				ProjectionOverlay.Points,
+				ProjectionOverlay.Hulls,
+				ProjectionOverlay.Ellipses
+			]
+		}
+	};
+	defaults() {
+		return {
+			group: "group",
+			components: "pc1-pc2",
+			scaling: "symmetric",
+			basis: "correlation",
+			overlay: ProjectionOverlay.Points
+		};
+	}
+	arrows = [];
+	embed(table, records) {
+		const { scaling, basis, components } = this.options;
+		const pca = MultivariateMath.pca(records.map((record) => record.values), basis === "correlation");
+		const [a, b] = PAIRS[components];
+		const pcB = Math.min(b, pca.eigenvalues.length - 1);
+		const alpha = scaling === "distance" ? 1 : scaling === "variable" ? 0 : .5;
+		const power = (c) => Math.sqrt(Math.max(1e-12, pca.eigenvalues[c]));
+		const points = pca.scores.map((score) => [score[a] / power(a) ** (1 - alpha), score[pcB] / power(pcB) ** (1 - alpha)]);
+		const raw = table.dimensions.map((name, d) => ({
+			name,
+			x: pca.loadings[a][d] * power(a) ** (1 - alpha),
+			y: pca.loadings[pcB][d] * power(pcB) ** (1 - alpha)
+		}));
+		const reach = max(points, (p) => Math.hypot(p[0], p[1])) ?? 1;
+		const longest = max(raw, (arrow) => Math.hypot(arrow.x, arrow.y)) || 1;
+		this.arrows = raw.map((arrow) => ({
+			...arrow,
+			x: arrow.x / longest * reach * .85,
+			y: arrow.y / longest * reach * .85
+		}));
+		const label = (c) => `PC${c + 1} (${(pca.explained[c] * 100).toFixed(0)}%)`;
+		return {
+			points,
+			xLabel: label(a),
+			yLabel: label(pcB),
+			extra: this.arrows.map((arrow) => [arrow.x, arrow.y])
+		};
+	}
+	annotate(ctx, { x, y }) {
+		const { width, height } = ctx.plot;
+		const ox = x(0), oy = y(0);
+		const lines = ctx.marks("arrows", "path", this.arrows, (arrow) => arrow.name).attr("fill", "none").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("stroke-linecap", "round").attr("stroke-linejoin", "round");
+		const tip = (arrow) => {
+			const tx = x(arrow.x), ty = y(arrow.y), angle = Math.atan2(ty - oy, tx - ox), head = 7;
+			const wing = (turn) => `${tx - head * Math.cos(angle + turn)},${ty - head * Math.sin(angle + turn)}`;
+			return `M${ox},${oy}L${tx},${ty}M${wing(.45)}L${tx},${ty}L${wing(-.45)}`;
+		};
+		ctx.set(lines, { d: tip }, { d: `M${ox},${oy}L${ox},${oy}M${ox},${oy}L${ox},${oy}L${ox},${oy}` });
+		ctx.hover(lines, (arrow) => ({
+			title: arrow.name,
+			rows: [["Loading x", +arrow.x.toFixed(2)], ["Loading y", +arrow.y.toFixed(2)]]
+		}));
+		const placed = [];
+		const labels = [...this.arrows].sort((p, q) => Math.hypot(q.x, q.y) - Math.hypot(p.x, p.y)).flatMap((arrow) => {
+			const w = arrow.name.length * 6.4, tx = x(arrow.x), ty = y(arrow.y);
+			const px = Math.max(w / 2, Math.min(width - w / 2, tx + Math.sign(tx - ox) * (w / 2 + 5))), py = Math.max(8, Math.min(height - 6, ty + Math.sign(ty - oy || -1) * 10));
+			if (placed.some((box) => Math.abs(box.x - px) < (box.w + w) / 2 + 2 && Math.abs(box.y - py) < 12)) return [];
+			placed.push({
+				x: px,
+				y: py,
+				w
+			});
+			return [{
+				name: arrow.name,
+				x: px,
+				y: py
+			}];
+		});
+		const texts = ctx.marks("arrow-labels", "text", labels, (d) => d.name).attr("text-anchor", "middle").attr("dy", "0.32em").attr("font-weight", 600);
+		MultivariateKit.halo(ctx.text(texts, 10.5, "ink"), ctx).text((d) => d.name);
+		ctx.set(texts, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+	}
+};
+export { BiplotBasis, BiplotComponents, BiplotScaling, PCABiplot };