@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/matrix/MatrixSurface.js

@@ -0,0 +1,43 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { LegendPosition } from "../../core/enums.js";
+import { rgb } from "d3";
+// src/charts/matrix/MatrixSurface.ts
+/** Estimated width of one character at 11px. */
+var CHAR = 6.2;
+/** Truncates to what fits in `width` px of 11px text. */
+function fitText(text, width, char = CHAR) {
+	const room = Math.floor(width / char);
+	return text.length <= room ? text : room < 2 ? "" : `${text.slice(0, room - 1)}…`;
+}
+/** Canvas shared by every chart in this module: a clean slate on shape changes, and legible ink on data-coloured fills. */
+var MatrixSurface = class extends Chart2D {
+	shape = "";
+	get legendPosition() {
+		return this.options.legend ?? LegendPosition.None;
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 16,
+			bottom: 10,
+			left: 16
+		};
+	}
+	draw(ctx) {
+		const { data: _, width: __, height: ___, ...rest } = this.options;
+		const shape = JSON.stringify(rest);
+		if (shape !== this.shape || this.blank) ctx.root.selectAll("*").remove();
+		this.shape = shape;
+		if (!this.blank) this.compose(ctx);
+	}
+	/** The theme ink or surface that contrasts best with `fill`, which may be any CSS colour. */
+	inkOn(ctx, fill) {
+		const luma = (value) => {
+			const { r, g, b } = rgb(value);
+			return .299 * r + .587 * g + .114 * b;
+		};
+		const base = luma(fill);
+		return Math.abs(base - luma(ctx.theme.ink)) > Math.abs(base - luma(ctx.theme.surface)) ? ctx.theme.ink : ctx.theme.surface;
+	}
+};
+export { CHAR, MatrixSurface, fitText };

package/dist/charts/matrix/MatrixTowers3D.js

