@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/density/DelaunayMesh.js

@@ -0,0 +1,186 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { PlaneGeometry } from "./PlaneGeometry.js";
+import { PointDensityChart } from "./PointDensityChart.js";
+import { Delaunay, mean, polygonHull } from "d3";
+// src/charts/density/DelaunayMesh.ts
+/** Which subgraph of the Delaunay triangulation to draw. Each is a stricter proximity rule. */
+var MeshGraph = /* @__PURE__ */ function(MeshGraph) {
+	MeshGraph["Delaunay"] = "delaunay";
+	MeshGraph["Alpha"] = "alpha";
+	MeshGraph["Gabriel"] = "gabriel";
+	MeshGraph["Urquhart"] = "urquhart";
+	MeshGraph["Relative"] = "relative-neighbour";
+	MeshGraph["Spanning"] = "spanning-tree";
+	return MeshGraph;
+}({});
+var MeshStyle = /* @__PURE__ */ function(MeshStyle) {
+	MeshStyle["Wire"] = "wire";
+	MeshStyle["Filled"] = "filled";
+	return MeshStyle;
+}({});
+var distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+/** Triangulates points and draws proximity graphs. Use it to see who neighbours whom, for meshes and spatial clustering. */
+var DelaunayMesh = class extends PointDensityChart {
+	static meta = {
+		id: "density-delaunay",
+		name: "Delaunay mesh",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Connects neighbouring points into a triangulation or one of its proximity subgraphs, from alpha shapes to the minimum spanning tree.",
+		tags: [
+			"triangulation",
+			"gabriel graph",
+			"alpha shape",
+			"minimum spanning tree"
+		],
+		sample: (seed) => SampleData.points(seed, 110, 3),
+		variants: {
+			graph: Object.values(MeshGraph),
+			style: ["wire", "filled"],
+			relax: [
+				0,
+				1,
+				3
+			],
+			sites: [true, false],
+			hull: [false, true]
+		},
+		valid: ({ graph, style, relax }) => (style === "wire" || graph === "delaunay" || graph === "alpha") && (graph !== "relative-neighbour" || relax === 0)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			weight: "size",
+			graph: "delaunay",
+			style: "wire",
+			relax: 0,
+			sites: true,
+			hull: false
+		};
+	}
+	triangles(mesh, sites, points) {
+		const all = [];
+		for (let t = 0; t < mesh.triangles.length / 3; t++) {
+			const corners = [
+				mesh.triangles[t * 3],
+				mesh.triangles[t * 3 + 1],
+				mesh.triangles[t * 3 + 2]
+			];
+			if (corners.every((c) => points[c])) all.push({
+				key: t,
+				corners,
+				value: mean(corners, (c) => points[c].w) ?? 0
+			});
+		}
+		if (this.options.graph !== "alpha") return all;
+		const radius = ({ corners: [a, b, c] }) => {
+			const [A, B, C] = [
+				sites[a],
+				sites[b],
+				sites[c]
+			];
+			return distance(A, B) * distance(B, C) * distance(C, A) / (4 * PlaneGeometry.area([
+				A,
+				B,
+				C
+			]) || 1);
+		};
+		const sorted = all.map(radius).sort((x, y) => x - y);
+		const alpha = sorted[Math.floor(sorted.length * .75)] ?? 0;
+		return all.filter((triangle) => radius(triangle) <= alpha);
+	}
+	edges(mesh, sites, triangles) {
+		const unique = /* @__PURE__ */ new Map();
+		for (const { corners: [a, b, c] } of triangles) for (const [p, q] of [
+			[a, b],
+			[b, c],
+			[c, a]
+		]) unique.set(`${Math.min(p, q)}/${Math.max(p, q)}`, p < q ? [p, q] : [q, p]);
+		const edges = [...unique.values()];
+		const length = ([a, b]) => distance(sites[a], sites[b]);
+		const near = (i) => [...mesh.neighbors(i)];
+		switch (this.options.graph) {
+			case "gabriel": return edges.filter(([a, b]) => {
+				const middle = [(sites[a][0] + sites[b][0]) / 2, (sites[a][1] + sites[b][1]) / 2], reach = length([a, b]) / 2;
+				return ![...near(a), ...near(b)].some((c) => c !== a && c !== b && distance(sites[c], middle) < reach);
+			});
+			case "urquhart": {
+				const longest = new Set(triangles.map(({ corners: [a, b, c] }) => {
+					const longestEdge = [
+						[a, b],
+						[b, c],
+						[c, a]
+					].reduce((best, edge) => length(edge) > length(best) ? edge : best);
+					return `${Math.min(...longestEdge)}/${Math.max(...longestEdge)}`;
+				}));
+				return edges.filter(([a, b]) => !longest.has(`${a}/${b}`));
+			}
+			case "relative-neighbour": return edges.filter(([a, b]) => {
+				const span = length([a, b]);
+				return ![...near(a), ...near(b)].some((c) => c !== a && c !== b && Math.max(distance(sites[a], sites[c]), distance(sites[b], sites[c])) < span);
+			});
+			case "spanning-tree": {
+				const parent = sites.map((_, i) => i);
+				const root = (i) => parent[i] === i ? i : parent[i] = root(parent[i]);
+				return [...edges].sort((p, q) => length(p) - length(q)).filter(([a, b]) => {
+					const ra = root(a), rb = root(b);
+					if (ra === rb) return false;
+					parent[ra] = rb;
+					return true;
+				});
+			}
+			default: return edges;
+		}
+	}
+	drawDensity(ctx, _axes, points) {
+		const { style, relax, sites: showSites, hull } = this.options;
+		const { width, height } = ctx.plot;
+		const sites = PlaneGeometry.relax(this.pixels(points), width, height, relax);
+		const mesh = Delaunay.from(sites);
+		const triangles = this.triangles(mesh, sites, points);
+		const filled = style === "filled";
+		const top = triangles.reduce((best, t) => Math.max(best, t.value), 0) || 1;
+		const tone = (d) => ctx.palette.sequential(.12 + .88 * d.value / top);
+		const faces = ctx.marks("faces", "path", filled ? triangles : [], (d) => d.key).attr("fill", tone).attr("stroke", ctx.theme.surface).attr("stroke-width", 1).attr("stroke-linejoin", "round");
+		this.reveal(ctx, faces, { d: (d) => PlaneGeometry.path(d.corners.map((c) => sites[c])) }, 2);
+		ctx.hover(faces, (d) => ({
+			color: tone(d),
+			rows: [[`Mean ${this.options.weight}`, +d.value.toFixed(1)]]
+		}));
+		const links = filled ? [] : this.edges(mesh, sites, triangles);
+		const lines = ctx.marks("edges", "line", links, (d) => `${d[0]}/${d[1]}`).attr("stroke", ctx.palette.sequential(.72)).attr("stroke-width", 1.5).attr("stroke-linecap", "round");
+		this.reveal(ctx, lines, {
+			x1: (d) => sites[d[0]][0],
+			y1: (d) => sites[d[0]][1],
+			x2: (d) => sites[d[1]][0],
+			y2: (d) => sites[d[1]][1]
+		}, 1);
+		ctx.hover(lines, (d) => ({ rows: [["Length", `${Math.round(distance(sites[d[0]], sites[d[1]]))} px`]] }));
+		const shell = sites.length > 2 ? polygonHull(sites) : null;
+		const outline = ctx.marks("hull", "path", hull && shell ? [PlaneGeometry.path(shell)] : []).attr("fill", "none").attr("stroke", ctx.theme.ink).attr("stroke-width", 2).attr("stroke-linejoin", "round");
+		ctx.set(outline, { d: (d) => d });
+		const indexed = sites.map((site, i) => ({
+			site,
+			point: points[i]
+		}));
+		const dots = ctx.marks("sites", "circle", showSites ? indexed : [], (_, i) => i).attr("fill", (d) => ctx.palette.color(d.point.group)).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => d.site[0],
+			cy: (d) => d.site[1],
+			r: 4
+		}, {
+			cx: (d) => d.site[0],
+			cy: (d) => d.site[1],
+			r: 0
+		}, 3);
+		ctx.hover(dots, (d) => ({
+			title: d.point.group || void 0,
+			color: ctx.palette.color(d.point.group),
+			rows: this.tipRows(d.point)
+		}));
+		if (filled) this.showRamp(ctx, top, (t) => ctx.palette.sequential(.12 + .88 * t));
+	}
+};
+export { DelaunayMesh, MeshGraph, MeshStyle };

