@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/geoflows/GeoFlowChart.js

@@ -0,0 +1,316 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { LegendPosition } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GeoViewport } from "../geomaps/GeoViewport.js";
+import { GeoFlowFrame, GeoFlowProjection, isAzimuthal } from "./GeoFlowFrame.js";
+import { geoGraticule10, max } from "d3";
+// src/charts/geoflows/GeoFlowChart.ts
+/** What the map frames: the whole sphere, or just the data. */
+var GeoFlowFit = /* @__PURE__ */ function(GeoFlowFit) {
+	GeoFlowFit["Data"] = "data";
+	GeoFlowFit["World"] = "world";
+	return GeoFlowFit;
+}({});
+var WORLD_FOCUS = 11;
+var CHAR = 6.2;
+var countries;
+var clips = 0;
+var graticule = geoGraticule10();
+/** A number from a data cell, or NaN for blanks: `+null` would silently place a mark at 0. */
+var reading = (cell) => cell === null || cell === void 0 || cell === "" ? NaN : +cell;
+var hasPlace = (place) => Number.isFinite(place[0]) && Number.isFinite(place[1]) && Math.abs(place[1]) <= 90;
+/**
+* Base of every geographic flow chart: fits a projection, paints a recessive basemap and offers
+* label placement and scale keys. Subclasses add `points` (what to centre on) and `plotGeo`.
+*/
+var GeoFlowChart = class extends Chart2D {
+	clipId = `geoflow-clip-${++clips}`;
+	/** Programmatic pan and zoom: `zoomIn`, `zoomOut`, `reset`, `fit`. */
+	viewport = new GeoViewport(this);
+	drawnLayout = "";
+	/** Draws the marks. Charts that arrange their own maps override `compose` instead. */
+	plotGeo(_ctx, _frame) {}
+	defaults() {
+		return {
+			...super.defaults(),
+			projection: GeoFlowProjection.NaturalEarth,
+			fit: "data",
+			key: true,
+			zoom: false,
+			maxZoom: 16
+		};
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 12,
+			bottom: 10,
+			left: 12
+		};
+	}
+	/** Whether colour shows named categories, so the legend earns its row. */
+	categorical() {
+		return false;
+	}
+	get legendPosition() {
+		return this.options.legend ?? (this.categorical() ? LegendPosition.Top : LegendPosition.None);
+	}
+	/** What a data-fitted map must contain. */
+	subject() {
+		const coordinates = this.points();
+		return coordinates.length ? {
+			type: "MultiPoint",
+			coordinates
+		} : null;
+	}
+	/** The widest empty stretch of longitude: `start` is its western edge. */
+	lonGap() {
+		const lons = this.points().map(([lon]) => (lon % 360 + 540) % 360 - 180).sort((a, b) => a - b);
+		if (!lons.length) return null;
+		let gap = lons[0] + 360 - lons.at(-1), start = lons.at(-1);
+		lons.forEach((lon, i) => {
+			if (i && lon - lons[i - 1] > gap) {
+				gap = lon - lons[i - 1];
+				start = lons[i - 1];
+			}
+		});
+		return {
+			gap,
+			start
+		};
+	}
+	/** Puts the empty stretch of longitude at the map edge, so regional data never straddles it. */
+	focus() {
+		if (this.options.centre) return this.options.centre;
+		const open = this.lonGap();
+		if (!open) return [WORLD_FOCUS, 0];
+		const places = this.points();
+		const lat = places.reduce((sum, [, y]) => sum + y, 0) / places.length;
+		return [open.gap < 180 ? WORLD_FOCUS : (open.start + open.gap / 2 + 360) % 360 - 180, lat];
+	}
+	/** Clear space around the map, in pixels. Undefined keeps the frame's default. */
+	framePad(_width, _height) {}
+	frame(width, height) {
+		const { projection, fit } = this.options;
+		const open = this.lonGap();
+		const worldwide = !isAzimuthal(projection) && !!open && open.gap < 180;
+		const whole = fit === "world" || projection === GeoFlowProjection.Orthographic || worldwide;
+		return new GeoFlowFrame(projection, width, height, this.focus(), whole ? null : this.subject(), this.framePad(width, height));
+	}
+	/** Identifies the structure of the marks. When it changes the plot is rebuilt, since each form draws different groups. */
+	layoutKey() {
+		const options = this.options;
+		return Object.keys(this.meta.variants ?? {}).map((axis) => String(options[axis])).join("|");
+	}
+	viewMoved() {}
+	draw(outer) {
+		const layout = this.layoutKey();
+		if (layout !== this.drawnLayout) outer.root.selectAll("*").remove();
+		this.drawnLayout = layout;
+		const { width, height } = outer.plot;
+		const ctx = this.viewport.attach(outer, {
+			enabled: !!this.options.zoom,
+			width,
+			height,
+			pinned: true,
+			smooth: this.animated,
+			limits: {
+				scale: [1, this.options.maxZoom],
+				pan: [[0, 0], [width, height]]
+			}
+		});
+		this.compose(ctx);
+		this.viewport.finish(outer);
+	}
+	compose(ctx) {
+		const frame = this.frame(ctx.plot.width, ctx.plot.height);
+		this.drawBasemap(ctx, frame);
+		this.plotGeo(ctx, frame);
+	}
+	get land() {
+		return this.options.basemap ?? (countries ??= SampleData.world(1));
+	}
+	drawBasemap(ctx, frame, graticules = true) {
+		const { theme } = ctx;
+		ctx.marks("sphere", "path", [frame.path({ type: "Sphere" }) ?? ""]).attr("d", (d) => d).attr("fill", theme.surface).attr("stroke", frame.whole ? theme.axis : "none").attr("pointer-events", "none");
+		ctx.marks("graticule", "path", graticules ? [frame.path(graticule) ?? ""] : []).attr("d", (d) => d).attr("fill", "none").attr("stroke", theme.grid).attr("stroke-width", .5).attr("pointer-events", "none");
+		ctx.marks("land", "path", [frame.path(this.land) ?? ""]).attr("d", (d) => d).attr("fill", theme.grid).attr("stroke", theme.surface).attr("stroke-width", .5).attr("pointer-events", "none");
+	}
+	/** A group whose content is cut to `shape`, an SVG path; null leaves it uncut. */
+	clipped(ctx, name, shape) {
+		ctx.marks(`${name}-clip`, "clipPath", shape === null ? [] : [shape]).attr("id", `${this.clipId}-${name}`).selectAll("path").data((d) => [d]).join("path").attr("d", (d) => d);
+		return ctx.group(name).attr("clip-path", shape === null ? null : `url(#${this.clipId}-${name})`);
+	}
+	/** Coastlines redrawn over filled marks, so geography stays readable through them. */
+	drawCoast(ctx, frame, skip = false) {
+		ctx.marks("coast", "path", skip ? [] : [frame.path(this.land) ?? ""]).attr("d", (d) => d).attr("fill", "none").attr("stroke", ctx.theme.surface).attr("stroke-width", .75).attr("stroke-opacity", .75).attr("pointer-events", "none");
+	}
+	/** Greedy labels, most important first: tries right, left, above, below, and drops what cannot fit. */
+	labels(ctx, items, name = "labels", limit = 7) {
+		const { width, height } = ctx.plot;
+		const placed = [];
+		const free = (box) => box.x >= 0 && box.y >= 0 && box.x + box.w <= width && box.y + box.h <= height && placed.every(({ box: b }) => box.x + box.w < b.x || b.x + b.w < box.x || box.y + box.h < b.y || b.y + b.h < box.y);
+		for (const item of items) {
+			if (placed.length >= limit) break;
+			const w = item.text.length * CHAR, gap = (item.gap ?? 4) + 3;
+			const fit = [
+				[
+					"start",
+					item.x + gap,
+					item.y + 4,
+					{
+						x: item.x + gap,
+						y: item.y - 7,
+						w,
+						h: 13
+					}
+				],
+				[
+					"end",
+					item.x - gap,
+					item.y + 4,
+					{
+						x: item.x - gap - w,
+						y: item.y - 7,
+						w,
+						h: 13
+					}
+				],
+				[
+					"middle",
+					item.x,
+					item.y - gap - 3,
+					{
+						x: item.x - w / 2,
+						y: item.y - gap - 13,
+						w,
+						h: 13
+					}
+				],
+				[
+					"middle",
+					item.x,
+					item.y + gap + 10,
+					{
+						x: item.x - w / 2,
+						y: item.y + gap,
+						w,
+						h: 13
+					}
+				]
+			].find(([, , , box]) => free(box));
+			if (fit) placed.push({
+				...item,
+				anchor: fit[0],
+				px: fit[1],
+				py: fit[2],
+				box: fit[3]
+			});
+		}
+		ctx.text(ctx.marks(name, "text", placed, (d, i) => `${d.text}/${i}`).attr("x", (d) => d.px).attr("y", (d) => d.py).attr("text-anchor", (d) => d.anchor).text((d) => d.text), 11, "ink").attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").attr("pointer-events", "none");
+	}
+	/** Moves the scale key to the top of the plot, for charts whose marks fill the bottom corner. */
+	get keyOnTop() {
+		return false;
+	}
+	keyed(ctx, width, height) {
+		const roomy = this.options.key !== false && ctx.plot.width >= 280 && ctx.plot.height >= 150;
+		const nested = ctx.nest(`translate(4,${this.keyOnTop ? 4 : Math.max(0, ctx.plot.height - height - 2)})`, "key");
+		if (!roomy) {
+			nested.root.selectAll("*").remove();
+			return null;
+		}
+		nested.marks("back", "rect", [width]).attr("x", -3).attr("y", -3).attr("width", (d) => d + 6).attr("height", height + 6).attr("rx", 3).attr("fill", ctx.theme.surface).attr("fill-opacity", .82);
+		return nested;
+	}
+	keyWords(key, words) {
+		key.text(key.marks("words", "text", words).attr("x", (d) => d.x).attr("y", (d) => d.y).attr("text-anchor", (d) => d.a ?? "start").text((d) => d.t), 10);
+	}
+	/** Stepped colour ramp for a magnitude. */
+	keyRamp(ctx, title, low, high, color) {
+		const steps = [
+			0,
+			.25,
+			.5,
+			.75,
+			1
+		], cell = 16;
+		const key = this.keyed(ctx, steps.length * cell, 34);
+		if (!key) return;
+		key.marks("ramp", "rect", steps).attr("x", (_, i) => i * cell).attr("y", 14).attr("width", 15).attr("height", 7).attr("fill", (t) => color(t));
+		this.keyWords(key, [
+			{
+				t: title,
+				x: 0,
+				y: 9
+			},
+			{
+				t: low,
+				x: 0,
+				y: 33
+			},
+			{
+				t: high,
+				x: steps.length * cell,
+				y: 33,
+				a: "end"
+			}
+		]);
+	}
+	/** Line widths and the values they stand for. */
+	keyWidths(ctx, title, width, top) {
+		if (!(top > 0)) return;
+		const values = [top, top / 2].map((value) => +value.toPrecision(2));
+		const sizes = values.map((value) => width(value));
+		const rows = sizes.map((size, i) => 14 + sizes.slice(0, i).reduce((sum, s) => sum + Math.max(s, 12) + 2, 0) + Math.max(size, 12) / 2);
+		const key = this.keyed(ctx, 68, rows[1] + Math.max(sizes[1], 12) / 2);
+		if (!key) return;
+		key.marks("widths", "rect", values).attr("x", 0).attr("y", (_, i) => rows[i] - sizes[i] / 2).attr("width", 26).attr("height", (_, i) => sizes[i]).attr("rx", 1).attr("fill", ctx.theme.inkMuted);
+		this.keyWords(key, [{
+			t: title,
+			x: 0,
+			y: 8
+		}, ...values.map((v, i) => ({
+			t: Scales.format(v, top),
+			x: 32,
+			y: rows[i] + 3.5
+		}))]);
+	}
+	/** Nested circles and the values they stand for. */
+	keyCircles(ctx, title, radius, top) {
+		const reach = radius(top), base = 14 + reach * 2;
+		const key = this.keyed(ctx, reach * 2 + 34, base);
+		if (!key || !(top > 0) || reach < 3) return;
+		const values = [top, top / 4].map((value) => +value.toPrecision(2));
+		key.marks("circles", "circle", values).attr("cx", reach).attr("cy", (v) => base - radius(v)).attr("r", (v) => radius(v)).attr("fill", "none").attr("stroke", ctx.theme.inkMuted);
+		this.keyWords(key, [{
+			t: title,
+			x: 0,
+			y: 8
+		}, ...values.map((v, i) => ({
+			t: Scales.format(v, top),
+			x: reach * 2 + 5,
+			y: Math.max(base - radius(v) * 2 + 8, 22 + i * 11)
+		}))]);
+	}
+	/** Visible runs of a place list in pixels, broken at the horizon and at the map's seam. */
+	runs(frame, places) {
+		const runs = [];
+		let run = [];
+		for (const place of places) {
+			const point = frame.at(place), last = run.at(-1);
+			if (!point || last && Math.hypot(point[0] - last[0], point[1] - last[1]) > frame.width / 3) {
+				if (run.length > 1) runs.push(run);
+				run = point ? [point] : [];
+			} else run.push(point);
+		}
+		if (run.length > 1) runs.push(run);
+		return runs;
+	}
+	/** Largest absolute value of a column, safe on empty input. */
+	static peakOf(items, value) {
+		return max(items, (item) => Math.abs(value(item))) || 1;
+	}
+};
+export { GeoFlowChart, GeoFlowFit, hasPlace, reading };