@@ -0,0 +1,152 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixOrder } from "./matrixEnums.js";
+import { MatrixModel } from "./MatrixModel.js";
+import { MatrixSeriation } from "./MatrixSeriation.js";
+import { scaleBand, scaleLinear } from "d3";
+import { BoxGeometry, ConeGeometry, CylinderGeometry, InstancedMesh, Mesh, MeshStandardMaterial, Object3D, PlaneGeometry, SphereGeometry } from "three";
+// src/charts/matrix/MatrixTowers3D.ts
+var TowerShape = /* @__PURE__ */ function(TowerShape) {
+	TowerShape["Box"] = "box";
+	TowerShape["Cylinder"] = "cylinder";
+	TowerShape["Hexagon"] = "hex-prism";
+	TowerShape["Cone"] = "cone";
+	TowerShape["Sphere"] = "sphere";
+	return TowerShape;
+}({});
+var TowerHeight = /* @__PURE__ */ function(TowerHeight) {
+	TowerHeight["Linear"] = "linear-height";
+	TowerHeight["Root"] = "root-height";
+	return TowerHeight;
+}({});
+var FLOOR = -.7;
+/** A heatmap raised into relief: height doubles the colour channel, for presenting the broad shape of a matrix. */
+var MatrixTowers3D = class extends Chart3D {
+	static meta = {
+		id: "matrix-towers-3d",
+		name: "3D matrix towers",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Three,
+		shape: DataShape.Matrix,
+		description: "Raises each matrix cell into a tower, with height and colour both showing the value, for an overview of its relief.",
+		tags: [
+			"3d heatmap",
+			"cityscape",
+			"relief"
+		],
+		sample: (seed) => SampleData.matrix(seed, 9, 11),
+		variants: {
+			shape: [
+				"box",
+				"cylinder",
+				"hex-prism",
+				"cone",
+				"sphere"
+			],
+			order: [
+				MatrixOrder.Input,
+				MatrixOrder.Total,
+				MatrixOrder.Cluster
+			],
+			heightScale: ["linear-height", "root-height"],
+			padding: [.18, .4]
+		}
+	};
+	defaults() {
+		return {
+			x: "series",
+			y: "category",
+			value: "value",
+			shape: "box",
+			order: MatrixOrder.Input,
+			heightScale: "linear-height",
+			padding: .18
+		};
+	}
+	arranged() {
+		const { data, order } = this.options;
+		const model = MatrixModel.from(data, this.options);
+		if (order === MatrixOrder.Total) {
+			const rows = model.rowTotals, columns = model.columnTotals;
+			return model.reorder(model.rows.map((_, i) => i).sort((a, b) => rows[b] - rows[a] || a - b), model.columns.map((_, i) => i).sort((a, b) => columns[b] - columns[a] || a - b));
+		}
+		return order === MatrixOrder.Cluster ? model.reorder(MatrixSeriation.clustered(model.rowVectors), MatrixSeriation.clustered(model.columnVectors)) : model;
+	}
+	geometry(width, depth) {
+		const radius = Math.min(width, depth) / 2;
+		switch (this.options.shape) {
+			case "cylinder": return new CylinderGeometry(radius, radius, 1, 20);
+			case "hex-prism": return new CylinderGeometry(radius, radius, 1, 6);
+			case "cone": return new ConeGeometry(radius, 1, 20);
+			case "sphere": return new SphereGeometry(radius, 18, 14);
+			default: return new BoxGeometry(width, 1, depth);
+		}
+	}
+	build(ctx) {
+		const model = this.arranged();
+		const floor = new Mesh(new PlaneGeometry(2.3, 2.3), new MeshStandardMaterial({ color: ctx.theme.grid }));
+		floor.rotation.x = -Math.PI / 2;
+		floor.position.y = FLOOR;
+		floor.receiveShadow = true;
+		ctx.root.add(floor);
+		const cells = model.cells.filter((cell) => cell.value !== null);
+		if (!cells.length) return;
+		const { padding, heightScale, shape } = this.options;
+		const bandX = scaleBand(model.columns.map((_, c) => c), [-1, 1]).padding(padding), bandZ = scaleBand(model.rows.map((_, r) => r), [-1, 1]).padding(padding);
+		const reach = model.reach, signed = model.domain[0] < 0;
+		const lift = scaleLinear([0, reach], [0, signed ? .68 : 1.36]);
+		const base = signed ? 0 : FLOOR;
+		const towers = new InstancedMesh(this.geometry(bandX.bandwidth(), bandZ.bandwidth()), new MeshStandardMaterial({ roughness: .5 }), cells.length);
+		towers.castShadow = true;
+		if (signed) {
+			const zero = new Mesh(new PlaneGeometry(2.1, 2.1), new MeshStandardMaterial({
+				color: ctx.theme.axis,
+				transparent: true,
+				opacity: .22
+			}));
+			zero.rotation.x = -Math.PI / 2;
+			ctx.root.add(zero);
+		}
+		const [low, high] = model.domain, dummy = new Object3D();
+		const size = (value) => {
+			const share = Math.abs(value) / reach;
+			return Math.max(.002, lift(heightScale === "root-height" ? Math.sqrt(share) * reach : share * reach));
+		};
+		const place = (progress) => {
+			cells.forEach((cell, i) => {
+				const h = size(cell.value) * progress, sign = Math.sign(cell.value) || 1;
+				dummy.position.set(bandX(cell.c) + bandX.bandwidth() / 2, shape === "sphere" ? base + sign * size(cell.value) : base + sign * h / 2, bandZ(cell.r) + bandZ.bandwidth() / 2);
+				if (shape === "sphere") dummy.scale.setScalar(Math.max(.05, Math.sqrt(Math.abs(cell.value) / reach)) * progress);
+				else dummy.scale.set(1, h, 1);
+				dummy.rotation.x = shape === "cone" && sign < 0 ? Math.PI : 0;
+				dummy.updateMatrix();
+				towers.setMatrixAt(i, dummy.matrix);
+			});
+			towers.instanceMatrix.needsUpdate = true;
+		};
+		cells.forEach((cell, i) => towers.setColorAt(i, ctx.color(signed ? ctx.palette.diverging(cell.value / reach) : ctx.palette.sequential(high > low ? (cell.value - low) / (high - low) : .6))));
+		ctx.reveal(place);
+		ctx.root.add(towers);
+		ctx.pick(towers, (i) => ({
+			title: `${cells[i].row} · ${cells[i].column}`,
+			rows: [["Value", +cells[i].value.toFixed(3)]]
+		}));
+		const every = (count) => Math.ceil(count / 6);
+		model.columns.forEach((name, c) => {
+			if (c % every(model.columns.length) === 0) ctx.label(name, [
+				bandX(c) + bandX.bandwidth() / 2,
+				-.75,
+				1.2
+			], "secondary", 10);
+		});
+		model.rows.forEach((name, r) => {
+			if (r % every(model.rows.length) === 0) ctx.label(name, [
+				-1.24,
+				-.75,
+				bandZ(r) + bandZ.bandwidth() / 2
+			], "secondary", 10);
+		});
+	}
+};
+export { MatrixTowers3D, TowerHeight, TowerShape };

