@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/network/CircularLayoutGraph.js

@@ -0,0 +1,120 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { EdgeRouter } from "./EdgeRouter.js";
+import { GraphOrder } from "./GraphOrder.js";
+import { NetworkEdge, NetworkMetric, NetworkOrder } from "./networkEnums.js";
+import { NetworkSamples } from "./NetworkSamples.js";
+import { NodeLinkNetwork } from "./NodeLinkNetwork.js";
+// src/charts/network/CircularLayoutGraph.ts
+/** One ring of all nodes, or one small ring per group arranged on a larger ring. */
+var CircularArrangement = /* @__PURE__ */ function(CircularArrangement) {
+	CircularArrangement["Ring"] = "ring";
+	CircularArrangement["GroupRings"] = "group-rings";
+	return CircularArrangement;
+}({});
+/** For graphs without a natural layout: a calm ring where order, not physics, reveals structure. */
+var CircularLayoutGraph = class extends NodeLinkNetwork {
+	static meta = {
+		id: "circular-layout-graph",
+		name: "Circular layout graph",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Places nodes on a ring so that ordering and the sweep of links reveal clusters without layout noise.",
+		tags: [
+			"network",
+			"ring",
+			"circular",
+			"node-link"
+		],
+		sample: (seed) => NetworkSamples.clustered(seed, 32, 4),
+		variants: {
+			order: [
+				NetworkOrder.Group,
+				NetworkOrder.Input,
+				NetworkOrder.Degree,
+				NetworkOrder.Community,
+				NetworkOrder.CuthillMcKee,
+				NetworkOrder.Spectral
+			],
+			edge: [
+				NetworkEdge.Curve,
+				NetworkEdge.Straight,
+				NetworkEdge.Bundled
+			],
+			arrangement: ["ring", "group-rings"],
+			nodeSize: [
+				NetworkMetric.Degree,
+				NetworkMetric.Uniform,
+				NetworkMetric.Value
+			]
+		},
+		valid: ({ order, arrangement }) => arrangement === "ring" || order !== NetworkOrder.Degree
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			order: NetworkOrder.Group,
+			edge: NetworkEdge.Curve,
+			arrangement: "ring"
+		};
+	}
+	outer(ctx) {
+		return Math.max(12, Math.min(ctx.plot.width, ctx.plot.height) / 2 - 22);
+	}
+	radii(model, metric, ctx) {
+		const ring = 2 * Math.PI * this.outer(ctx) / model.nodes.length;
+		const room = this.options.arrangement === "ring" ? ring : ring * .6;
+		return this.capped(super.radii(model, metric, ctx), room * .62);
+	}
+	place(ctx, model, radii) {
+		const { x: cx, y: cy } = this.centre(ctx);
+		const outer = this.outer(ctx);
+		const sorted = GraphOrder.sort(model, this.options.order);
+		const points = [];
+		if (this.options.arrangement === "group-rings") {
+			const groups = model.groups;
+			const fan = Math.sin(Math.PI / groups.length);
+			const small = groups.length > 1 ? Math.min(outer * .46, outer * fan / (1 + fan) - Math.max(...radii) - 2) : outer;
+			groups.forEach((group, g) => {
+				const turn = g / groups.length * 2 * Math.PI - Math.PI / 2;
+				const hx = cx + Math.cos(turn) * (groups.length > 1 ? outer - small : 0), hy = cy + Math.sin(turn) * (groups.length > 1 ? outer - small : 0);
+				const members = sorted.filter((node) => node.group === group);
+				members.forEach((node, i) => {
+					const angle = i / members.length * 2 * Math.PI + turn;
+					points[node.index] = {
+						x: hx + Math.cos(angle) * small,
+						y: hy + Math.sin(angle) * small
+					};
+				});
+			});
+			return points;
+		}
+		sorted.forEach((node, i) => {
+			const angle = i / sorted.length * 2 * Math.PI - Math.PI / 2;
+			points[node.index] = {
+				x: cx + Math.cos(angle) * outer,
+				y: cy + Math.sin(angle) * outer
+			};
+		});
+		return points;
+	}
+	routeEdge(_link, input) {
+		const ring = this.options.arrangement === "ring";
+		return EdgeRouter.route(this.options.edge, ring && this.options.edge === NetworkEdge.Bundled ? {
+			...input,
+			via: [input.center],
+			bundle: .7
+		} : input);
+	}
+	drawLabelSide(ctx, placed) {
+		const { x: cx, y: cy } = this.centre(ctx);
+		return placed.map((d) => {
+			const dx = d.x - cx, dy = d.y - cy;
+			return {
+				...d,
+				side: Math.abs(dx) > Math.abs(dy) ? dx > 0 ? "right" : "left" : dy > 0 ? "bottom" : "top"
+			};
+		});
+	}
+};
+export { CircularArrangement, CircularLayoutGraph };

