@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/multivariate/PCAScatter3D.js

@@ -0,0 +1,217 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { InstancedSticks } from "./InstancedSticks.js";
+import { MultivariateMath } from "./MultivariateMath.js";
+import { MultivariateSample } from "./MultivariateSample.js";
+import { BiplotBasis } from "./PCABiplot.js";
+import { WideTable } from "./WideTable.js";
+import { max, scaleLinear } from "d3";
+import { BoxGeometry, ConeGeometry, IcosahedronGeometry, InstancedMesh, Mesh, MeshStandardMaterial, Object3D, OctahedronGeometry, PlaneGeometry, Quaternion, Vector3 } from "three";
+// src/charts/multivariate/PCAScatter3D.ts
+var PointShape3D = /* @__PURE__ */ function(PointShape3D) {
+	PointShape3D["Sphere"] = "sphere";
+	PointShape3D["Cube"] = "cube";
+	PointShape3D["Octahedron"] = "octahedron";
+	return PointShape3D;
+}({});
+var GEOMETRY = {
+	["sphere"]: () => new IcosahedronGeometry(.042, 2),
+	["cube"]: () => new BoxGeometry(.066, .066, .066),
+	["octahedron"]: () => new OctahedronGeometry(.056)
+};
+var FLOOR = -.92;
+/** Three principal components at once, for structure a flat biplot flattens; orbit to separate clusters. */
+var PCAScatter3D = class extends Chart3D {
+	static meta = {
+		id: "pca-scatter-3d",
+		name: "3D PCA scatter",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Plots observations on their first three principal components, with optional loading arrows and drop lines.",
+		tags: [
+			"multivariate",
+			"principal components",
+			"biplot",
+			"orbit"
+		],
+		sample: (seed) => MultivariateSample.wide(seed),
+		variants: {
+			shape: [
+				"sphere",
+				"cube",
+				"octahedron"
+			],
+			basis: [BiplotBasis.Correlation, BiplotBasis.Covariance],
+			loadings: [true, false],
+			stems: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			distance: 5,
+			group: "group",
+			basis: BiplotBasis.Correlation,
+			shape: "sphere",
+			loadings: true,
+			stems: false
+		};
+	}
+	build(ctx) {
+		const table = new WideTable(this.options.data, this.options.dimensions, this.options.group);
+		const records = table.complete;
+		if (table.dimensions.length < 3 || records.length < 2) return;
+		const pca = MultivariateMath.pca(records.map((record) => record.values), this.options.basis === BiplotBasis.Correlation);
+		const reach = max(pca.scores.flatMap((score) => score.slice(0, 3).map(Math.abs))) || 1;
+		const unit = scaleLinear([-reach, reach], [-.85, .85]);
+		const position = (score) => [
+			unit(score[0]),
+			unit(score[2] ?? 0),
+			unit(score[1] ?? 0)
+		];
+		const floor = new Mesh(new PlaneGeometry(2, 2), new MeshStandardMaterial({ color: ctx.theme.grid }));
+		floor.rotation.x = -Math.PI / 2;
+		floor.position.y = FLOOR;
+		floor.receiveShadow = true;
+		ctx.root.add(floor);
+		const axes = [
+			{
+				from: [
+					-.95,
+					0,
+					0
+				],
+				to: [
+					.95,
+					0,
+					0
+				],
+				color: ctx.theme.axis
+			},
+			{
+				from: [
+					0,
+					-.9,
+					0
+				],
+				to: [
+					0,
+					.95,
+					0
+				],
+				color: ctx.theme.axis
+			},
+			{
+				from: [
+					0,
+					0,
+					-.95
+				],
+				to: [
+					0,
+					0,
+					.95
+				],
+				color: ctx.theme.axis
+			}
+		];
+		InstancedSticks.add(ctx, axes, .005, false);
+		const percent = (c) => `PC${c + 1} ${(pca.explained[c] * 100).toFixed(0)}%`;
+		ctx.label(percent(0), [
+			1.04,
+			0,
+			0
+		], "secondary", 11);
+		ctx.label(percent(2), [
+			0,
+			1.03,
+			0
+		], "secondary", 11);
+		ctx.label(percent(1), [
+			0,
+			0,
+			1.08
+		], "secondary", 11);
+		const dots = new InstancedMesh(GEOMETRY[this.options.shape](), new MeshStandardMaterial({ roughness: .42 }), records.length);
+		dots.castShadow = true;
+		const dummy = new Object3D();
+		const place = (progress) => {
+			pca.scores.forEach((score, i) => {
+				const [x, y, z] = position(score);
+				dummy.position.set(x * progress, y * progress, z * progress);
+				dummy.updateMatrix();
+				dots.setMatrixAt(i, dummy.matrix);
+			});
+			dots.instanceMatrix.needsUpdate = true;
+		};
+		records.forEach((record, i) => dots.setColorAt(i, ctx.color(ctx.palette.color(record.group))));
+		ctx.reveal(place);
+		ctx.root.add(dots);
+		ctx.pick(dots, (i) => ({
+			title: records[i].group,
+			color: ctx.palette.color(records[i].group),
+			rows: table.dimensions.map((name, d) => [name, records[i].values[d]])
+		}));
+		if (this.options.stems) {
+			const stems = records.map((record, i) => {
+				const [x, y, z] = position(pca.scores[i]);
+				return {
+					from: [
+						x,
+						FLOOR,
+						z
+					],
+					to: [
+						x,
+						y,
+						z
+					],
+					color: ctx.palette.color(record.group)
+				};
+			});
+			InstancedSticks.add(ctx, stems, .004);
+		}
+		if (this.options.loadings) this.arrows(ctx, table, pca.loadings);
+	}
+	arrows(ctx, table, loadings) {
+		const tips = table.dimensions.map((name, d) => ({
+			name,
+			tip: [
+				(loadings[0]?.[d] ?? 0) * .82,
+				(loadings[2]?.[d] ?? 0) * .82,
+				(loadings[1]?.[d] ?? 0) * .82
+			]
+		}));
+		InstancedSticks.add(ctx, tips.map(({ tip }) => ({
+			from: [
+				0,
+				0,
+				0
+			],
+			to: tip,
+			color: ctx.theme.ink
+		})), .011);
+		const heads = new InstancedMesh(new ConeGeometry(.03, .08, 12), new MeshStandardMaterial({
+			color: ctx.theme.ink,
+			roughness: .5
+		}), tips.length);
+		const dummy = new Object3D(), turn = new Quaternion();
+		tips.forEach(({ tip }, i) => {
+			dummy.position.set(...tip);
+			dummy.quaternion.copy(turn.setFromUnitVectors(new Vector3(0, 1, 0), new Vector3(...tip).normalize()));
+			dummy.updateMatrix();
+			heads.setMatrixAt(i, dummy.matrix);
+		});
+		ctx.root.add(heads);
+		ctx.pick(heads, (i) => ({
+			title: tips[i].name,
+			rows: [["Loading length", +new Vector3(...tips[i].tip).length().toFixed(2)]]
+		}));
+		for (const { name, tip } of tips) ctx.label(name, [
+			tip[0] * 1.14,
+			tip[1] * 1.14 + .03,
+			tip[2] * 1.14
+		], "ink", 10.5);
+	}
+};
+export { PCAScatter3D, PointShape3D };

