@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/scatter/GridBinScatter.js

@@ -0,0 +1,98 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BinEncoding, BinnedScatterBase } from "./BinnedScatterBase.js";
+import { extent, max, thresholdFreedmanDiaconis, thresholdScott, thresholdSturges } from "d3";
+// src/charts/scatter/GridBinScatter.ts
+var ScatterBinRule = /* @__PURE__ */ function(ScatterBinRule) {
+	ScatterBinRule["Sturges"] = "sturges";
+	ScatterBinRule["Scott"] = "scott";
+	ScatterBinRule["FreedmanDiaconis"] = "freedman-diaconis";
+	return ScatterBinRule;
+}({});
+var ScatterGridCell = /* @__PURE__ */ function(ScatterGridCell) {
+	ScatterGridCell["Square"] = "square-cells";
+	ScatterGridCell["Circle"] = "circle-cells";
+	return ScatterGridCell;
+}({});
+var RULES = {
+	["sturges"]: thresholdSturges,
+	["scott"]: thresholdScott,
+	["freedman-diaconis"]: thresholdFreedmanDiaconis
+};
+/** A two-dimensional histogram over x/y, with statistical bin-width rules. */
+var GridBinScatter = class extends BinnedScatterBase {
+	static meta = {
+		id: "gridbin-scatter",
+		name: "Grid-binned scatter",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Counts x/y points in a rectangular grid chosen by a statistical bin-width rule.",
+		tags: [
+			"2d histogram",
+			"heatmap",
+			"binned scatter"
+		],
+		sample: (seed) => SampleData.points(seed, 700, 3),
+		variants: {
+			rule: [
+				"scott",
+				"sturges",
+				"freedman-diaconis"
+			],
+			encoding: [BinEncoding.Color, BinEncoding.Both],
+			cell: ["square-cells", "circle-cells"],
+			raw: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			rule: "scott",
+			cell: "square-cells"
+		};
+	}
+	plotPoints(ctx, _axes, points) {
+		const { rule, cell } = this.options, { width, height } = ctx.plot;
+		const divisions = (values, top) => {
+			const [low = 0, high = top] = extent(values);
+			return Math.max(2, Math.min(40, RULES[rule](values, low, high) || 2));
+		};
+		const columns = divisions(points.map((p) => p.px), width), rows = divisions(points.map((p) => p.py), height);
+		const cw = width / columns, ch = height / rows;
+		const cells = /* @__PURE__ */ new Map();
+		for (const point of points) {
+			const col = Math.min(columns - 1, Math.floor(point.px / cw)), row = Math.min(rows - 1, Math.floor(point.py / ch)), key = `${col}/${row}`;
+			if (!cells.has(key)) cells.set(key, {
+				col,
+				row,
+				points: []
+			});
+			cells.get(key).points.push(point);
+		}
+		const list = [...cells.values()], peak = max(list, (d) => d.points.length) ?? 1;
+		const span = (d) => this.extent(this.share(d.points.length, peak));
+		const color = (d) => this.shade(ctx, this.share(d.points.length, peak));
+		const key = (d) => `${d.col}/${d.row}`;
+		this.drawRaw(ctx, points);
+		const squares = ctx.marks("squares", "rect", cell === "square-cells" ? list : [], key).attr("fill", color).attr("rx", 2);
+		ctx.set(squares, {
+			x: (d) => (d.col + .5 - span(d) / 2) * cw + 1,
+			y: (d) => (d.row + .5 - span(d) / 2) * ch + 1,
+			width: (d) => Math.max(1, cw * span(d) - 2),
+			height: (d) => Math.max(1, ch * span(d) - 2)
+		});
+		const circles = ctx.marks("circles", "circle", cell === "circle-cells" ? list : [], key).attr("fill", color);
+		ctx.set(circles, {
+			cx: (d) => (d.col + .5) * cw,
+			cy: (d) => (d.row + .5) * ch,
+			r: (d) => Math.max(1, (Math.min(cw, ch) / 2 - 1) * span(d))
+		});
+		for (const marks of [squares, circles]) ctx.hover(marks, (d) => ({
+			title: `${d.points.length} points`,
+			color: color(d)
+		}));
+		this.drawCountKey(ctx, points, peak, (t) => this.shade(ctx, t));
+	}
+};
+export { GridBinScatter, ScatterBinRule, ScatterGridCell };