package/dist/charts/matrix/PunchCard.js

@@ -0,0 +1,153 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixChart } from "./MatrixChart.js";
+import { MatrixGlyph, MatrixMarginal } from "./matrixEnums.js";
+import { pointRadial, sum } from "d3";
+// src/charts/matrix/PunchCard.ts
+var PunchCardLayout = /* @__PURE__ */ function(PunchCardLayout) {
+	PunchCardLayout["Grid"] = "grid";
+	PunchCardLayout["Polar"] = "polar";
+	return PunchCardLayout;
+}({});
+var PunchCardRows = /* @__PURE__ */ function(PunchCardRows) {
+	PunchCardRows["Input"] = "input-rows";
+	PunchCardRows["Busiest"] = "busiest-first";
+	return PunchCardRows;
+}({});
+var DAYS = [
+	"Mon",
+	"Tue",
+	"Wed",
+	"Thu",
+	"Fri",
+	"Sat",
+	"Sun"
+];
+var pad = (hour) => `${hour}`.padStart(2, "0");
+/** Activity by weekday and hour, as GitHub's punch card: one sized mark per slot on a recurring cycle. */
+var PunchCard = class extends MatrixChart {
+	static meta = {
+		id: "punch-card",
+		name: "Punch card",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Matrix,
+		description: "Shows how activity falls across a repeating cycle, such as weekday by hour, using a sized mark per slot.",
+		tags: [
+			"weekly",
+			"hour of day",
+			"activity"
+		],
+		sample: (seed) => {
+			const { values } = SampleData.matrix(seed, 7, 24);
+			return {
+				rows: DAYS,
+				columns: values[0].map((_, hour) => pad(hour)),
+				values: values.map((row, r) => row.map((value, hour) => Math.round((Math.abs(value) + .2) * 40 * (hour > 7 && hour < 19 ? 1.6 : .5) * (r > 4 ? .45 : 1))))
+			};
+		},
+		variants: {
+			layout: ["grid", "polar"],
+			symbol: [
+				MatrixGlyph.Circle,
+				MatrixGlyph.Square,
+				MatrixGlyph.Column
+			],
+			rowOrder: ["input-rows", "busiest-first"],
+			guides: [true, false],
+			marginals: [
+				MatrixMarginal.None,
+				MatrixMarginal.Rows,
+				MatrixMarginal.Columns,
+				MatrixMarginal.Both
+			]
+		},
+		valid: (v) => !(v.layout === "polar" && v.marginals !== MatrixMarginal.None)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			layout: "grid",
+			symbol: MatrixGlyph.Circle,
+			rowOrder: "input-rows",
+			guides: true,
+			marginals: MatrixMarginal.None
+		};
+	}
+	arranged(source) {
+		if (this.options.rowOrder === "input-rows") return source;
+		const totals = source.values.map((row) => sum(row, (value) => value ?? 0));
+		return source.reorder(source.rows.map((_, r) => r).sort((a, b) => totals[b] - totals[a] || a - b), source.columns.map((_, c) => c));
+	}
+	drawMatrix(ctx, source) {
+		const model = this.arranged(source);
+		if (this.options.layout === "polar") this.polar(ctx, model);
+		else this.grid(ctx, model);
+	}
+	describe(model, ctx, cell) {
+		return {
+			title: `${cell.row} · ${cell.column}`,
+			color: ctx.palette.sequential(.7),
+			rows: [["Activity", Scales.format(cell.value ?? 0, model.reach)]]
+		};
+	}
+	grid(ctx, model) {
+		const { symbol, marginals, guides } = this.options;
+		const onRight = marginals === MatrixMarginal.Rows || marginals === MatrixMarginal.Both;
+		const onTop = marginals === MatrixMarginal.Columns || marginals === MatrixMarginal.Both;
+		const frame = this.frame(ctx, model, {
+			right: onRight ? 44 : 0,
+			top: onTop ? 44 : 0,
+			columnLabels: onTop ? "bottom" : "top"
+		});
+		const reach = model.reach, fill = ctx.palette.sequential(.68);
+		this.axisLabels(ctx, model, frame);
+		this.marginals(ctx, model, frame, marginals);
+		ctx.marks("guides", "line", guides ? model.rows.map((_, r) => r) : [], (r) => r).attr("stroke", ctx.theme.grid).attr("x1", frame.x).attr("x2", frame.x + frame.width).attr("y1", frame.cy).attr("y2", frame.cy);
+		this.glyphs(ctx, "cells", model.cells.filter((cell) => cell.value), frame, {
+			glyph: symbol,
+			gap: 1,
+			size: (cell) => Math.abs(cell.value) / reach,
+			fill: () => fill,
+			tip: (cell) => this.describe(model, ctx, cell)
+		});
+	}
+	polar(ctx, model) {
+		const { symbol, guides } = this.options;
+		const size = Math.min(ctx.plot.width, ctx.plot.height), cx = ctx.plot.width / 2, cy = size / 2;
+		const outer = size / 2 - 14, inner = outer * .26, ring = (outer - inner) / model.rows.length;
+		const slots = model.columns.length, turn = (c) => c / slots * Math.PI * 2;
+		const radius = (r) => inner + (r + .5) * ring;
+		const span = Math.min(ring - 1, Math.PI * 2 * radius(0) / slots - 1);
+		const reach = model.reach, fill = ctx.palette.sequential(.68);
+		ctx.marks("rings", "circle", guides ? model.rows.map((_, r) => r) : [], (r) => r).attr("fill", "none").attr("stroke", ctx.theme.grid).attr("cx", cx).attr("cy", cy).attr("r", radius);
+		const place = (cell) => {
+			const [x, y] = pointRadial(turn(cell.c), radius(cell.r));
+			return `translate(${cx + x},${cy + y}) rotate(${turn(cell.c) * 180 / Math.PI})`;
+		};
+		this.glyphs(ctx, "cells", model.cells.filter((cell) => cell.value), {
+			cw: span,
+			ch: span
+		}, {
+			glyph: symbol,
+			gap: 0,
+			place,
+			size: (cell) => Math.abs(cell.value) / reach,
+			fill: () => fill,
+			tip: (cell) => this.describe(model, ctx, cell)
+		});
+		const step = Math.ceil(slots / 8);
+		const hours = model.columns.map((label, c) => ({
+			label,
+			c
+		})).filter(({ c }) => c % step === 0);
+		ctx.text(ctx.marks("column-labels", "text", hours, (d) => d.c), 10.5).attr("text-anchor", "middle").attr("dy", "0.32em").attr("x", (d) => cx + pointRadial(turn(d.c), outer + 7)[0]).attr("y", (d) => cy + pointRadial(turn(d.c), outer + 7)[1]).text((d) => d.label);
+		const fits = ring >= 11;
+		ctx.text(ctx.marks("row-labels", "text", fits ? model.rows.map((label, r) => ({
+			label,
+			r
+		})) : [], (d) => d.r), 9.5, "muted").attr("text-anchor", "middle").attr("dy", "0.32em").attr("x", cx - 3).attr("y", (d) => cy - radius(d.r)).text((d) => d.label.slice(0, 3)).attr("pointer-events", "none");
+	}
+};
+export { PunchCard, PunchCardLayout, PunchCardRows };

