@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/geoflows/GeoLinkChart.js

@@ -0,0 +1,155 @@
+import { FlowGeometry } from "./FlowGeometry.js";
+import { GeoFlowChart, hasPlace, reading } from "./GeoFlowChart.js";
+import { ascending, rollup, scaleLinear } from "d3";
+// src/charts/geoflows/GeoLinkChart.ts
+/** How a flow travels across the map. */
+var GeoFlowRoute = /* @__PURE__ */ function(GeoFlowRoute) {
+	GeoFlowRoute["Arc"] = "arc";
+	GeoFlowRoute["Geodesic"] = "geodesic";
+	GeoFlowRoute["Straight"] = "straight";
+	GeoFlowRoute["Bundled"] = "bundled";
+	return GeoFlowRoute;
+}({});
+/** Base of the charts that take origin-destination rows. Rows without both ends are skipped, self-loops included. */
+var GeoLinkChart = class extends GeoFlowChart {
+	parsed = null;
+	defaults() {
+		return {
+			...super.defaults(),
+			source: "source",
+			target: "target",
+			sourceLon: "sourceLon",
+			sourceLat: "sourceLat",
+			targetLon: "targetLon",
+			targetLat: "targetLat",
+			value: "value",
+			series: "series"
+		};
+	}
+	parse() {
+		const { data, source, target, sourceLon, sourceLat, targetLon, targetLat, value, series } = this.options;
+		if (this.parsed?.data === data) return this.parsed;
+		const links = (data ?? []).flatMap((row, id) => {
+			const from = [reading(row[sourceLon]), reading(row[sourceLat])], to = [reading(row[targetLon]), reading(row[targetLat])];
+			if (!hasPlace(from) || !hasPlace(to) || from[0] === to[0] && from[1] === to[1]) return [];
+			const size = Math.abs(reading(row[value]));
+			return [{
+				id,
+				source: String(row[source] ?? from),
+				target: String(row[target] ?? to),
+				from,
+				to,
+				value: Number.isFinite(size) ? size : 1,
+				series: String(row[series] ?? ""),
+				row
+			}];
+		});
+		const stops = /* @__PURE__ */ new Map();
+		const stop = (name, place) => {
+			let hit = stops.get(name);
+			if (!hit) stops.set(name, hit = {
+				name,
+				place,
+				inflow: 0,
+				outflow: 0,
+				degree: 0
+			});
+			return hit;
+		};
+		for (const link of links) {
+			const a = stop(link.source, link.from), b = stop(link.target, link.to);
+			a.outflow += link.value;
+			a.degree++;
+			b.inflow += link.value;
+			b.degree++;
+		}
+		return this.parsed = {
+			data,
+			links,
+			stops: [...stops.values()]
+		};
+	}
+	get links() {
+		return this.parse().links;
+	}
+	get stops() {
+		return this.parse().stops;
+	}
+	categorical() {
+		return new Set(this.links.map((link) => link.series)).size > 1;
+	}
+	points() {
+		return this.stops.map((stop) => stop.place);
+	}
+	subject() {
+		return this.links.length ? {
+			type: "MultiLineString",
+			coordinates: this.links.map((link) => [link.from, link.to])
+		} : null;
+	}
+	tint(ctx, link) {
+		return ctx.palette.color(link.series || "Flow");
+	}
+	widthScale(links, most = 9) {
+		return scaleLinear([0, GeoFlowChart.peakOf(links, (link) => link.value)], [1.5, most]);
+	}
+	/** Screen path of a link for routes that bend on the page. Null when an end is out of view. */
+	screenRoute(frame, link, route) {
+		const a = frame.at(link.from), b = frame.at(link.to);
+		if (!a || !b) return null;
+		return (route === "straight" ? FlowGeometry.straight(a, b) : FlowGeometry.arc(a, b)).map(([x, y]) => [Math.max(0, Math.min(frame.width, x)), Math.max(0, Math.min(frame.height, y))]);
+	}
+	/** Bundled screen paths, keyed by link id; links with an end out of view are absent. */
+	bundled(frame, links) {
+		const shown = links.flatMap((link) => {
+			const a = frame.at(link.from), b = frame.at(link.to);
+			return a && b ? [{
+				link,
+				ends: [a, b]
+			}] : [];
+		});
+		const paths = FlowGeometry.bundle(shown.map((item) => item.ends));
+		return new Map(shown.map((item, i) => [item.link.id, paths[i]]));
+	}
+	/** Node dots: area follows throughput, with a surface ring so they sit clear of the lines. */
+	stopDots(ctx, frame, stops, radius) {
+		const shown = stops.flatMap((stop) => {
+			const at = frame.at(stop.place);
+			return at ? [{
+				stop,
+				at
+			}] : [];
+		}).sort((a, b) => ascending(radius(b.stop), radius(a.stop)));
+		const dots = ctx.marks("stops", "circle", shown, (d) => d.stop.name).attr("fill", ctx.theme.ink).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: (d) => d.at[0],
+			cy: (d) => d.at[1],
+			r: (d) => radius(d.stop)
+		}, { r: 0 });
+		return ctx.hover(dots, (d) => ({
+			title: d.stop.name,
+			rows: [
+				["In", d.stop.inflow],
+				["Out", d.stop.outflow],
+				["Links", d.stop.degree]
+			]
+		}));
+	}
+	/** Busiest stops first, ready for `labels`. */
+	stopLabels(frame, stops, radius) {
+		const total = (stop) => stop.inflow + stop.outflow;
+		return [...stops].sort((a, b) => total(b) - total(a)).flatMap((stop) => {
+			const at = frame.at(stop.place);
+			return at ? [{
+				text: stop.name,
+				x: at[0],
+				y: at[1],
+				gap: radius(stop)
+			}] : [];
+		});
+	}
+	totals(links, key) {
+		return rollup(links, (rows) => rows.reduce((sum, link) => sum + link.value, 0), key);
+	}
+};
+export { GeoFlowRoute, GeoLinkChart };