package/dist/charts/scatter/HexbinScatter.js

@@ -0,0 +1,74 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BinCount, BinEncoding, BinnedScatterBase } from "./BinnedScatterBase.js";
+import { max } from "d3";
+import { hexbin } from "d3-hexbin";
+// src/charts/scatter/HexbinScatter.ts
+/** Hexagonal binning for overplotted scatters: thousands of points become a count surface. */
+var HexbinScatter = class extends BinnedScatterBase {
+	static meta = {
+		id: "hexbin-scatter",
+		name: "Hexbin scatter",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Bins dense x/y points into hexagons and shows the count in each.",
+		tags: [
+			"hexagonal binning",
+			"density",
+			"overplotting",
+			"big data"
+		],
+		sample: (seed) => SampleData.points(seed, 900, 3),
+		variants: {
+			encoding: [BinEncoding.Color, BinEncoding.Both],
+			count: [
+				BinCount.Linear,
+				BinCount.Sqrt,
+				BinCount.Log
+			],
+			binRadius: [
+				11,
+				7,
+				16
+			],
+			lattice: [false, true],
+			raw: [false, true]
+		},
+		valid: (v) => v.encoding !== BinEncoding.Color || v.count === BinCount.Linear
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			binRadius: 11,
+			lattice: false
+		};
+	}
+	inset() {
+		return this.options.binRadius;
+	}
+	plotPoints(ctx, _axes, points) {
+		const { width, height } = ctx.plot, { binRadius, lattice } = this.options;
+		const layout = hexbin().x((d) => d.px).y((d) => d.py).radius(binRadius).extent([[binRadius, binRadius], [width - binRadius, height - binRadius]]);
+		const bins = layout(points).map((bin) => bin);
+		const peak = max(bins, (bin) => bin.length) ?? 1;
+		const mesh = ctx.marks("lattice", "path", lattice ? [layout.mesh()] : []).attr("fill", "none").attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+		ctx.set(mesh, { d: (d) => d });
+		this.drawRaw(ctx, points);
+		const inner = Math.max(1, binRadius - 1);
+		const hexes = ctx.marks("hexes", "path", bins, (bin) => `${bin.x},${bin.y}`).attr("fill", (bin) => this.shade(ctx, this.share(bin.length, peak))).attr("stroke", ctx.theme.surface).attr("stroke-width", 1);
+		ctx.set(hexes, {
+			d: (bin) => layout.hexagon(inner * this.extent(this.share(bin.length, peak))),
+			transform: (bin) => `translate(${bin.x},${bin.y})`
+		}, {
+			transform: (bin) => `translate(${bin.x},${bin.y})`,
+			d: layout.hexagon(.01)
+		}, 1);
+		ctx.hover(hexes, (bin) => ({
+			title: `${bin.length} points`,
+			color: this.shade(ctx, this.share(bin.length, peak))
+		}));
+		this.drawCountKey(ctx, points, peak, (t) => this.shade(ctx, t));
+	}
+};
+export { HexbinScatter };

package/dist/charts/scatter/JitterPlot.js