package/dist/charts/geoflows/GeoFlowFrame.js

@@ -0,0 +1,97 @@
+import { geoAzimuthalEqualArea, geoAzimuthalEquidistant, geoCentroid, geoConicEqualArea, geoDistance, geoEqualEarth, geoEquirectangular, geoMercator, geoNaturalEarth1, geoOrthographic, geoPath, geoStereographic } from "d3";
+// src/charts/geoflows/GeoFlowFrame.ts
+/** Map projection of a flow map. Global forms come first; azimuthal forms centre on the data; conic suits one region. */
+var GeoFlowProjection = /* @__PURE__ */ function(GeoFlowProjection) {
+	GeoFlowProjection["NaturalEarth"] = "natural-earth";
+	GeoFlowProjection["EqualEarth"] = "equal-earth";
+	GeoFlowProjection["Mercator"] = "mercator";
+	GeoFlowProjection["Equirectangular"] = "equirectangular";
+	GeoFlowProjection["Orthographic"] = "orthographic";
+	GeoFlowProjection["AzimuthalEqualArea"] = "azimuthal-equal-area";
+	GeoFlowProjection["AzimuthalEquidistant"] = "azimuthal-equidistant";
+	GeoFlowProjection["Stereographic"] = "stereographic";
+	GeoFlowProjection["ConicEqualArea"] = "conic-equal-area";
+	return GeoFlowProjection;
+}({});
+var RADIANS = Math.PI / 180;
+var AZIMUTHAL = /* @__PURE__ */ new Set([
+	"orthographic",
+	"azimuthal-equal-area",
+	"azimuthal-equidistant",
+	"stereographic"
+]);
+var FACTORIES = {
+	["natural-earth"]: geoNaturalEarth1,
+	["equal-earth"]: geoEqualEarth,
+	["mercator"]: geoMercator,
+	["equirectangular"]: geoEquirectangular,
+	["orthographic"]: geoOrthographic,
+	["azimuthal-equal-area"]: geoAzimuthalEqualArea,
+	["azimuthal-equidistant"]: geoAzimuthalEquidistant,
+	["stereographic"]: geoStereographic,
+	["conic-equal-area"]: geoConicEqualArea
+};
+var isAzimuthal = (kind) => AZIMUTHAL.has(kind);
+/** A projection fitted to a pixel box, plus the checks every mark needs before it is placed. */
+var GeoFlowFrame = class GeoFlowFrame {
+	width;
+	height;
+	projection;
+	path;
+	center;
+	whole;
+	azimuthal;
+	globe;
+	horizon;
+	constructor(kind, width, height, focus, subject, pad = subject ? 16 : 2) {
+		this.width = width;
+		this.height = height;
+		const [lon, lat] = focus;
+		const projection = FACTORIES[kind]().precision(.4);
+		if (AZIMUTHAL.has(kind)) projection.rotate([-lon, -lat]);
+		else projection.rotate([-lon, 0]);
+		if (kind === "conic-equal-area") projection.parallels([Math.max(-75, lat - 12), Math.min(75, lat + 12)]);
+		if (kind === "stereographic") projection.clipAngle(115);
+		const box = [[pad, pad], [width - pad, height - pad]];
+		const target = subject ?? (kind === "mercator" ? {
+			type: "MultiPoint",
+			coordinates: [[lon - 179.9, -58], [lon + 179.9, 80]]
+		} : { type: "Sphere" });
+		projection.fitExtent(box, target);
+		GeoFlowFrame.limit(projection, target, width, height);
+		projection.clipExtent([[0, 0], [width, height]]);
+		this.projection = projection;
+		this.path = geoPath(projection).digits(1);
+		this.center = AZIMUTHAL.has(kind) ? [lon, lat] : [lon, 0];
+		this.whole = !subject;
+		this.azimuthal = AZIMUTHAL.has(kind);
+		this.globe = kind === "orthographic";
+		this.horizon = (projection.clipAngle?.() ?? 0) * RADIANS;
+	}
+	/** A lone point or a tiny cluster fits at infinite zoom: cap it and centre the subject instead. */
+	static limit(projection, target, width, height) {
+		const most = Math.min(width, height) * 3;
+		if (projection.scale() <= most) return;
+		projection.scale(most).translate([width / 2, height / 2]);
+		const at = projection(geoCentroid(target));
+		if (at) projection.translate([width - at[0], height - at[1]]);
+	}
+	/** Pixel position, or null when the place is behind the horizon or off the plot. */
+	at(place) {
+		if (!this.seen(place)) return null;
+		const point = this.projection(place);
+		if (!point || !Number.isFinite(point[0]) || !Number.isFinite(point[1])) return null;
+		return point[0] < 0 || point[1] < 0 || point[0] > this.width || point[1] > this.height ? null : point;
+	}
+	seen(place) {
+		return !this.horizon || geoDistance(place, this.center) < this.horizon - .001;
+	}
+	/** Line through `places`, following the sphere, clipped to the horizon and the plot. */
+	line(places) {
+		return this.path({
+			type: "LineString",
+			coordinates: places
+		}) ?? "";
+	}
+};
+export { GeoFlowFrame, GeoFlowProjection, isAzimuthal };