package/dist/charts/geoflows/GeoPointChart.js

@@ -0,0 +1,42 @@
+import { GeoFlowChart, hasPlace, reading } from "./GeoFlowChart.js";
+// src/charts/geoflows/GeoPointChart.ts
+/** Base of the charts that take one row per place. Rows without a position are skipped. */
+var GeoPointChart = class extends GeoFlowChart {
+	parsed = null;
+	defaults() {
+		return {
+			...super.defaults(),
+			name: "name",
+			lon: "lon",
+			lat: "lat",
+			value: "value",
+			series: "series"
+		};
+	}
+	get places() {
+		const { data, name, lon, lat, value, series } = this.options;
+		if (this.parsed?.data === data) return this.parsed.places;
+		const places = (data ?? []).flatMap((row, id) => {
+			const place = [reading(row[lon]), reading(row[lat])];
+			if (!hasPlace(place)) return [];
+			const size = reading(row[value]);
+			return [{
+				id,
+				name: String(row[name] ?? id),
+				place,
+				value: Number.isFinite(size) ? size : 0,
+				series: String(row[series] ?? ""),
+				row
+			}];
+		});
+		this.parsed = {
+			data,
+			places
+		};
+		return places;
+	}
+	points() {
+		return this.places.map((place) => place.place);
+	}
+};
+export { GeoPointChart };

package/dist/charts/geoflows/GeoSankey.js