@@ -0,0 +1,103 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { CategoryScatterBase, CategorySummary } from "./CategoryScatterBase.js";
+import { randomLcg, randomNormal } from "d3";
+// src/charts/scatter/JitterPlot.ts
+var JitterMethod = /* @__PURE__ */ function(JitterMethod) {
+	JitterMethod["Uniform"] = "uniform";
+	JitterMethod["Gaussian"] = "gaussian";
+	JitterMethod["Quasi"] = "quasirandom";
+	JitterMethod["Sina"] = "sina";
+	return JitterMethod;
+}({});
+var GOLDEN = .6180339887;
+/** Raw points per category with random or density-aware spread, for honest small-sample comparison. */
+var JitterPlot = class extends CategoryScatterBase {
+	static meta = {
+		id: "jitter-scatter",
+		name: "Jitter plot",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Spreads overlapping points across each category so every observation stays visible.",
+		tags: [
+			"sina",
+			"quasirandom",
+			"dot plot",
+			"strip"
+		],
+		sample: (seed) => SampleData.distribution(seed, 60, 4),
+		variants: {
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			jitter: [
+				"sina",
+				"uniform",
+				"gaussian",
+				"quasirandom"
+			],
+			summary: [
+				CategorySummary.Median,
+				CategorySummary.None,
+				CategorySummary.Mean,
+				CategorySummary.Box
+			],
+			spread: [
+				.7,
+				.4,
+				.95
+			]
+		},
+		valid: (v) => !(v.jitter === "gaussian" && v.spread === .95)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			jitter: "sina",
+			spread: .7,
+			summary: CategorySummary.Median
+		};
+	}
+	/** Offsets in -1..1, deterministic so re-renders do not shuffle points. */
+	offsets(lane) {
+		const count = lane.points.length, method = this.options.jitter;
+		const random = randomLcg(.37);
+		if (method === "uniform") return lane.points.map(() => random() * 2 - 1);
+		if (method === "gaussian") {
+			const normal = randomNormal.source(random)(0, .4);
+			return lane.points.map(() => Math.max(-1, Math.min(1, normal())));
+		}
+		const quasi = lane.points.map((_, i) => i * GOLDEN % 1 * 2 - 1);
+		if (method === "quasirandom") return quasi;
+		const values = lane.points.map((point) => point.value);
+		const low = Math.min(...values), bandwidth = (Math.max(...values) - low) / 6 || 1;
+		const density = values.map((v) => values.reduce((sum, other) => sum + Math.exp(-(((v - other) / bandwidth) ** 2) / 2), 0) / count);
+		const peak = Math.max(...density);
+		return quasi.map((offset, i) => offset * (density[i] / peak));
+	}
+	plotLanes(ctx, axes, lanes) {
+		const spread = this.options.spread;
+		const dots = lanes.flatMap((lane) => {
+			const offsets = this.offsets(lane);
+			return lane.points.map((point, i) => {
+				const [px, py] = this.place(axes, lane, point.value, offsets[i] * (lane.breadth / 2) * spread);
+				return {
+					...point,
+					px,
+					py
+				};
+			});
+		});
+		const marks = ctx.marks("dots", "circle", dots, (d) => d.index).attr("fill", (d) => ctx.palette.color(d.group)).attr("fill-opacity", .78).attr("stroke", ctx.theme.surface).attr("stroke-width", 1.5);
+		ctx.set(marks, {
+			cx: (d) => d.px,
+			cy: (d) => d.py,
+			r: this.options.radius
+		}, {
+			cx: (d) => d.px,
+			cy: (d) => d.py,
+			r: 0
+		}, 1);
+		ctx.hover(marks, (d) => this.tooltip(ctx, d));
+	}
+};
+export { JitterMethod, JitterPlot };

package/dist/charts/scatter/LabelledScatter.js