package/dist/charts/density/DensityContourChart.js

@@ -0,0 +1,107 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { ContourLabels } from "./ContourLabels.js";
+import { DensityBandwidth, DensityKernel, DensityOverlay, LevelSpacing } from "./DensityEnums.js";
+import { FieldContours } from "./FieldContours.js";
+import { FieldLevels } from "./FieldLevels.js";
+import { KernelField } from "./KernelField.js";
+import { PointDensityChart } from "./PointDensityChart.js";
+import { group } from "d3";
+// src/charts/density/DensityContourChart.ts
+/** Outlines where points concentrate. Use it instead of a scatter plot once points overlap, or to compare groups. */
+var DensityContourChart = class extends PointDensityChart {
+	static meta = {
+		id: "density-contour",
+		name: "Density contour",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Estimates the density of an x/y point cloud and draws its contours, pooled or per group, with mass-enclosing levels.",
+		tags: [
+			"kde",
+			"contour",
+			"highest density region",
+			"bivariate"
+		],
+		sample: (seed) => SampleData.points(seed, 480, 3),
+		variants: {
+			spacing: [
+				LevelSpacing.Uniform,
+				LevelSpacing.Mass,
+				LevelSpacing.Quantile
+			],
+			bandwidth: [
+				DensityBandwidth.Scott,
+				DensityBandwidth.Narrow,
+				DensityBandwidth.Wide
+			],
+			kernel: [
+				DensityKernel.Gaussian,
+				DensityKernel.Epanechnikov,
+				DensityKernel.Box
+			],
+			overlay: [
+				DensityOverlay.None,
+				DensityOverlay.Points,
+				DensityOverlay.Rug
+			],
+			split: [false, true]
+		},
+		valid: ({ split, overlay }) => !(split && overlay === DensityOverlay.Rug)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			kernel: DensityKernel.Gaussian,
+			bandwidth: DensityBandwidth.Scott,
+			spacing: LevelSpacing.Uniform,
+			overlay: DensityOverlay.None,
+			split: false,
+			levels: 6
+		};
+	}
+	lines(points, ctx, top) {
+		const { kernel, bandwidth, spacing, levels } = this.options;
+		const field = new KernelField(points.map(({ px, py }) => ({
+			px,
+			py
+		})), ctx.plot.width, ctx.plot.height, {
+			kernel,
+			bandwidth
+		});
+		const project = (i, j) => [(i + .5) * field.cellWidth, (j + .5) * field.cellHeight];
+		const contours = new FieldContours(field.values, field.columns, field.rows, project);
+		top.value = Math.max(top.value, field.max);
+		return FieldLevels.of(field.values, levels, spacing).map((level, index) => ({
+			...level,
+			index,
+			peak: field.max,
+			label: spacing === LevelSpacing.Mass ? level.label : level.value / field.max < .01 ? "<1%" : `${Math.round(level.value / field.max * 100)}%`,
+			...contours.at(level.value)
+		}));
+	}
+	drawDensity(ctx, _axes, points) {
+		const { split, overlay, spacing } = this.options;
+		const parts = split ? [...group(points, (d) => d.group)] : [["", points]];
+		const top = { value: 0 };
+		const lines = parts.flatMap(([name, rows]) => this.lines([...rows], ctx, top).map((line) => ({
+			...line,
+			name
+		})));
+		const stroke = (d) => split ? ctx.palette.color(d.name) : ctx.palette.sequential(.3 + .7 * d.value / d.peak);
+		const paths = ctx.marks("contours", "path", lines, (d) => `${d.name}/${d.value}`).attr("fill", "none").attr("stroke", stroke).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("stroke-opacity", split ? .85 : 1);
+		this.reveal(ctx, paths, { d: (d) => d.line }, 25);
+		ctx.hover(paths, (d) => ({
+			title: d.name || void 0,
+			rows: [[spacing === LevelSpacing.Mass ? "Encloses" : "Share of peak", d.label]],
+			color: stroke(d)
+		}));
+		this.drawOverlay(ctx, points, overlay);
+		ContourLabels.draw(ctx, split ? [] : lines.filter((d) => d.index % 2 === 1).map((d) => ({
+			text: d.label,
+			polylines: d.polylines
+		})));
+		if (!split) this.showRamp(ctx, 1, (t) => ctx.palette.sequential(.3 + .7 * t), (t) => `${Math.round(t * 100)}%`);
+	}
+};
+export { DensityContourChart };