package/dist/charts/network/ClusteredForceChart.js

@@ -0,0 +1,131 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { GraphCommunities } from "./GraphCommunities.js";
+import { GraphLayouts } from "./GraphLayouts.js";
+import { NetworkCommunity, NetworkEdge, NetworkMetric } from "./networkEnums.js";
+import { NetworkSamples } from "./NetworkSamples.js";
+import { NodeLinkNetwork } from "./NodeLinkNetwork.js";
+import { curveCatmullRomClosed, forceX, forceY, line, polygonHull } from "d3";
+// src/charts/network/ClusteredForceChart.ts
+var ClusterArrangement = /* @__PURE__ */ function(ClusterArrangement) {
+	ClusterArrangement["Ring"] = "ring";
+	ClusterArrangement["Grid"] = "grid";
+	ClusterArrangement["Row"] = "row";
+	return ClusterArrangement;
+}({});
+var ClusterHull = /* @__PURE__ */ function(ClusterHull) {
+	ClusterHull["None"] = "none";
+	ClusterHull["Convex"] = "convex";
+	ClusterHull["Rounded"] = "rounded";
+	return ClusterHull;
+}({});
+/** Forces nodes toward a home per cluster, for when the groups matter more than the links between them. */
+var ClusteredForceChart = class extends NodeLinkNetwork {
+	static meta = {
+		id: "clustered-force",
+		name: "Clustered force graph",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Gathers each group around its own centre so cluster membership and the ties between clusters are explicit.",
+		tags: [
+			"network",
+			"cluster",
+			"hull",
+			"bubble sets"
+		],
+		sample: (seed) => NetworkSamples.clustered(seed, 40, 4),
+		variants: {
+			arrangement: [
+				"ring",
+				"grid",
+				"row"
+			],
+			hull: [
+				"rounded",
+				"convex",
+				"none"
+			],
+			communities: [
+				NetworkCommunity.Attribute,
+				NetworkCommunity.Louvain,
+				NetworkCommunity.LabelPropagation
+			],
+			edge: [NetworkEdge.Straight, NetworkEdge.Bundled],
+			nodeSize: [NetworkMetric.Degree, NetworkMetric.Uniform]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			arrangement: "ring",
+			hull: "rounded",
+			communities: NetworkCommunity.Attribute
+		};
+	}
+	view(model) {
+		return GraphCommunities.apply(model, this.options.communities);
+	}
+	homes(ctx, groups) {
+		const { width, height } = ctx.plot, count = groups.length, { arrangement } = this.options;
+		return new Map(groups.map((group, i) => {
+			if (arrangement === "row") return [group, {
+				x: (i + .5) / count * width,
+				y: height / 2
+			}];
+			if (arrangement === "grid") {
+				const columns = Math.ceil(Math.sqrt(count * width / height)), rows = Math.ceil(count / columns);
+				return [group, {
+					x: (i % columns + .5) / columns * width,
+					y: (Math.floor(i / columns) + .5) / rows * height
+				}];
+			}
+			const turn = i / count * 2 * Math.PI - Math.PI / 2;
+			return [group, {
+				x: width / 2 + Math.cos(turn) * width * .3,
+				y: height / 2 + Math.sin(turn) * height * .3
+			}];
+		}));
+	}
+	place(ctx, model, radii) {
+		const homes = this.homes(ctx, model.groups);
+		const home = (index) => homes.get(model.nodes[index].group);
+		const within = 1 / 3;
+		const raw = GraphLayouts.force(model, {
+			box: ctx.plot,
+			radii,
+			gravity: 0,
+			charge: .45,
+			strength: (link) => link.source.group === link.target.group ? .35 : .01,
+			distance: (link) => link.source.group === link.target.group ? Math.sqrt(ctx.plot.width * ctx.plot.height / model.nodes.length) * within : 200,
+			forces: {
+				homeX: forceX((node) => home(node.index).x).strength(.2),
+				homeY: forceY((node) => home(node.index).y).strength(.2)
+			}
+		});
+		return GraphLayouts.relax(GraphLayouts.fit(raw, ctx.plot, Math.max(...radii) + 8), radii, ctx.plot);
+	}
+	hullPath(members) {
+		const ring = members.flatMap(({ x, y, r }) => Array.from({ length: 8 }, (_, k) => {
+			const turn = k / 8 * 2 * Math.PI;
+			return [x + Math.cos(turn) * (r + 6), y + Math.sin(turn) * (r + 6)];
+		}));
+		const hull = polygonHull(ring);
+		if (!hull) return "";
+		const body = (this.options.hull === "rounded" ? line().curve(curveCatmullRomClosed.alpha(.5)) : line())(hull) ?? "";
+		return this.options.hull === "rounded" ? body : `${body}Z`;
+	}
+	underlay(ctx, model, placed) {
+		const shapes = this.options.hull === "none" ? [] : model.groups.map((group) => ({
+			group,
+			d: this.hullPath(placed.filter((d) => d.node.group === group))
+		}));
+		const hulls = ctx.marks("hulls", "path", shapes, (d) => d.group).attr("fill", (d) => ctx.palette.color(d.group)).attr("fill-opacity", .1).attr("stroke", (d) => ctx.palette.color(d.group)).attr("stroke-opacity", .35).attr("stroke-width", 1.5).attr("stroke-linejoin", "round");
+		ctx.set(hulls, { d: (d) => d.d }, { d: (d) => d.d });
+		ctx.hover(hulls, (d) => ({
+			title: d.group,
+			color: ctx.palette.color(d.group),
+			rows: [["Members", placed.filter((p) => p.node.group === d.group).length]]
+		}));
+	}
+};
+export { ClusterArrangement, ClusterHull, ClusteredForceChart };