@@ -0,0 +1,272 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { ScatterBase } from "./ScatterBase.js";
+import { descending, forceCollide, forceLink, forceSimulation, forceX, forceY, mean } from "d3";
+// src/charts/scatter/LabelledScatter.ts
+var LabelSelection = /* @__PURE__ */ function(LabelSelection) {
+	LabelSelection["Extremes"] = "extremes";
+	LabelSelection["Largest"] = "largest";
+	LabelSelection["Spread"] = "spread";
+	return LabelSelection;
+}({});
+var LabelLayout = /* @__PURE__ */ function(LabelLayout) {
+	LabelLayout["Greedy"] = "greedy";
+	LabelLayout["Force"] = "force";
+	LabelLayout["Margin"] = "margin-column";
+	return LabelLayout;
+}({});
+var LabelLeader = /* @__PURE__ */ function(LabelLeader) {
+	LabelLeader["Straight"] = "straight-leader";
+	LabelLeader["Elbow"] = "elbow-leader";
+	LabelLeader["None"] = "no-leader";
+	return LabelLeader;
+}({});
+var CHAR = 6.2;
+var LINE = 14;
+var COLUMN = 84;
+var overlaps = (a, b) => a.x < b.x + b.w + 2 && b.x < a.x + a.w + 2 && a.y < b.y + b.h && b.y < a.y + a.h;
+var sized = (text) => ({
+	w: text.length * CHAR,
+	h: LINE
+});
+function namedPoints(seed) {
+	const words = SampleData.words(seed);
+	return SampleData.points(seed, words.length, 3).map((row, i) => ({
+		...row,
+		label: String(words[i].text)
+	}));
+}
+/** Direct labels on the points that matter, placed to avoid each other and the data. */
+var LabelledScatter = class extends ScatterBase {
+	static meta = {
+		id: "labelled-scatter",
+		name: "Labelled scatter",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Names selected points directly, with collision-free label placement and leader lines.",
+		tags: [
+			"annotated scatter",
+			"direct labels",
+			"label placement",
+			"repel"
+		],
+		sample: namedPoints,
+		variants: {
+			layout: [
+				"greedy",
+				"force",
+				"margin-column"
+			],
+			selection: [
+				"extremes",
+				"largest",
+				"spread"
+			],
+			leader: [
+				"straight-leader",
+				"elbow-leader",
+				"no-leader"
+			],
+			labelled: [
+				8,
+				5,
+				12
+			]
+		},
+		valid: (v) => v.layout !== "margin-column" || v.leader !== "no-leader"
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			selection: "extremes",
+			layout: "greedy",
+			leader: "straight-leader",
+			labelled: 8
+		};
+	}
+	frame(ctx) {
+		return {
+			...super.frame(ctx),
+			right: ctx.plot.width - (this.options.layout === "margin-column" ? COLUMN : 0)
+		};
+	}
+	chosen(points) {
+		const named = points.filter((point) => point.label), count = this.options.labelled;
+		const { selection } = this.options;
+		if (selection === "largest") return [...named].sort((a, b) => descending(a.size, b.size)).slice(0, count);
+		if (selection === "extremes") {
+			const cx = mean(named, (p) => p.px) ?? 0, cy = mean(named, (p) => p.py) ?? 0;
+			return [...named].sort((a, b) => descending(Math.hypot(a.px - cx, a.py - cy), Math.hypot(b.px - cx, b.py - cy))).slice(0, count);
+		}
+		const picked = named.slice(0, 1);
+		while (picked.length < Math.min(count, named.length)) {
+			const distance = (point) => Math.min(...picked.map((other) => Math.hypot(point.px - other.px, point.py - other.py)));
+			picked.push([...named].sort((a, b) => descending(distance(a), distance(b)))[0]);
+		}
+		return picked;
+	}
+	inside(ctx, box) {
+		return box.x >= 0 && box.y >= 0 && box.x + box.w <= ctx.plot.width && box.y + box.h <= ctx.plot.height;
+	}
+	greedy(ctx, chosen, points) {
+		const obstacles = points.map((p) => ({
+			x: p.px - 4,
+			y: p.py - 4,
+			w: 8,
+			h: 8
+		})), placed = [];
+		for (const point of chosen) {
+			const { w, h } = sized(point.label);
+			const hit = [
+				7,
+				20,
+				34
+			].flatMap((d) => [
+				{
+					x: point.px + d,
+					y: point.py - h / 2
+				},
+				{
+					x: point.px - d - w,
+					y: point.py - h / 2
+				},
+				{
+					x: point.px - w / 2,
+					y: point.py - d - h
+				},
+				{
+					x: point.px - w / 2,
+					y: point.py + d
+				},
+				{
+					x: point.px + d,
+					y: point.py - d - h
+				},
+				{
+					x: point.px - d - w,
+					y: point.py - d - h
+				},
+				{
+					x: point.px + d,
+					y: point.py + d
+				},
+				{
+					x: point.px - d - w,
+					y: point.py + d
+				}
+			]).find((spot) => {
+				const box = {
+					x: spot.x,
+					y: spot.y,
+					w,
+					h
+				};
+				return this.inside(ctx, box) && !obstacles.some((other) => overlaps(box, other));
+			});
+			if (!hit) continue;
+			const box = {
+				x: hit.x,
+				y: hit.y,
+				w,
+				h
+			};
+			obstacles.push(box);
+			placed.push({
+				point,
+				box
+			});
+		}
+		return placed;
+	}
+	force(ctx, chosen) {
+		const nodes = chosen.map((point) => ({
+			point,
+			...sized(point.label),
+			x: point.px,
+			y: point.py - 16
+		}));
+		const anchors = chosen.map((point) => ({
+			fx: point.px,
+			fy: point.py,
+			x: point.px,
+			y: point.py
+		}));
+		const all = [...nodes, ...anchors];
+		forceSimulation(all).stop().force("hold", forceLink(nodes.map((_, i) => ({
+			source: i,
+			target: i + nodes.length
+		}))).distance(26).strength(.6)).force("x", forceX(ctx.plot.width / 2).strength(.01)).force("y", forceY(ctx.plot.height / 2).strength(.01)).force("collide", forceCollide((d) => d.w ? d.w / 2 + 3 : 7)).tick(180);
+		const placed = [];
+		for (const node of nodes) {
+			const box = {
+				x: Math.max(0, Math.min(ctx.plot.width - node.w, node.x - node.w / 2)),
+				y: Math.max(0, Math.min(ctx.plot.height - node.h, node.y - node.h / 2)),
+				w: node.w,
+				h: node.h
+			};
+			if (!placed.some((other) => overlaps(box, other.box))) placed.push({
+				point: node.point,
+				box
+			});
+		}
+		return placed;
+	}
+	column(ctx, chosen) {
+		const { height, width } = ctx.plot, room = Math.floor(height / LINE);
+		const ordered = [...chosen].slice(0, room).sort((a, b) => a.py - b.py);
+		const slots = ordered.map((point) => point.py - LINE / 2);
+		slots.forEach((slot, i) => {
+			slots[i] = Math.max(slot, i ? slots[i - 1] + LINE : 0);
+		});
+		let ceiling = height - LINE;
+		for (let i = slots.length - 1; i >= 0; i--) {
+			slots[i] = Math.min(slots[i], ceiling);
+			ceiling = slots[i] - LINE;
+		}
+		return ordered.map((point, i) => {
+			const { w, h } = sized(point.label.length * CHAR > 70 ? `${point.label.slice(0, Math.floor(70 / CHAR) - 1)}…` : point.label);
+			return {
+				point,
+				box: {
+					x: width - COLUMN + 12,
+					y: slots[i],
+					w,
+					h
+				}
+			};
+		});
+	}
+	plotPoints(ctx, _axes, points) {
+		const { layout, leader } = this.options;
+		const chosen = this.chosen(points);
+		const placed = layout === "margin-column" ? this.column(ctx, chosen) : layout === "force" ? this.force(ctx, chosen) : this.greedy(ctx, chosen, points);
+		const named = new Set(placed.map((item) => item.point.index));
+		const pale = ctx.theme.inkMuted;
+		const faint = points.filter((point) => !named.has(point.index));
+		const anchor = (d) => {
+			const midY = d.box.y + d.box.h / 2;
+			return [d.box.x > d.point.px ? d.box.x - 2 : d.box.x + d.box.w < d.point.px ? d.box.x + d.box.w + 2 : d.box.x + d.box.w / 2, d.box.y + d.box.h < d.point.py ? d.box.y + d.box.h : d.box.y > d.point.py ? d.box.y : midY];
+		};
+		const leaders = leader === "no-leader" ? [] : placed;
+		const paths = ctx.marks("leaders", "path", leaders, (d) => d.point.index).attr("fill", "none").attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		ctx.set(paths, { d: (d) => {
+			const [x, y] = anchor(d), { px, py } = d.point;
+			return leader === "elbow-leader" ? `M${px},${py}L${px + (x - px) * .3},${y}L${x},${y}` : `M${px},${py}L${x},${y}`;
+		} });
+		this.drawDots(ctx, faint, {
+			fill: () => pale,
+			radius: this.options.radius - 1,
+			name: "context"
+		});
+		this.drawDots(ctx, placed.map((item) => item.point));
+		const label = ctx.marks("labels", "text", placed, (d) => d.point.index).text((d) => d.box.w < d.point.label.length * CHAR ? `${d.point.label.slice(0, Math.floor(d.box.w / CHAR))}…` : d.point.label);
+		ctx.text(label, 11, "ink");
+		this.halo(label, ctx);
+		ctx.set(label, {
+			x: (d) => d.box.x,
+			y: (d) => d.box.y + 11
+		});
+	}
+};
+export { LabelLayout, LabelLeader, LabelSelection, LabelledScatter };