package/dist/charts/density/DensityEnums.js

@@ -0,0 +1,45 @@
+// src/charts/density/DensityEnums.ts
+/** Shape of the smoothing kernel used by every kernel density estimate in this module. */
+var DensityKernel = /* @__PURE__ */ function(DensityKernel) {
+	DensityKernel["Gaussian"] = "gaussian";
+	DensityKernel["Epanechnikov"] = "epanechnikov";
+	DensityKernel["Triangular"] = "triangular";
+	DensityKernel["Box"] = "box";
+	return DensityKernel;
+}({});
+/** Smoothing strength relative to Scott's rule. */
+var DensityBandwidth = /* @__PURE__ */ function(DensityBandwidth) {
+	DensityBandwidth["Scott"] = "scott";
+	DensityBandwidth["Narrow"] = "narrow";
+	DensityBandwidth["Wide"] = "wide";
+	return DensityBandwidth;
+}({});
+/** How contour levels divide a field's range. `Mass` picks levels enclosing fixed shares of the total. */
+var LevelSpacing = /* @__PURE__ */ function(LevelSpacing) {
+	LevelSpacing["Uniform"] = "uniform";
+	LevelSpacing["Quantile"] = "quantile";
+	LevelSpacing["Geometric"] = "geometric";
+	LevelSpacing["Mass"] = "mass";
+	return LevelSpacing;
+}({});
+/** Interpolated contour vertices, or vertices kept on the grid. */
+var FieldInterpolation = /* @__PURE__ */ function(FieldInterpolation) {
+	FieldInterpolation["Smooth"] = "smooth";
+	FieldInterpolation["Stepped"] = "stepped";
+	return FieldInterpolation;
+}({});
+/** Raw data drawn over a density surface. */
+var DensityOverlay = /* @__PURE__ */ function(DensityOverlay) {
+	DensityOverlay["None"] = "none";
+	DensityOverlay["Points"] = "points";
+	DensityOverlay["Rug"] = "rug";
+	return DensityOverlay;
+}({});
+/** How raw density maps to tone. */
+var DensityTransform = /* @__PURE__ */ function(DensityTransform) {
+	DensityTransform["Linear"] = "linear";
+	DensityTransform["Sqrt"] = "sqrt";
+	DensityTransform["Log"] = "log";
+	return DensityTransform;
+}({});
+export { DensityBandwidth, DensityKernel, DensityOverlay, DensityTransform, FieldInterpolation, LevelSpacing };