package/dist/charts/matrix/RecurrencePlot.js

@@ -0,0 +1,177 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixSurface } from "./MatrixSurface.js";
+import { ascending, deviation, group, line, mean, quantile, scaleLinear } from "d3";
+// src/charts/matrix/RecurrencePlot.ts
+var RecurrenceMetric = /* @__PURE__ */ function(RecurrenceMetric) {
+	RecurrenceMetric["Euclidean"] = "euclidean";
+	RecurrenceMetric["Maximum"] = "maximum";
+	RecurrenceMetric["Manhattan"] = "manhattan";
+	return RecurrenceMetric;
+}({});
+var RecurrenceDisplay = /* @__PURE__ */ function(RecurrenceDisplay) {
+	RecurrenceDisplay["Radius"] = "fixed-radius";
+	RecurrenceDisplay["Rate"] = "fixed-rate";
+	RecurrenceDisplay["Distance"] = "distance-levels";
+	return RecurrenceDisplay;
+}({});
+var RecurrenceKind = /* @__PURE__ */ function(RecurrenceKind) {
+	RecurrenceKind["Self"] = "self";
+	RecurrenceKind["Cross"] = "cross";
+	return RecurrenceKind;
+}({});
+var LEVELS = 7;
+var RAIL = 26;
+var KEY = 20;
+var LIMIT = 400;
+/** Eckmann's recurrence plot: marks every pair of times at which a system returns to a similar state. */
+var RecurrencePlot = class extends MatrixSurface {
+	static meta = {
+		id: "recurrence-plot",
+		name: "Recurrence plot",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots time against time and marks when a signal revisits a similar state, exposing periodicity, drift and regime changes.",
+		tags: [
+			"time series",
+			"phase space",
+			"dynamical systems",
+			"nonlinear"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 110, 2),
+		variants: {
+			metric: [
+				"euclidean",
+				"maximum",
+				"manhattan"
+			],
+			embedding: [
+				1,
+				2,
+				3
+			],
+			delay: [1, 4],
+			display: [
+				"fixed-radius",
+				"fixed-rate",
+				"distance-levels"
+			],
+			kind: ["self", "cross"],
+			signal: [false, true]
+		},
+		valid: (v) => !(v.embedding === 1 && (v.metric !== "euclidean" || v.delay !== 1))
+	};
+	defaults() {
+		return {
+			y: "value",
+			series: "series",
+			metric: "euclidean",
+			embedding: 1,
+			delay: 1,
+			display: "fixed-radius",
+			kind: "self",
+			signal: false
+		};
+	}
+	get blank() {
+		return this.traces()[0].length < 2;
+	}
+	/** The two compared signals; a self plot compares one with itself. Long signals are thinned to `LIMIT` samples. */
+	traces() {
+		const { data, y, series, kind } = this.options;
+		const groups = [...group(data ?? [], (row) => String(row[series]))].map(([, rows]) => rows.map((row) => +row[y]).filter(Number.isFinite));
+		const thin = (values) => {
+			const step = Math.ceil(values.length / LIMIT);
+			return step > 1 ? values.filter((_, i) => i % step === 0) : values;
+		};
+		const a = thin(groups[0] ?? []);
+		return [a, kind === "cross" ? thin(groups[1] ?? a) : a];
+	}
+	embed(values) {
+		const { embedding, delay } = this.options;
+		const count = Math.max(0, values.length - (embedding - 1) * delay);
+		const centre = mean(values) ?? 0, spread = deviation(values) || 1;
+		return Array.from({ length: count }, (_, i) => Array.from({ length: embedding }, (_, d) => (values[i + d * delay] - centre) / spread));
+	}
+	/** Distances grow with embedding dimension, so a radius in σ must grow to mean the same thing. */
+	get radiusScale() {
+		const { metric, embedding } = this.options;
+		return metric === "maximum" ? 1 : metric === "manhattan" ? embedding : Math.sqrt(embedding);
+	}
+	distance(a, b) {
+		const { metric } = this.options;
+		let result = 0;
+		for (let i = 0; i < a.length; i++) {
+			const gap = Math.abs(a[i] - b[i]);
+			if (metric === "maximum") result = Math.max(result, gap);
+			else result += metric === "manhattan" ? gap : gap * gap;
+		}
+		return metric === "euclidean" ? Math.sqrt(result) : result;
+	}
+	compose(ctx) {
+		const { display, signal, threshold } = this.options;
+		const [one, two] = this.traces();
+		const a = this.embed(one), b = this.embed(two);
+		if (!a.length || !b.length) return;
+		const rail = signal ? RAIL : 0;
+		const side = Math.max(10, Math.min(ctx.plot.width - rail, ctx.plot.height - rail - KEY));
+		const originX = (ctx.plot.width - side - rail) / 2 + rail, originY = rail;
+		const cellX = side / b.length, cellY = side / a.length;
+		const distances = a.map((point) => b.map((other) => this.distance(point, other)));
+		const flat = distances.flat().sort(ascending);
+		const top = flat[flat.length - 1] || 1;
+		const cut = display === "fixed-rate" ? quantile(flat, threshold ?? .12) : (threshold ?? .25) * this.radiusScale;
+		const level = (value) => Math.min(6, Math.floor(value / top * LEVELS));
+		const runs = Array.from({ length: display === "distance-levels" ? LEVELS : 1 }, () => []);
+		distances.forEach((row, r) => {
+			let start = -1, bucket = -1;
+			for (let c = 0; c <= row.length; c++) {
+				const value = row[c];
+				const next = value === void 0 ? -1 : display === "distance-levels" ? level(value) : value <= cut ? 0 : -1;
+				if (next === bucket) continue;
+				if (bucket >= 0) runs[bucket].push(`M${(originX + start * cellX).toFixed(1)},${(originY + side - (r + 1) * cellY).toFixed(1)}h${((c - start) * cellX).toFixed(1)}v${cellY.toFixed(2)}h${(-(c - start) * cellX).toFixed(1)}z`);
+				bucket = next;
+				start = c;
+			}
+		});
+		const layers = runs.map((list, index) => ({
+			index,
+			d: list.join("")
+		})).filter((layer) => layer.d);
+		const fill = (index) => display === "distance-levels" ? ctx.palette.sequential(1 - (index + .5) / LEVELS) : ctx.palette.sequential(.78);
+		ctx.marks("recurrences", "path", layers, (layer) => layer.index).attr("d", (layer) => layer.d).attr("fill", (layer) => fill(layer.index)).attr("shape-rendering", "crispEdges");
+		ctx.marks("frame", "rect", [0]).attr("x", originX).attr("y", originY).attr("width", side).attr("height", side).attr("fill", "transparent").attr("stroke", ctx.theme.axis).style("cursor", "crosshair").on("pointermove", (event) => {
+			const box = event.currentTarget.getBoundingClientRect();
+			const c = Math.floor((event.clientX - box.left) / box.width * b.length), r = a.length - 1 - Math.floor((event.clientY - box.top) / box.height * a.length);
+			const value = distances[r]?.[c];
+			if (value !== void 0) this.tip(event, {
+				title: `t ${r} and t ${c}`,
+				rows: [["Distance", value.toFixed(3)], ["Recurrent", value <= cut ? "yes" : "no"]]
+			});
+		}).on("pointerleave", () => this.untip());
+		const rails = signal ? [{
+			key: "top",
+			points: two,
+			along: "x",
+			offset: originY - RAIL + 2
+		}, {
+			key: "left",
+			points: one,
+			along: "y",
+			offset: originX - RAIL + 2
+		}] : [];
+		const trace = (rail) => {
+			const low = Math.min(...rail.points), high = Math.max(...rail.points);
+			const across = scaleLinear([low, high], [20, 0]), step = side / (rail.points.length - 1 || 1);
+			return (rail.along === "x" ? line().x((_, i) => originX + i * step).y((value) => rail.offset + across(value)) : line().y((_, i) => originY + side - i * step).x((value) => rail.offset + across(value)))(rail.points);
+		};
+		const traces = ctx.marks("signals", "path", rails, (rail) => rail.key).attr("d", trace).attr("fill", "none").attr("stroke", ctx.theme.inkSecondary).attr("stroke-width", 1.25);
+		ctx.drawOn(traces);
+		const rate = flat.filter((value) => value <= cut).length / flat.length;
+		const note = display === "distance-levels" ? `Stronger shade = nearer · furthest ${Scales.format(top, top)}` : `Recurrence rate ${(rate * 100).toFixed(1)}% · radius ${cut.toFixed(2)}`;
+		ctx.text(ctx.marks("note", "text", [note]), 10.5, "muted").attr("text-anchor", "middle").attr("x", originX + side / 2).attr("y", originY + side + 14).text((d) => d);
+	}
+};
+export { RecurrenceDisplay, RecurrenceKind, RecurrenceMetric, RecurrencePlot };