@@ -0,0 +1,167 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { FlowGeometry } from "./FlowGeometry.js";
+import { GeoFlowChart } from "./GeoFlowChart.js";
+import { GeoFlowProjection } from "./GeoFlowFrame.js";
+import { GeoFlowSample } from "./GeoFlowSample.js";
+import { GeoLinkChart } from "./GeoLinkChart.js";
+import { ascending, sum } from "d3";
+// src/charts/geoflows/GeoSankey.ts
+/** How a place is drawn where the bands meet. */
+var GeoSankeyNode = /* @__PURE__ */ function(GeoSankeyNode) {
+	GeoSankeyNode["Bar"] = "bar";
+	GeoSankeyNode["Tick"] = "tick";
+	GeoSankeyNode["Disc"] = "disc";
+	return GeoSankeyNode;
+}({});
+/** How a band runs between two places. */
+var GeoSankeyCurve = /* @__PURE__ */ function(GeoSankeyCurve) {
+	GeoSankeyCurve["Bump"] = "bump";
+	GeoSankeyCurve["Straight"] = "straight";
+	GeoSankeyCurve["Arc"] = "arc";
+	return GeoSankeyCurve;
+}({});
+/** How bands stack at a place. */
+var GeoSankeyOrder = /* @__PURE__ */ function(GeoSankeyOrder) {
+	GeoSankeyOrder["Position"] = "position";
+	GeoSankeyOrder["Size"] = "size";
+	return GeoSankeyOrder;
+}({});
+/** Show flows that conserve quantity on real geography: every place's bar is exactly as long as the bands stacked against it. */
+var GeoSankey = class extends GeoLinkChart {
+	static meta = {
+		id: "geo-sankey",
+		name: "Geographic Sankey",
+		family: ChartFamily.Geospatial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Places a Sankey on a map: bands of constant width stack at each location so totals add up visually.",
+		tags: [
+			"sankey",
+			"ribbon",
+			"stacked flows"
+		],
+		sample: (seed) => GeoFlowSample.flows(seed, 14, GeoFlowSample.spaced),
+		variants: {
+			projection: [
+				GeoFlowProjection.NaturalEarth,
+				GeoFlowProjection.Equirectangular,
+				GeoFlowProjection.Mercator,
+				GeoFlowProjection.EqualEarth
+			],
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			node: [
+				"bar",
+				"tick",
+				"disc"
+			],
+			curve: [
+				"bump",
+				"straight",
+				"arc"
+			],
+			order: ["position", "size"]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			orientation: Orientation.Vertical,
+			node: "bar",
+			curve: "bump",
+			order: "position"
+		};
+	}
+	path(band, across) {
+		const { curve } = this.options;
+		if (curve === "straight") return FlowGeometry.straight(band.a, band.b, 2);
+		if (curve === "arc") return FlowGeometry.arc(band.a, band.b, .16, 20);
+		const axis = across ? 0 : 1;
+		const pull = Math.max(24, Math.abs(band.b[axis] - band.a[axis]) / 2);
+		const c1 = across ? [band.a[0] + pull, band.a[1]] : [band.a[0], band.a[1] + pull];
+		const c2 = across ? [band.b[0] - pull, band.b[1]] : [band.b[0], band.b[1] - pull];
+		return Array.from({ length: 25 }, (_, i) => {
+			const t = i / 24, s = 1 - t;
+			const mix = (k) => s ** 3 * band.a[k] + 3 * s * s * t * c1[k] + 3 * s * t * t * c2[k] + t ** 3 * band.b[k];
+			return [mix(0), mix(1)];
+		});
+	}
+	plotGeo(ctx, frame) {
+		const { orientation, node, order } = this.options;
+		const across = orientation === Orientation.Vertical;
+		const anchors = new Map(this.stops.flatMap((stop) => {
+			const at = frame.at(stop.place);
+			return at ? [[stop.name, {
+				stop,
+				at,
+				size: Math.max(stop.inflow, stop.outflow)
+			}]] : [];
+		}));
+		const peak = GeoFlowChart.peakOf([...anchors.values()], (anchor) => anchor.size);
+		const unit = Math.min(ctx.plot.height, ctx.plot.width) * .2 / peak;
+		const links = this.links.filter((link) => anchors.has(link.source) && anchors.has(link.target));
+		const barWidth = node === "tick" ? 3 : 8;
+		const across1 = across ? 1 : 0;
+		const stack = (name, rows, other, side) => {
+			const anchor = anchors.get(name);
+			const sorted = [...rows].sort(order === "size" ? (a, b) => b.value - a.value : (a, b) => ascending(anchors.get(other(a)).at[across1], anchors.get(other(b)).at[across1]));
+			let cursor = anchor.at[across1] - sum(sorted, (link) => link.value) * unit / 2;
+			return sorted.map((link) => {
+				const thick = link.value * unit, mid = cursor + thick / 2;
+				cursor += thick;
+				const point = across ? [anchor.at[0] + side * barWidth / 2, mid] : [mid, anchor.at[1] + side * barWidth / 2];
+				return [link.id, point];
+			});
+		};
+		const starts = new Map([...anchors.keys()].flatMap((name) => stack(name, links.filter((link) => link.source === name), (link) => link.target, 1)));
+		const ends = new Map([...anchors.keys()].flatMap((name) => stack(name, links.filter((link) => link.target === name), (link) => link.source, -1)));
+		const bands = links.map((link) => ({
+			link,
+			thick: link.value * unit,
+			a: starts.get(link.id),
+			b: ends.get(link.id)
+		})).sort((a, b) => b.thick - a.thick);
+		const ribbons = ctx.marks("bands", "path", bands, (d) => d.link.id).attr("fill", (d) => this.tint(ctx, d.link)).attr("fill-opacity", .62).attr("stroke", ctx.theme.surface).attr("stroke-width", .75);
+		const shape = (d) => FlowGeometry.ribbon(this.path(d, across), () => Math.max(1, d.thick));
+		ctx.set(ribbons, { d: shape }, { d: shape });
+		ctx.hover(ribbons, (d) => ({
+			title: `${d.link.source} → ${d.link.target}`,
+			color: this.tint(ctx, d.link),
+			rows: [["Flow", d.link.value]]
+		}));
+		const places = [...anchors.values()];
+		const length = (d) => Math.max(4, d.size * unit);
+		const blocks = ctx.marks("nodes", "rect", node === "disc" ? [] : places, (d) => d.stop.name).attr("fill", ctx.theme.ink).attr("rx", 2);
+		ctx.set(blocks, across ? {
+			x: (d) => d.at[0] - barWidth / 2,
+			width: barWidth,
+			y: (d) => d.at[1] - length(d) / 2,
+			height: length
+		} : {
+			y: (d) => d.at[1] - barWidth / 2,
+			height: barWidth,
+			x: (d) => d.at[0] - length(d) / 2,
+			width: length
+		});
+		ctx.hover(blocks, (d) => ({
+			title: d.stop.name,
+			rows: [["In", d.stop.inflow], ["Out", d.stop.outflow]]
+		}));
+		const discs = ctx.marks("discs", "circle", node === "disc" ? places : [], (d) => d.stop.name).attr("fill", ctx.theme.inkSecondary).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(discs, {
+			cx: (d) => d.at[0],
+			cy: (d) => d.at[1],
+			r: (d) => Math.max(4, length(d) / 2)
+		}, { r: 0 });
+		ctx.hover(discs, (d) => ({
+			title: d.stop.name,
+			rows: [["In", d.stop.inflow], ["Out", d.stop.outflow]]
+		}));
+		this.labels(ctx, [...places].sort((a, b) => b.size - a.size).map((d) => ({
+			text: d.stop.name,
+			x: d.at[0],
+			y: d.at[1],
+			gap: across ? barWidth : length(d) / 2
+		})), "labels", 6);
+	}
+};
+export { GeoSankey, GeoSankeyCurve, GeoSankeyNode, GeoSankeyOrder };