package/dist/charts/density/DensityScatter.js

@@ -0,0 +1,118 @@
+import { ChartFamily, DataShape, Dimension, SymbolKind } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { DensityBandwidth } from "./DensityEnums.js";
+import { FieldContours } from "./FieldContours.js";
+import { FieldLevels } from "./FieldLevels.js";
+import { KernelField } from "./KernelField.js";
+import { PointDensityChart } from "./PointDensityChart.js";
+import { ascending, descending, quantile, symbol } from "d3";
+// src/charts/density/DensityScatter.ts
+/** Paint order of the dots. */
+var ScatterStacking = /* @__PURE__ */ function(ScatterStacking) {
+	ScatterStacking["DenseOnTop"] = "dense-on-top";
+	ScatterStacking["SparseOnTop"] = "sparse-on-top";
+	ScatterStacking["DataOrder"] = "data-order";
+	return ScatterStacking;
+}({});
+/** All dots toned by density, or a smooth surface with only the outliers left as dots. */
+var ScatterMode = /* @__PURE__ */ function(ScatterMode) {
+	ScatterMode["AllPoints"] = "all-points";
+	ScatterMode["OutliersOnSurface"] = "outliers-on-surface";
+	return ScatterMode;
+}({});
+var OUTLIER_SHARE = .08;
+var MARKER_AREA = 42;
+/** A scatter plot coloured by local density. Use it when every point matters, but so does where they pile up. */
+var DensityScatter = class extends PointDensityChart {
+	static meta = {
+		id: "density-scatter",
+		name: "Density scatter",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Colours each point by the local density around it, or keeps only outliers over a smooth surface, so overplotting stops hiding the shape.",
+		tags: [
+			"smooth scatter",
+			"heat scatter",
+			"overplotting",
+			"outliers"
+		],
+		sample: (seed) => SampleData.points(seed, 480, 3),
+		variants: {
+			stacking: [
+				"dense-on-top",
+				"sparse-on-top",
+				"data-order"
+			],
+			mode: ["all-points", "outliers-on-surface"],
+			marker: [
+				SymbolKind.Circle,
+				SymbolKind.Square,
+				SymbolKind.Diamond
+			],
+			shrink: [false, true],
+			bandwidth: [
+				DensityBandwidth.Scott,
+				DensityBandwidth.Narrow,
+				DensityBandwidth.Wide
+			]
+		},
+		valid: ({ mode, stacking, shrink, bandwidth }) => mode === "all-points" ? stacking !== "data-order" || shrink === true || bandwidth === DensityBandwidth.Scott : stacking === "dense-on-top" && !shrink
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			stacking: "dense-on-top",
+			mode: "all-points",
+			marker: SymbolKind.Circle,
+			shrink: false,
+			bandwidth: DensityBandwidth.Scott
+		};
+	}
+	drawDensity(ctx, _axes, points) {
+		const { stacking, mode, marker, shrink, bandwidth } = this.options;
+		const field = new KernelField(points.map(({ px, py }) => ({
+			px,
+			py
+		})), ctx.plot.width, ctx.plot.height, { bandwidth });
+		const top = field.max || 1;
+		const scored = points.map((point, index) => ({
+			...point,
+			index,
+			density: field.at(point.px, point.py) / top
+		}));
+		const surface = mode === "outliers-on-surface";
+		const cut = quantile(scored.map((d) => d.density).sort(ascending), OUTLIER_SHARE) ?? 0;
+		const kept = surface ? scored.filter((d) => d.density <= cut) : scored;
+		const ordered = stacking === "data-order" ? kept : [...kept].sort((a, b) => stacking === "dense-on-top" ? ascending(a.density, b.density) : descending(a.density, b.density));
+		const project = (i, j) => [(i + .5) * field.cellWidth, (j + .5) * field.cellHeight];
+		const contours = new FieldContours(field.values, field.columns, field.rows, project);
+		const bands = surface ? FieldLevels.of(field.values, 16).map((level) => ({
+			...level,
+			...contours.at(level.value)
+		})) : [];
+		const shade = (value) => ctx.palette.sequential(value / top);
+		const fills = ctx.marks("surface", "path", bands, (d) => d.value).attr("fill", (d) => shade(d.value));
+		this.reveal(ctx, fills, { d: (d) => d.area }, 10);
+		const tone = (d) => surface ? ctx.theme.ink : ctx.palette.sequential(.15 + .85 * d.density);
+		const shape = symbol(Scales.symbol(marker));
+		const area = (d) => shrink ? MARKER_AREA * (1 - .72 * Math.sqrt(d.density)) : MARKER_AREA;
+		const dots = ctx.marks("dots", "path", ordered, (d) => d.index).attr("fill", tone).attr("stroke", ctx.theme.surface).attr("stroke-width", surface ? 1 : .75).attr("paint-order", "stroke");
+		dots.order();
+		const place = (d) => `translate(${d.px.toFixed(1)},${d.py.toFixed(1)})`;
+		ctx.set(dots, {
+			d: (d) => shape.size(area(d))(),
+			transform: place
+		}, {
+			d: () => shape.size(1)(),
+			transform: place
+		});
+		ctx.hover(dots, (d) => ({
+			color: tone(d),
+			rows: [...this.tipRows(d), ["Density", `${Math.round(d.density * 100)}% of peak`]]
+		}));
+		this.showRamp(ctx, 1, (t) => ctx.palette.sequential(surface ? t : .15 + .85 * t), (t) => `${Math.round(t * 100)}%`);
+	}
+};
+export { DensityScatter, ScatterMode, ScatterStacking };