package/dist/charts/network/CommunityChart.js

@@ -0,0 +1,305 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { GraphCommunities } from "./GraphCommunities.js";
+import { GraphLayouts } from "./GraphLayouts.js";
+import { LabelPlacer } from "./LabelPlacer.js";
+import { NetworkCommunity } from "./networkEnums.js";
+import { NetworkModel } from "./NetworkModel.js";
+import { NetworkChart } from "./NetworkChart.js";
+import { NetworkSamples } from "./NetworkSamples.js";
+import { packEnclose, packSiblings, scaleLinear } from "d3";
+// src/charts/network/CommunityChart.ts
+/** Bubbles roll communities up, Packed keeps their members visible, Blocks is the block-model matrix. */
+var CommunityView = /* @__PURE__ */ function(CommunityView) {
+	CommunityView["Bubbles"] = "bubbles";
+	CommunityView["Packed"] = "packed";
+	CommunityView["Blocks"] = "blocks";
+	return CommunityView;
+}({});
+/** Thickness of the tie between two communities. */
+var CommunityLinkage = /* @__PURE__ */ function(CommunityLinkage) {
+	CommunityLinkage["Count"] = "count";
+	CommunityLinkage["Weight"] = "weight";
+	CommunityLinkage["Density"] = "density";
+	return CommunityLinkage;
+}({});
+var CommunitySize = /* @__PURE__ */ function(CommunitySize) {
+	CommunitySize["Members"] = "members";
+	CommunitySize["Strength"] = "strength";
+	return CommunitySize;
+}({});
+/** Finds or uses communities and reports on them: how large they are and how tightly they tie to each other. */
+var CommunityChart = class extends NetworkChart {
+	static meta = {
+		id: "community-graph",
+		name: "Community graph",
+		family: ChartFamily.Network,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Detects network communities and rolls them up so their sizes and the ties between them can be compared.",
+		tags: [
+			"network",
+			"community",
+			"louvain",
+			"block model",
+			"modularity"
+		],
+		sample: (seed) => NetworkSamples.clustered(seed, 48, 5, 2),
+		variants: {
+			view: [
+				"packed",
+				"bubbles",
+				"blocks"
+			],
+			method: [
+				NetworkCommunity.Louvain,
+				NetworkCommunity.Attribute,
+				NetworkCommunity.LabelPropagation
+			],
+			linkage: [
+				"count",
+				"weight",
+				"density"
+			],
+			sizeBy: ["members", "strength"]
+		},
+		valid: ({ view, linkage }) => view !== "blocks" || linkage === "count"
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			view: "packed",
+			method: NetworkCommunity.Louvain,
+			linkage: "count",
+			sizeBy: "members"
+		};
+	}
+	rollup(model) {
+		const sizes = new Map(model.groups.map((group) => [group, 0])), ties = /* @__PURE__ */ new Map();
+		for (const node of model.nodes) sizes.set(node.group, sizes.get(node.group) + (this.options.sizeBy === "strength" ? node.strength : 1));
+		const count = (group) => model.nodes.filter((node) => node.group === group).length;
+		for (const { source, target, value } of model.links) {
+			const [a, b] = [source.group, target.group].sort(), key = `${a}\u0000${b}`;
+			const tie = ties.get(key) ?? {
+				source: a,
+				target: b,
+				count: 0,
+				weight: 0,
+				density: 0
+			};
+			tie.count++;
+			tie.weight += value;
+			tie.density = tie.count / (a === b ? count(a) * (count(a) - 1) / 2 || 1 : count(a) * count(b));
+			ties.set(key, tie);
+		}
+		return {
+			sizes,
+			ties: [...ties.values()]
+		};
+	}
+	layout(ctx, sizes, ties, radii) {
+		const names = [...sizes.keys()];
+		const data = {
+			nodes: names.map((id) => ({ id })),
+			links: ties.filter((tie) => tie.source !== tie.target).map(({ source, target }) => ({
+				source,
+				target
+			}))
+		};
+		const meta = NetworkModel.from(data);
+		const list = names.map((name) => radii.get(name)), top = Math.max(...list);
+		const raw = GraphLayouts.force(meta, {
+			box: ctx.plot,
+			radii: list,
+			distance: (link) => radii.get(link.source.id) + radii.get(link.target.id) + 24,
+			charge: 1.2
+		});
+		const fitted = GraphLayouts.relax(GraphLayouts.fit(raw, ctx.plot, top + 4), list.map((r) => r + 6), ctx.plot, 120);
+		return new Map(names.map((name, i) => [name, fitted[i]]));
+	}
+	drawBubbles(ctx, model) {
+		const { view, linkage } = this.options, packed = view === "packed";
+		const { sizes, ties } = this.rollup(model);
+		const total = [...sizes.values()].reduce((sum, value) => sum + value, 0) || 1;
+		const area = ctx.plot.width * ctx.plot.height * .34;
+		const radii = new Map([...sizes].map(([group, size]) => [group, Math.max(10, Math.sqrt(area * size / total / Math.PI))]));
+		const members = /* @__PURE__ */ new Map();
+		if (packed) for (const group of model.groups) {
+			const circles = model.nodes.filter((node) => node.group === group).map((node) => ({
+				id: node.id,
+				r: Math.sqrt(1 + node.degree),
+				x: 0,
+				y: 0
+			}));
+			packSiblings(circles);
+			const hull = packEnclose(circles), scale = (radii.get(group) - 3) / (hull?.r || 1);
+			members.set(group, circles.map((c) => ({
+				...c,
+				x: (c.x - hull.x) * scale,
+				y: (c.y - hull.y) * scale,
+				r: c.r * scale
+			})));
+		}
+		const spots = this.layout(ctx, sizes, ties, radii);
+		const bubbles = model.groups.map((group) => ({
+			group,
+			...spots.get(group),
+			r: radii.get(group),
+			members: model.nodes.filter((node) => node.group === group).length,
+			total: sizes.get(group)
+		}));
+		const between = ties.filter((tie) => tie.source !== tie.target);
+		const measure = (tie) => linkage === "weight" ? tie.weight : linkage === "density" ? tie.density : tie.count;
+		const thick = scaleLinear([0, Math.max(...between.map(measure), 1e-9)], [.75, 9]);
+		const lookup = new Map(model.nodes.map((node) => [node.group, node]));
+		const edges = between.map((tie) => {
+			const a = spots.get(tie.source), b = spots.get(tie.target);
+			const source = lookup.get(tie.source), target = lookup.get(tie.target);
+			const span = Math.hypot(b.x - a.x, b.y - a.y) || 1, half = thick(measure(tie)) / 2;
+			const ux = (b.x - a.x) / span, uy = (b.y - a.y) / span;
+			const from = {
+				x: a.x + ux * (radii.get(tie.source) - 1),
+				y: a.y + uy * (radii.get(tie.source) - 1)
+			};
+			const to = {
+				x: b.x - ux * (radii.get(tie.target) - 1),
+				y: b.y - uy * (radii.get(tie.target) - 1)
+			};
+			const corners = [
+				[from, 1],
+				[to, 1],
+				[to, -1],
+				[from, -1]
+			];
+			return {
+				link: {
+					key: `${tie.source}\u0000${tie.target}`,
+					source: {
+						...source,
+						label: tie.source
+					},
+					target: {
+						...target,
+						label: tie.target
+					},
+					value: measure(tie),
+					raw: null
+				},
+				d: `M${corners.map(([p, side]) => `${(p.x - uy * half * side).toFixed(2)},${(p.y + ux * half * side).toFixed(2)}`).join("L")}Z`,
+				solid: true,
+				width: 0,
+				color: ctx.theme.inkMuted,
+				opacity: .4
+			};
+		});
+		ctx.marks("blocks", "rect", []);
+		this.paintEdges(ctx, edges);
+		const dots = ctx.marks("bubbles", "circle", bubbles, (d) => d.group).attr("fill", (d) => ctx.palette.color(d.group)).attr("fill-opacity", packed ? .14 : 1).attr("stroke", (d) => packed ? ctx.palette.color(d.group) : ctx.theme.surface).attr("stroke-opacity", packed ? .4 : 1).attr("stroke-width", packed ? 1.5 : 2);
+		ctx.set(dots, {
+			cx: (d) => d.x,
+			cy: (d) => d.y,
+			r: (d) => d.r
+		}, {
+			cx: (d) => d.x,
+			cy: (d) => d.y,
+			r: 0
+		}, 30);
+		ctx.hover(dots, (d) => ({
+			title: d.group,
+			color: ctx.palette.color(d.group),
+			rows: [["Members", d.members], ["Total", Math.round(d.total)]]
+		}));
+		const placed = packed ? model.nodes.flatMap((node) => {
+			const spot = spots.get(node.group), hit = members.get(node.group).find((c) => c.id === node.id);
+			return [{
+				node,
+				x: spot.x + hit.x,
+				y: spot.y + hit.y,
+				r: Math.max(1.8, hit.r * .86)
+			}];
+		}) : [];
+		this.paintNodes(ctx, model, placed);
+		const tags = packed ? [] : bubbles.filter((d) => d.r > 16).map((d) => ({
+			key: d.group,
+			text: LabelPlacer.clip(d.group.replace("Community ", "#"), d.r * 1.8),
+			x: d.x,
+			y: d.y,
+			fill: ctx.palette.inkOn(ctx.palette.color(d.group))
+		}));
+		const text = ctx.marks("tags", "text", tags, (d) => d.key).text((d) => d.text).attr("text-anchor", "middle").attr("dy", "0.32em").attr("pointer-events", "none");
+		ctx.text(text, 11, "ink").attr("fill", (d) => d.fill);
+		ctx.set(text, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		}, {
+			x: (d) => d.x,
+			y: (d) => d.y
+		});
+	}
+	drawBlocks(ctx, model) {
+		const { sizes, ties } = this.rollup(model);
+		for (const name of [
+			"edges",
+			"arrows",
+			"bubbles",
+			"nodes",
+			"tags"
+		]) ctx.group(name).selectAll("*").remove();
+		const names = model.groups, total = [...sizes.values()].reduce((sum, value) => sum + value, 0) || 1;
+		const side = Math.max(20, Math.min(ctx.plot.width - 60, ctx.plot.height - 8)), left = (ctx.plot.width - side) / 2 + 26;
+		let cursor = 0;
+		const spans = new Map(names.map((name) => {
+			const start = cursor;
+			cursor += sizes.get(name) / total * side;
+			return [name, {
+				start,
+				size: cursor - start
+			}];
+		}));
+		const top = Math.max(1e-9, ...ties.map((tie) => tie.density));
+		const blocks = names.flatMap((a) => names.map((b) => {
+			const tie = ties.find((t) => t.source === a && t.target === b || t.source === b && t.target === a);
+			const x = spans.get(b), y = spans.get(a);
+			return {
+				key: `${a}/${b}`,
+				a,
+				b,
+				x: left + x.start,
+				y: 4 + y.start,
+				width: Math.max(1, x.size - 2),
+				height: Math.max(1, y.size - 2),
+				density: tie?.density ?? 0
+			};
+		}));
+		const cells = ctx.marks("blocks", "rect", blocks, (d) => d.key).attr("rx", 2).attr("fill", (d) => d.density ? ctx.palette.sequential(.15 + .85 * (d.density / top)) : ctx.theme.grid);
+		ctx.set(cells, {
+			x: (d) => d.x,
+			y: (d) => d.y,
+			width: (d) => d.width,
+			height: (d) => d.height
+		}, {
+			x: (d) => d.x,
+			y: (d) => d.y,
+			width: (d) => d.width,
+			height: (d) => d.height
+		}, 6);
+		ctx.hover(cells, (d) => ({
+			title: `${d.a} × ${d.b}`,
+			rows: [["Link density", +d.density.toFixed(3)]]
+		}));
+		this.paintAxisLabels(ctx, names.filter((name) => spans.get(name).size >= 11).map((name) => ({
+			key: name,
+			text: LabelPlacer.clip(name.replace("Community ", "#"), 48),
+			x: left - 6,
+			y: 4 + spans.get(name).start + spans.get(name).size / 2,
+			anchor: "end"
+		})));
+	}
+	view(model) {
+		return GraphCommunities.apply(model, this.options.method);
+	}
+	drawNetwork(ctx, model) {
+		if (this.options.view === "blocks") this.drawBlocks(ctx, model);
+		else this.drawBubbles(ctx, model);
+	}
+};
+export { CommunityChart, CommunityLinkage, CommunitySize, CommunityView };