package/dist/charts/geoflows/GeoTrackChart.js

@@ -0,0 +1,60 @@
+import { GeoFlowChart, hasPlace, reading } from "./GeoFlowChart.js";
+import { ascending, flatGroup } from "d3";
+// src/charts/geoflows/GeoTrackChart.ts
+/** Base of the charts that take ordered positions along named paths. Rows without a position are skipped. */
+var GeoTrackChart = class extends GeoFlowChart {
+	parsed = null;
+	defaults() {
+		return {
+			...super.defaults(),
+			track: "track",
+			lon: "lon",
+			lat: "lat",
+			time: "time",
+			value: "value"
+		};
+	}
+	get tracks() {
+		const { data, track, lon, lat, time, value } = this.options;
+		if (this.parsed?.data === data) return this.parsed.tracks;
+		const fixes = (data ?? []).flatMap((row, index) => {
+			const place = [reading(row[lon]), reading(row[lat])];
+			if (!hasPlace(place)) return [];
+			const when = row[time];
+			return [{
+				name: String(row[track] ?? ""),
+				place,
+				time: when instanceof Date ? +when : Number.isFinite(reading(when)) ? reading(when) : index,
+				value: reading(row[value]),
+				row
+			}];
+		});
+		const tracks = flatGroup(fixes, (fix) => fix.name).map(([name, rows]) => ({
+			name,
+			fixes: [...rows].sort((a, b) => ascending(a.time, b.time))
+		}));
+		this.parsed = {
+			data,
+			tracks
+		};
+		return tracks;
+	}
+	points() {
+		return this.tracks.flatMap((track) => track.fixes.map((fix) => fix.place));
+	}
+	categorical() {
+		return this.tracks.length > 1;
+	}
+	subject() {
+		const lines = this.tracks.map((track) => track.fixes.map((fix) => fix.place)).filter((line) => line.length > 1);
+		return lines.length ? {
+			type: "MultiLineString",
+			coordinates: lines
+		} : super.subject();
+	}
+	/** Whether the time column holds dates, so durations are real hours. */
+	get dated() {
+		return this.tracks[0]?.fixes[0]?.row[this.options.time] instanceof Date;
+	}
+};
+export { GeoTrackChart };