package/dist/charts/multivariate/PanelScatter.js

@@ -0,0 +1,88 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { MultivariateKit } from "./MultivariateKit.js";
+import { MultivariateMath } from "./MultivariateMath.js";
+import { curveLinearClosed, curveMonotoneX, line } from "d3";
+// src/charts/multivariate/PanelScatter.ts
+var PanelFit = /* @__PURE__ */ function(PanelFit) {
+	PanelFit["None"] = "no-fit";
+	PanelFit["Linear"] = "linear-fit";
+	PanelFit["Loess"] = "loess";
+	PanelFit["Ellipse"] = "ellipse";
+	return PanelFit;
+}({});
+/** Small-multiple scatter panels: shared drawing for faceted and conditioned plots. */
+var PanelScatter = class extends Chart2D {
+	plotMargin() {
+		return {
+			top: 6,
+			right: 12,
+			bottom: 20,
+			left: 30
+		};
+	}
+	points() {
+		const { data, x, y } = this.options;
+		return (Array.isArray(data) ? data : []).flatMap((row, index) => {
+			const px = row[x] == null ? NaN : +row[x], py = row[y] == null ? NaN : +row[y];
+			return Number.isFinite(px) && Number.isFinite(py) ? [{
+				x: px,
+				y: py,
+				row,
+				index
+			}] : [];
+		});
+	}
+	panel(ctx, { panel, name, rows, x, y, context = [], showX, showY }) {
+		const nest = ctx.nest(`translate(${panel.x},${panel.y})`, `panel-${panel.index}`);
+		const { width, height } = panel;
+		const compact = width < 100;
+		MultivariateKit.axes(nest, x, y, {
+			width,
+			height,
+			showX,
+			showY,
+			xTicks: compact ? 2 : 3,
+			yTicks: height < 46 ? 1 : height < 60 ? 2 : 3
+		});
+		const r = Math.max(2, Math.min(4, Math.min(width, height) / 16));
+		const ghosts = nest.marks("context", "circle", context, (d) => d.index).attr("fill", ctx.theme.inkMuted).attr("fill-opacity", .22);
+		ctx.set(ghosts, {
+			cx: (d) => x(d.x),
+			cy: (d) => y(d.y),
+			r: Math.max(1.5, r - 1)
+		});
+		const color = ctx.palette.color(this.options.y);
+		const dots = nest.marks("dots", "circle", rows, (d) => d.index).attr("fill", color).attr("stroke", ctx.theme.surface).attr("stroke-width", r >= 3 ? 1 : .5);
+		ctx.set(dots, {
+			cx: (d) => x(d.x),
+			cy: (d) => y(d.y),
+			r
+		}, { r: 0 }, 2);
+		ctx.hover(dots, (d) => ({
+			title: name,
+			color,
+			rows: [[this.options.x, d.x], [this.options.y, d.y]]
+		}));
+		const fit = this.fitPath(rows.map((d) => [d.x, d.y]), x, y);
+		const lines = nest.marks("fit", "path", fit ? [fit] : []).attr("fill", "none").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		ctx.set(lines, { d: (d) => d });
+		const title = nest.marks("title", "text", [name]).attr("font-weight", 600).text((d) => MultivariateKit.trim(d, width - 6, 10.5));
+		MultivariateKit.halo(ctx.text(title, 10.5, "ink"), ctx);
+		ctx.set(title, {
+			x: 4,
+			y: 11
+		});
+	}
+	fitPath(points, x, y) {
+		const { fit } = this.options;
+		const clamp = (p) => [x(p[0]), Math.max(y.range()[1], Math.min(y.range()[0], y(p[1])))];
+		if (fit === "ellipse") {
+			const shape = MultivariateMath.ellipse(points).map(clamp);
+			return shape.length ? line().curve(curveLinearClosed)(shape) : null;
+		}
+		if (fit !== "linear-fit" && fit !== "loess") return null;
+		const shape = (fit === "linear-fit" ? MultivariateMath.linearFit(points) : MultivariateMath.loess(points)).map(clamp);
+		return shape.length > 1 ? line().curve(curveMonotoneX)(shape) : null;
+	}
+};
+export { PanelFit, PanelScatter };