package/dist/charts/geoflows/GeoFlowSample.js

@@ -0,0 +1,252 @@
+import { SampleData } from "../../data/SampleData.js";
+import { geoCentroid, geoDistance } from "d3";
+// src/charts/geoflows/GeoFlowSample.ts
+/** Broad region of a place, from its coordinates; demo data only. */
+var regionOf = (lon, lat) => {
+	if (lon < -30) return "Americas";
+	if (lon < 60) return lat > 35 ? "Europe" : "Africa";
+	return lat < -10 ? "Oceania" : "Asia";
+};
+/** Reshapes `SampleData` into origin-destination rows, tracks and point sets. */
+var GeoFlowSample = class {
+	/** `{ source, target, sourceLon, sourceLat, targetLon, targetLat, value, series }`, the strongest city pairs. */
+	static flows(seed, count = 36, only) {
+		const cities = SampleData.cities(seed).filter((city) => !only || only.includes(String(city.name)));
+		const noise = SampleData.matrix(seed, cities.length, cities.length).values;
+		return cities.flatMap((a, i) => cities.flatMap((b, j) => {
+			if (i === j) return [];
+			const value = Math.round(+a.value * (noise[i][j] + 1.4) * .6 + 4);
+			return [{
+				source: a.name,
+				target: b.name,
+				sourceLon: a.lon,
+				sourceLat: a.lat,
+				targetLon: b.lon,
+				targetLat: b.lat,
+				value,
+				series: regionOf(+a.lon, +a.lat)
+			}];
+		})).sort((x, y) => +y.value - +x.value).slice(0, count);
+	}
+	/** Nine cities far enough apart to read individually. */
+	static spaced = [
+		"New York",
+		"São Paulo",
+		"London",
+		"Lagos",
+		"Moscow",
+		"Mumbai",
+		"Beijing",
+		"Tokyo",
+		"Sydney"
+	];
+	/** Every city linked to one hub, in both directions. */
+	static star(seed, hub = "London") {
+		const cities = SampleData.cities(seed);
+		const centre = cities.find((city) => city.name === hub) ?? cities[0];
+		return cities.filter((city) => city !== centre).flatMap((city, i) => {
+			const series = regionOf(+city.lon, +city.lat);
+			return [{
+				source: centre.name,
+				target: city.name,
+				sourceLon: centre.lon,
+				sourceLat: centre.lat,
+				targetLon: city.lon,
+				targetLat: city.lat,
+				value: city.value,
+				series
+			}, {
+				source: city.name,
+				target: centre.name,
+				sourceLon: city.lon,
+				sourceLat: city.lat,
+				targetLon: centre.lon,
+				targetLat: centre.lat,
+				value: 12 + +city.value * (i + 3) % 70,
+				series
+			}];
+		});
+	}
+	/** `{ route, stop, order, lon, lat }`: four liner services through the sample cities. */
+	static routes(seed) {
+		const cities = new Map(SampleData.cities(seed).map((city) => [city.name, city]));
+		return [
+			["Atlantic", [
+				"Toronto",
+				"New York",
+				"London",
+				"Paris",
+				"Lagos",
+				"Cape Town"
+			]],
+			["Silk Road", [
+				"Paris",
+				"Istanbul",
+				"Moscow",
+				"Mumbai",
+				"Beijing",
+				"Seoul",
+				"Tokyo"
+			]],
+			["Southern", [
+				"Lima",
+				"São Paulo",
+				"Cape Town",
+				"Nairobi",
+				"Jakarta",
+				"Sydney"
+			]],
+			["Pacific", [
+				"Sydney",
+				"Singapore",
+				"Tokyo",
+				"Mexico City",
+				"New York"
+			]]
+		].flatMap(([route, stops]) => stops.map((stop, order) => {
+			const city = cities.get(stop);
+			return {
+				route,
+				stop,
+				order,
+				lon: city.lon,
+				lat: city.lat,
+				value: city.value
+			};
+		}));
+	}
+	/** `{ track, time, lon, lat, value }`: tagged birds flying from Europe to southern Africa. */
+	static tracks(seed, count = 5, fixes = 48) {
+		const walks = SampleData.timeSeries(seed, fixes, count);
+		return [...new Set(walks.map((row) => String(row.series)))].flatMap((track, i) => {
+			const rows = walks.filter((row) => row.series === track);
+			const first = +rows[0].value;
+			return rows.map((row, step) => {
+				const t = step / (fixes - 1), drift = (+row.value - first) * .32, bow = Math.sin(t * Math.PI);
+				return {
+					track,
+					time: row.date,
+					value: row.value,
+					lon: +(6 + i * 5 + (14 + i * 2) * t + bow * (11 - i * 5) + drift).toFixed(2),
+					lat: +(54 - i - (72 - i * 3) * t + bow * drift * .3).toFixed(2)
+				};
+			});
+		});
+	}
+	/** `{ track, time, lon, lat, value }`: Atlantic storms that curve north; `value` is sustained wind in knots. */
+	static storms(seed, count = 4, fixes = 26) {
+		const walks = SampleData.timeSeries(seed, fixes, count);
+		return [
+			"Ana",
+			"Bret",
+			"Cindy",
+			"Don",
+			"Emily",
+			"Franklin",
+			"Gert",
+			"Harvey"
+		].slice(0, count).flatMap((track, i) => {
+			const rows = walks.filter((row) => row.series === [...new Set(walks.map((walk) => walk.series))][i]);
+			const first = +rows[0].value;
+			return rows.map((row, step) => {
+				const t = step / (fixes - 1), turn = t ** 4, noise = (+row.value - first) * .18;
+				return {
+					track,
+					time: row.date,
+					lon: +(-24 - i * 6 - 110 * t + turn * 130 + noise).toFixed(2),
+					lat: +(11 + i * 1.5 + 14 * t + t * t * (24 - i * 2) + noise * .4).toFixed(2),
+					value: Math.round(Math.max(25, 30 + 125 * Math.sin(Math.min(1, t * 1.15) * Math.PI) ** 1.4 * (1 - i * .12) + noise * 2))
+				};
+			});
+		});
+	}
+	/** `{ phase, order, name, lon, lat, value, temperature }`: an army's advance and retreat across Europe. */
+	static campaign(seed) {
+		const cities = SampleData.cities(seed);
+		const start = cities.find((city) => city.name === "Paris"), end = cities.find((city) => city.name === "Moscow");
+		const noise = SampleData.timeSeries(seed, 9, 1).map((row) => +row.value);
+		const stage = (phase, from, to, army, loss, temperature) => Array.from({ length: 9 }, (_, i) => {
+			const t = i / 8, wave = (noise[i] - noise[0]) * .12;
+			return {
+				phase,
+				order: i,
+				name: `${phase} ${i + 1}`,
+				value: Math.round(army * (1 - loss) ** i),
+				lon: +(+from.lon + (+to.lon - +from.lon) * t).toFixed(2),
+				lat: +(+from.lat + (+to.lat - +from.lat) * t + Math.sin(t * Math.PI) * (phase === "Advance" ? 1.6 : -.6) + wave * .2).toFixed(2),
+				temperature: Math.round(temperature(i))
+			};
+		});
+		return [...stage("Advance", start, end, 42e4, .17, (i) => 24 - i), ...stage("Retreat", end, start, 96e3, .32, (i) => 8 - i * 4 + noise[i] * .01)];
+	}
+	/** `{ lon, lat, u, v }`: a stream function on a regular grid, so the field is smooth and rotational. */
+	static wind(seed, step = 5) {
+		const { z } = SampleData.surface(seed, 37);
+		const stream = (lon, lat) => {
+			const fx = (lon + 180) / 360 * 36, fy = (lat + 90) / 180 * 36;
+			return z[Math.min(36, Math.round(fy))][Math.min(36, Math.round(fx))] * 9 + 6 * Math.sin(lon * Math.PI / 60) * Math.cos(lat * Math.PI / 50) + 8 * Math.cos(lat * Math.PI / 30);
+		};
+		const rows = [];
+		for (let lat = -80; lat <= 80; lat += step) for (let lon = -180; lon < 180; lon += step) {
+			const u = (stream(lon, lat - step) - stream(lon, lat + step)) * 1.6, v = (stream(lon + step, lat) - stream(lon - step, lat)) * 1.6;
+			rows.push({
+				lon,
+				lat,
+				u: +u.toFixed(2),
+				v: +v.toFixed(2)
+			});
+		}
+		return rows;
+	}
+	/** `{ period, name, lon, lat, value }`: the cities repeated across six periods. */
+	static panels(seed, periods = 6) {
+		const cities = SampleData.cities(seed);
+		const { values } = SampleData.matrix(seed, cities.length, periods);
+		return Array.from({ length: periods }, (_, p) => cities.map((city, i) => ({
+			period: String(2021 + p),
+			name: city.name,
+			lon: city.lon,
+			lat: city.lat,
+			value: Math.round(+city.value * (1.1 + values[i][p] * (.2 + p * .14)))
+		}))).flat();
+	}
+	/** The country centroids with `value` as hours of travel from one city. */
+	static travel(seed, from = "London") {
+		const origin = SampleData.cities(seed).find((city) => city.name === from);
+		const home = [+origin.lon, +origin.lat];
+		return [{
+			name: from,
+			lon: home[0],
+			lat: home[1],
+			value: 0,
+			series: regionOf(...home)
+		}, ...this.places(seed).map((place) => ({
+			...place,
+			value: +(geoDistance(home, [+place.lon, +place.lat]) * 7.6 + 1.5 + +place.value / 18).toFixed(1)
+		}))];
+	}
+	/** The cities with three measures, for rings of metrics. */
+	static metrics(seed) {
+		const { values } = SampleData.matrix(seed, 20, 3);
+		return SampleData.cities(seed).map((city, i) => ({
+			...city,
+			series: regionOf(+city.lon, +city.lat),
+			growth: Math.round(40 + values[i][0] * 50),
+			density: Math.round(50 + values[i][1] * 45)
+		}));
+	}
+	/** `{ name, lon, lat, value, series }`: one point per country, at its centroid. */
+	static places(seed) {
+		return SampleData.world(seed).features.map((country) => {
+			const [lon, lat] = geoCentroid(country);
+			return {
+				name: String(country.properties?.name ?? ""),
+				lon: +lon.toFixed(2),
+				lat: +lat.toFixed(2),
+				value: country.properties?.value,
+				series: regionOf(lon, lat)
+			};
+		});
+	}
+};
+export { GeoFlowSample, regionOf };