package/dist/charts/geoflows/GreatCircleArcMap.js

@@ -0,0 +1,135 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FlowGeometry } from "./FlowGeometry.js";
+import { GeoFlowProjection } from "./GeoFlowFrame.js";
+import { GeoFlowSample } from "./GeoFlowSample.js";
+import { GeoLinkChart } from "./GeoLinkChart.js";
+import { geoDistance } from "d3";
+// src/charts/geoflows/GreatCircleArcMap.ts
+/** Which line joins two places. */
+var GreatCirclePath = /* @__PURE__ */ function(GreatCirclePath) {
+	GreatCirclePath["Geodesic"] = "geodesic";
+	GreatCirclePath["Lifted"] = "lifted";
+	GreatCirclePath["Rhumb"] = "rhumb";
+	GreatCirclePath["Compare"] = "geodesic-vs-rhumb";
+	return GreatCirclePath;
+}({});
+var PIECES = 10;
+var chunks = (line, parts) => {
+	const size = Math.max(1, Math.ceil((line.length - 1) / parts));
+	return Array.from({ length: Math.ceil((line.length - 1) / size) }, (_, i) => line.slice(i * size, i * size + size + 1));
+};
+/** Show the shortest path over the sphere: geodesics, flight-style lifted arcs, or the rhumb line a compass would keep. */
+var GreatCircleArcMap = class extends GeoLinkChart {
+	static meta = {
+		id: "great-circle-arc-map",
+		name: "Great circle arc map",
+		family: ChartFamily.Geospatial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Joins places by the shortest path over the globe, optionally lifted off the surface or set against the rhumb line.",
+		tags: [
+			"geodesic",
+			"flight path",
+			"rhumb line"
+		],
+		sample: (seed) => GeoFlowSample.flows(seed, 30),
+		variants: {
+			projection: [
+				GeoFlowProjection.Orthographic,
+				GeoFlowProjection.NaturalEarth,
+				GeoFlowProjection.Mercator,
+				GeoFlowProjection.AzimuthalEqualArea,
+				GeoFlowProjection.Stereographic
+			],
+			path: [
+				"geodesic",
+				"lifted",
+				"rhumb",
+				"geodesic-vs-rhumb"
+			],
+			fade: [false, true],
+			distances: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			projection: GeoFlowProjection.Orthographic,
+			path: "geodesic",
+			fade: false,
+			distances: false,
+			limit: 12
+		};
+	}
+	framePad(width, height) {
+		return this.options.path === "lifted" ? Math.min(width, height) * .13 : void 0;
+	}
+	/** Raises the geodesic off the surface. On the globe, parts behind it are hidden as a real arc's would be. */
+	lifted(frame, link) {
+		const steps = 40, rise = .12 + .3 * Math.min(1, geoDistance(link.from, link.to) / Math.PI);
+		const [cx, cy] = frame.projection.translate();
+		const runs = [];
+		let run = [];
+		const close = () => {
+			if (run.length > 1) runs.push(run);
+			run = [];
+		};
+		FlowGeometry.geodesic(link.from, link.to, steps).forEach((place, i) => {
+			const flat = frame.projection(place), h = rise * Math.sin(i / steps * Math.PI);
+			const angle = geoDistance(place, frame.center), scale = 1 + h;
+			if (!flat || frame.azimuthal && !frame.seen(place) && (!frame.globe || scale * Math.sin(angle) < 1)) return close();
+			const point = frame.azimuthal ? [cx + (flat[0] - cx) * scale, cy + (flat[1] - cy) * scale] : [flat[0], flat[1] - h * frame.height * .5];
+			const last = run.at(-1);
+			if (last && Math.hypot(point[0] - last[0], point[1] - last[1]) > frame.width / 4) close();
+			if (point[0] < 0 || point[1] < 0 || point[0] > frame.width || point[1] > frame.height) return close();
+			run.push(point);
+		});
+		close();
+		return runs;
+	}
+	pieces(frame, link, line, alt = false) {
+		const { fade } = this.options;
+		const parts = line ? (fade ? chunks(line, PIECES) : [line]).map((part) => frame.line(part)) : this.lifted(frame, link).flatMap((run) => (fade ? chunks(run, PIECES) : [run]).map((part) => FlowGeometry.polyline(part)));
+		return parts.filter(Boolean).map((d, i) => ({
+			key: `${link.id}/${alt}/${i}`,
+			link,
+			d,
+			alt,
+			strength: fade ? .15 + .85 * (i + 1) / parts.length : .9
+		}));
+	}
+	plotGeo(ctx, frame) {
+		const { path, limit, distances } = this.options;
+		const links = [...this.links].sort((a, b) => b.value - a.value).slice(0, limit);
+		const pieces = links.flatMap((link) => {
+			if (path === "lifted") return this.pieces(frame, link, null);
+			const rhumb = FlowGeometry.rhumb(link.from, link.to);
+			if (path === "rhumb") return this.pieces(frame, link, rhumb);
+			const geodesic = this.pieces(frame, link, FlowGeometry.geodesic(link.from, link.to));
+			return path === "geodesic-vs-rhumb" ? [...this.pieces(frame, link, rhumb, true), ...geodesic] : geodesic;
+		});
+		const lines = ctx.marks("arcs", "path", pieces, (d) => d.key).attr("fill", "none").attr("stroke-linecap", "round").attr("stroke", (d) => d.alt ? ctx.theme.inkMuted : this.tint(ctx, d.link)).attr("stroke-width", (d) => d.alt ? 1.25 : 2).attr("stroke-opacity", (d) => d.strength).attr("stroke-dasharray", (d) => d.alt ? "2 4" : null);
+		ctx.set(lines, { d: (d) => d.d }, { d: (d) => d.d });
+		if (!this.options.fade) ctx.drawOn(lines);
+		ctx.hover(lines, (d) => ({
+			title: `${d.link.source} → ${d.link.target}`,
+			color: this.tint(ctx, d.link),
+			rows: [["Distance", `${Math.round(FlowGeometry.km(d.link.from, d.link.to)).toLocaleString("en")} km`], ["Flow", d.link.value]]
+		}));
+		const names = new Set(links.flatMap((link) => [link.source, link.target]));
+		const stops = this.stops.filter((stop) => names.has(stop.name));
+		this.stopDots(ctx, frame, stops, () => 4);
+		const towns = this.stopLabels(frame, stops, () => 4);
+		const midpoints = !distances ? [] : links.flatMap((link) => {
+			const at = frame.at(FlowGeometry.geodesic(link.from, link.to, 2)[1]);
+			return at ? [{
+				text: `${Math.round(FlowGeometry.km(link.from, link.to)).toLocaleString("en")} km`,
+				x: at[0],
+				y: at[1],
+				gap: 0
+			}] : [];
+		});
+		this.labels(ctx, distances ? [...midpoints.slice(0, 4), ...towns] : towns, "labels", 6);
+	}
+};
+export { GreatCircleArcMap, GreatCirclePath };