package/dist/charts/multivariate/ParallelCoordinates.js

@@ -0,0 +1,262 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, CurveKind, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { MultivariateKit } from "./MultivariateKit.js";
+import { MultivariateMath } from "./MultivariateMath.js";
+import { MultivariateSample } from "./MultivariateSample.js";
+import { WideNormal, WideTable } from "./WideTable.js";
+import { area, brushX, brushY, curveBumpX, curveBumpY, curveLinear, deviation, extent, line, mean, quantile, scaleLinear, scalePoint } from "d3";
+// src/charts/multivariate/ParallelCoordinates.ts
+var ParallelAxisOrder = /* @__PURE__ */ function(ParallelAxisOrder) {
+	ParallelAxisOrder["Given"] = "given";
+	ParallelAxisOrder["Correlation"] = "correlation";
+	ParallelAxisOrder["Spread"] = "spread";
+	return ParallelAxisOrder;
+}({});
+var ParallelScale = /* @__PURE__ */ function(ParallelScale) {
+	ParallelScale["PerAxis"] = "per-axis";
+	ParallelScale["Shared"] = "shared";
+	ParallelScale["ZScore"] = "z-score";
+	return ParallelScale;
+}({});
+var ParallelLayer = /* @__PURE__ */ function(ParallelLayer) {
+	ParallelLayer["Lines"] = "lines";
+	ParallelLayer["Ribbons"] = "ribbons";
+	ParallelLayer["Means"] = "means";
+	return ParallelLayer;
+}({});
+var TOP = 30;
+/** Follow each observation across many measures to find clusters, trade-offs and outliers. Drag along an axis to filter. */
+var ParallelCoordinates = class extends Chart2D {
+	static meta = {
+		id: "parallel-coordinates",
+		name: "Parallel coordinates",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Draws every observation as a line across parallel axes, one per measure, to expose clusters and trade-offs.",
+		tags: [
+			"multivariate",
+			"pcp",
+			"brushing",
+			"high-dimensional"
+		],
+		sample: (seed) => MultivariateSample.wide(seed),
+		variants: {
+			layer: [
+				"lines",
+				"ribbons",
+				"means"
+			],
+			scale: [
+				"per-axis",
+				"shared",
+				"z-score"
+			],
+			axisOrder: [
+				"given",
+				"correlation",
+				"spread"
+			],
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			curve: [CurveKind.Linear, CurveKind.Bump]
+		}
+	};
+	filters = /* @__PURE__ */ new Map();
+	defaults() {
+		return {
+			group: "group",
+			orientation: Orientation.Vertical,
+			curve: CurveKind.Linear,
+			axisOrder: "given",
+			scale: "per-axis",
+			layer: "lines"
+		};
+	}
+	get upright() {
+		return this.options.orientation === Orientation.Vertical;
+	}
+	plotMargin() {
+		return this.upright ? {
+			top: 8,
+			right: 16,
+			bottom: 12,
+			left: 16
+		} : {
+			top: 6,
+			right: 16,
+			bottom: 14,
+			left: 56
+		};
+	}
+	order(table) {
+		const columns = table.dimensions.map((_, d) => table.records.map((record) => record.values[d]));
+		const all = table.dimensions.map((_, d) => d);
+		if (this.options.axisOrder === "correlation") return MultivariateMath.chain(columns);
+		if (this.options.axisOrder === "spread") {
+			const spread = all.map((d) => deviation(table.normalised(WideNormal.MinMax).map((row) => row[d]).filter(Number.isFinite)) ?? 0);
+			return all.sort((a, b) => spread[b] - spread[a]);
+		}
+		return all;
+	}
+	/** Values per axis on the active scale. */
+	strokes(table) {
+		const rows = this.options.scale === "z-score" ? table.normalised(WideNormal.ZScore) : table.records.map((record) => record.values);
+		return table.records.map((record, i) => ({
+			record,
+			values: rows[i]
+		}));
+	}
+	axes(ctx, table, strokes) {
+		const { width, height } = ctx.plot;
+		const order = this.order(table);
+		const along = scalePoint(order.map(String), this.upright ? [0, width] : [14, height - 12]);
+		const common = extent(strokes.flatMap((stroke) => stroke.values.filter(Number.isFinite)));
+		const range = this.upright ? [height - 14, TOP] : [0, width];
+		return order.map((column) => {
+			const own = this.options.scale === "per-axis" ? table.bounds(column) : common;
+			return {
+				name: table.dimensions[column],
+				column,
+				at: along(String(column)) ?? 0,
+				scale: scaleLinear(own, range)
+			};
+		});
+	}
+	draw(ctx) {
+		const table = WideTable.of(this.options);
+		if (!table.dimensions.length || !table.records.length) return;
+		const strokes = this.strokes(table);
+		const axes = this.axes(ctx, table, strokes);
+		this.drawAxes(ctx, axes);
+		if (this.options.layer === "lines") this.drawLines(ctx, table, strokes, axes);
+		else this.drawSummaries(ctx, table, strokes, axes);
+		this.drawLabels(ctx, axes);
+		if (this.options.layer === "lines") this.drawBrushes(ctx, axes);
+	}
+	curve() {
+		if (this.options.curve === CurveKind.Linear) return curveLinear;
+		return this.upright ? curveBumpX : curveBumpY;
+	}
+	path(axes, value) {
+		const point = (axis) => {
+			const across = axis.scale(value(axis));
+			return this.upright ? [axis.at, across] : [across, axis.at];
+		};
+		return line((axis) => point(axis)[0], (axis) => point(axis)[1]).defined((axis) => Number.isFinite(value(axis))).curve(this.curve())(axes) ?? "";
+	}
+	drawAxes(ctx, axes) {
+		const { width, height } = ctx.plot;
+		const posts = ctx.marks("posts", "line", axes, (axis) => axis.name).attr("stroke", ctx.theme.axis);
+		ctx.set(posts, this.upright ? {
+			x1: (a) => a.at,
+			x2: (a) => a.at,
+			y1: TOP,
+			y2: height - 14
+		} : {
+			x1: 0,
+			x2: width,
+			y1: (a) => a.at,
+			y2: (a) => a.at
+		});
+	}
+	drawLines(ctx, table, strokes, axes) {
+		const opacity = Math.max(.16, Math.min(.62, 26 / strokes.length));
+		const lines = ctx.marks("lines", "path", strokes, (stroke) => stroke.record.index).attr("fill", "none").attr("stroke", (stroke) => ctx.palette.color(stroke.record.group)).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-opacity", opacity);
+		ctx.set(lines, { d: (stroke) => this.path(axes, (axis) => stroke.values[axis.column]) });
+		ctx.drawOn(lines);
+		ctx.hover(lines, (stroke) => MultivariateKit.tooltip(table, stroke.record, ctx.palette.color(stroke.record.group)));
+	}
+	drawSummaries(ctx, table, strokes, axes) {
+		const groups = table.groups.map((name) => ({
+			name,
+			rows: strokes.filter((stroke) => stroke.record.group === name)
+		}));
+		const at = (rows, axis, q) => quantile(rows.map((row) => row.values[axis.column]).filter(Number.isFinite), q) ?? NaN;
+		const centre = (rows, axis) => mean(rows, (row) => row.values[axis.column]);
+		const ribbons = this.options.layer === "ribbons";
+		const shape = ({ rows }) => {
+			const low = (axis) => axis.scale(at(rows, axis, .25)), high = (axis) => axis.scale(at(rows, axis, .75));
+			return (this.upright ? area().x((axis) => axis.at).y0(low).y1(high) : area().y((axis) => axis.at).x0(low).x1(high)).defined((axis) => Number.isFinite(at(rows, axis, .5))).curve(this.curve())(axes) ?? "";
+		};
+		const color = (name) => ctx.palette.color(name);
+		const bands = ctx.marks("bands", "path", ribbons ? groups : [], (d) => d.name).attr("fill", (d) => color(d.name)).attr("fill-opacity", .2);
+		ctx.set(bands, { d: shape });
+		const trend = (rows) => (axis) => ribbons ? at(rows, axis, .5) : centre(rows, axis) ?? NaN;
+		const lines = ctx.marks("lines", "path", groups, (d) => d.name).attr("fill", "none").attr("stroke", (d) => color(d.name)).attr("stroke-width", 2.5).attr("stroke-linejoin", "round");
+		ctx.set(lines, { d: (d) => this.path(axes, trend(d.rows)) });
+		ctx.drawOn(lines);
+		ctx.hover(lines, (d) => ({
+			title: d.name,
+			color: color(d.name),
+			rows: axes.filter((axis) => Number.isFinite(trend(d.rows)(axis))).map((axis) => [axis.name, +trend(d.rows)(axis).toFixed(2)])
+		}));
+		const nodes = groups.flatMap((d) => axes.map((axis) => ({
+			group: d.name,
+			axis,
+			value: trend(d.rows)(axis)
+		})));
+		const dots = ctx.marks("nodes", "circle", nodes.filter((node) => Number.isFinite(node.value)), (d) => `${d.group}/${d.axis.name}`).attr("fill", (d) => color(d.group)).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => this.upright ? d.axis.at : d.axis.scale(d.value),
+			cy: (d) => this.upright ? d.axis.scale(d.value) : d.axis.at,
+			r: 5
+		}, { r: 0 });
+		ctx.hover(dots, (d) => ({
+			title: d.axis.name,
+			color: color(d.group),
+			rows: [[d.group, +d.value.toFixed(2)]]
+		}));
+	}
+	drawLabels(ctx, axes) {
+		const { width, height } = ctx.plot;
+		const room = (axes.length > 1 ? (this.upright ? width : height) / (axes.length - 1) : width) - 8;
+		const anchor = (i) => i === 0 ? "start" : i === axes.length - 1 ? "end" : "middle";
+		const names = ctx.marks("names", "text", axes, (axis) => axis.name).attr("font-weight", 600);
+		ctx.text(names, 11, "ink").attr("text-anchor", (_, i) => this.upright ? anchor(i) : "end").attr("dy", "0.32em").text((axis) => MultivariateKit.trim(axis.name, this.upright ? room : 50));
+		ctx.set(names, this.upright ? {
+			x: (a) => a.at,
+			y: 6
+		} : {
+			x: -8,
+			y: (a) => a.at
+		});
+		const ticks = axes.flatMap((axis) => axis.scale.domain().map((value) => ({
+			axis,
+			value
+		})));
+		const edge = (d) => axes.indexOf(d.axis) === axes.length - 1;
+		const labels = ctx.marks("ticks", "text", ticks, (d) => `${d.axis.name}/${d.value}`);
+		MultivariateKit.halo(ctx.text(labels, 9.5, "muted"), ctx).text((d) => +d.value.toFixed(Math.abs(d.value) < 10 ? 1 : 0));
+		if (this.upright) ctx.set(labels, {
+			x: (d) => d.axis.at + (edge(d) ? -3 : 3),
+			y: (d) => d.axis.scale(d.value) + (d.axis.scale(d.value) > height / 2 ? 11 : -3)
+		}).attr("text-anchor", (d) => edge(d) ? "end" : "start");
+		else ctx.set(labels, {
+			x: (d) => d.axis.scale(d.value),
+			y: (d) => d.axis.at + 10
+		}).attr("text-anchor", (d) => d.axis.scale(d.value) < 8 ? "start" : d.axis.scale(d.value) > width - 8 ? "end" : "middle");
+	}
+	drawBrushes(ctx, axes) {
+		const { width, height } = ctx.plot;
+		const { filters } = this;
+		const passes = (record) => axes.every((axis) => {
+			const span = filters.get(axis.name);
+			if (!span) return true;
+			const value = axis.scale(record.values[axis.column]);
+			return value >= span[0] && value <= span[1];
+		});
+		const refresh = () => ctx.root.select("g.m-lines").selectAll("path").attr("display", (stroke) => passes(stroke.record) ? null : "none");
+		const layer = ctx.marks("brushes", "g", axes, (axis) => axis.name);
+		const upright = this.upright;
+		layer.each(function(axis) {
+			const brush = (upright ? brushY().extent([[axis.at - 9, TOP], [axis.at + 9, height - 14]]) : brushX().extent([[0, axis.at - 7], [width, axis.at + 7]])).on("brush end", (event) => {
+				event.selection ? filters.set(axis.name, event.selection) : filters.delete(axis.name);
+				refresh();
+			});
+			ctx.root.select(() => this).call(brush);
+		});
+		layer.selectAll(".selection").attr("fill", ctx.theme.ink).attr("fill-opacity", .12).attr("stroke", ctx.theme.axis);
+		refresh();
+	}
+};
+export { ParallelAxisOrder, ParallelCoordinates, ParallelLayer, ParallelScale };