@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/density/TwoDHistogram.js

@@ -0,0 +1,231 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { PointDensityChart } from "./PointDensityChart.js";
+import { ascending, bisectRight, max, quantileSorted, range, sum, thresholdFreedmanDiaconis, thresholdScott, thresholdSturges } from "d3";
+// src/charts/density/TwoDHistogram.ts
+/** Rule that sets the bin edges. */
+var HistogramBinRule = /* @__PURE__ */ function(HistogramBinRule) {
+	HistogramBinRule["Sturges"] = "sturges";
+	HistogramBinRule["Scott"] = "scott";
+	HistogramBinRule["FreedmanDiaconis"] = "freedman-diaconis";
+	HistogramBinRule["SquareRoot"] = "square-root";
+	HistogramBinRule["Quantile"] = "quantile";
+	return HistogramBinRule;
+}({});
+/** The mark drawn in each bin. */
+var HistogramCell = /* @__PURE__ */ function(HistogramCell) {
+	HistogramCell["Tile"] = "tile";
+	HistogramCell["Bubble"] = "bubble";
+	HistogramCell["Inset"] = "inset";
+	return HistogramCell;
+}({});
+var HistogramMarginal = /* @__PURE__ */ function(HistogramMarginal) {
+	HistogramMarginal["None"] = "none";
+	HistogramMarginal["Bars"] = "bars";
+	HistogramMarginal["Steps"] = "steps";
+	return HistogramMarginal;
+}({});
+/** Whether cells compare across the whole grid, or within their own column. */
+var HistogramNorm = /* @__PURE__ */ function(HistogramNorm) {
+	HistogramNorm["Count"] = "count";
+	HistogramNorm["Column"] = "column";
+	return HistogramNorm;
+}({});
+var PANEL = 40;
+var GAP = 6;
+/** Counts points in a rectangular grid. Use it when bin edges must be exact and countable, unlike a smoothed density. */
+var TwoDHistogram = class extends PointDensityChart {
+	static meta = {
+		id: "density-histogram-2d",
+		name: "2D histogram",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Bins points on two axes with a choice of edge rule, then shows each bin as a tile, bubble or inset with optional marginal histograms.",
+		tags: [
+			"bivariate histogram",
+			"heatmap",
+			"binning",
+			"marginal"
+		],
+		sample: (seed) => SampleData.points(seed, 700, 3),
+		variants: {
+			rule: [
+				"sturges",
+				"scott",
+				"freedman-diaconis",
+				"square-root",
+				"quantile"
+			],
+			cell: [
+				"tile",
+				"bubble",
+				"inset"
+			],
+			marginal: [
+				"none",
+				"bars",
+				"steps"
+			],
+			norm: ["count", "column"],
+			empties: [false, true]
+		},
+		valid: ({ cell, norm, rule }) => norm === "count" || cell !== "tile" && rule !== "quantile"
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			rule: "sturges",
+			cell: "tile",
+			marginal: "none",
+			norm: "count",
+			empties: false
+		};
+	}
+	inset() {
+		return this.options.marginal === "none" ? {
+			top: 0,
+			right: 0
+		} : {
+			top: 46,
+			right: 46
+		};
+	}
+	get sizeEncoded() {
+		return this.options.cell !== "tile";
+	}
+	/** Bin edges in pixels, ascending. */
+	edges(values, low, high) {
+		const { rule } = this.options;
+		const sorted = [...values].sort(ascending);
+		const span = (from, to) => to > from ? [from, to] : [from, from + 1];
+		const [a, b] = span(sorted[0] ?? low, sorted[sorted.length - 1] ?? high);
+		if (rule === "quantile") {
+			const cuts = range(1, 10).map((i) => quantileSorted(sorted, i / 10) ?? low);
+			return [.../* @__PURE__ */ new Set([
+				low,
+				...cuts,
+				high
+			])];
+		}
+		const count = rule === "square-root" ? Math.ceil(Math.sqrt(values.length)) : rule === "scott" ? thresholdScott(sorted, a, b) : rule === "freedman-diaconis" ? thresholdFreedmanDiaconis(sorted, a, b) : thresholdSturges(sorted);
+		const bins = Math.max(1, Math.min(40, count || 1));
+		return range(bins + 1).map((i) => low + (high - low) * i / bins);
+	}
+	drawDensity(ctx, _axes, points) {
+		const { cell, norm, empties, marginal } = this.options;
+		const { width, height, top } = this.body(ctx);
+		const xs = this.edges(points.map((d) => d.px), 0, width);
+		const ys = this.edges(points.map((d) => d.py), top, top + height);
+		const columns = xs.length - 1, rows = ys.length - 1;
+		const counts = new Array(columns * rows).fill(0);
+		const clampBin = (edges, value) => Math.max(0, Math.min(edges.length - 2, bisectRight(edges, value) - 1));
+		for (const { px, py } of points) counts[clampBin(xs, px) + clampBin(ys, py) * columns]++;
+		const columnTotals = range(columns).map((i) => sum(range(rows), (j) => counts[i + j * columns]));
+		const rowTotals = range(rows).map((j) => sum(range(columns), (i) => counts[i + j * columns]));
+		const area = (k) => (xs[k % columns + 1] - xs[k % columns]) * (ys[Math.floor(k / columns) + 1] - ys[Math.floor(k / columns)]) || 1;
+		const unequal = this.options.rule === "quantile";
+		const shares = counts.map((count, k) => norm === "column" ? count / (columnTotals[k % columns] || 1) : unequal ? count / area(k) : count);
+		const top1 = max(shares) || 1;
+		const bins = range(columns * rows).map((k) => {
+			const i = k % columns, j = Math.floor(k / columns);
+			return {
+				key: `${i}/${j}`,
+				x0: xs[i],
+				x1: xs[i + 1],
+				y0: ys[j],
+				y1: ys[j + 1],
+				count: counts[k],
+				share: shares[k] / top1
+			};
+		}).filter((bin) => bin.count > 0 || empties);
+		const tone = (d) => d.count ? ctx.palette.sequential(cell === "tile" ? .12 + .88 * d.share : .72) : ctx.theme.grid;
+		const gap = columns > 24 || rows > 24 ? 1 : 2;
+		const w = (d) => Math.max(1, d.x1 - d.x0 - gap), h = (d) => Math.max(1, d.y1 - d.y0 - gap);
+		const scale = (d) => cell === "tile" || !d.count ? 1 : Math.sqrt(d.share);
+		const fx = (d) => d.x0 + (d.x1 - d.x0 - w(d) * scale(d)) / 2, fy = (d) => d.y0 + (d.y1 - d.y0 - h(d) * scale(d)) / 2;
+		const round = cell === "bubble";
+		const tiles = ctx.marks("tiles", "rect", round ? bins.filter((d) => !d.count) : bins, (d) => d.key).attr("fill", tone).attr("fill-opacity", (d) => d.count ? 1 : .5);
+		ctx.set(tiles, {
+			x: fx,
+			y: fy,
+			width: (d) => w(d) * scale(d),
+			height: (d) => h(d) * scale(d),
+			rx: 2
+		}, {
+			x: fx,
+			y: fy,
+			width: 0,
+			height: 0
+		}, 1);
+		const bubbles = ctx.marks("bubbles", "circle", round ? bins.filter((d) => d.count) : [], (d) => d.key).attr("fill", tone);
+		ctx.set(bubbles, {
+			cx: (d) => (d.x0 + d.x1) / 2,
+			cy: (d) => (d.y0 + d.y1) / 2,
+			r: (d) => Math.max(1, Math.min(d.x1 - d.x0, d.y1 - d.y0) * .46 * Math.sqrt(d.share))
+		}, {
+			cx: (d) => (d.x0 + d.x1) / 2,
+			cy: (d) => (d.y0 + d.y1) / 2,
+			r: 0
+		}, 1);
+		for (const marks of [tiles, bubbles]) ctx.hover(marks, (d) => ({
+			color: tone(d),
+			rows: [["Points", d.count], ...norm === "column" ? [["Share of column", `${Math.round(d.share * top1 * 100)}%`]] : []]
+		}));
+		this.drawMarginals(ctx, xs, ys, columnTotals, rowTotals, marginal);
+		this.showRamp(ctx, top1, (t) => ctx.palette.sequential(.12 + .88 * t), unequal ? (t) => `${Math.round(t * 100)}%` : void 0);
+	}
+	drawMarginals(ctx, xs, ys, columnTotals, rowTotals, marginal) {
+		const { width } = this.body(ctx);
+		const bars = marginal === "bars";
+		const perX = columnTotals.map((total, i) => total / (xs[i + 1] - xs[i] || 1)), perY = rowTotals.map((total, j) => total / (ys[j + 1] - ys[j] || 1));
+		const peakX = max(perX) || 1, peakY = max(perY) || 1;
+		const fill = ctx.palette.sequential(.6);
+		const up = (value) => value / peakX * 38, right = (value) => value / peakY * 38;
+		const topBars = ctx.marks("marginal-x", "rect", bars ? perX.map((value, i) => ({
+			value,
+			i,
+			total: columnTotals[i]
+		})) : [], (d) => d.i).attr("fill", fill).attr("rx", 1);
+		ctx.set(topBars, {
+			x: (d) => xs[d.i] + 1,
+			width: (d) => Math.max(1, xs[d.i + 1] - xs[d.i] - 2),
+			y: (d) => PANEL - up(d.value),
+			height: (d) => up(d.value)
+		}, {
+			x: (d) => xs[d.i] + 1,
+			width: (d) => Math.max(1, xs[d.i + 1] - xs[d.i] - 2),
+			y: PANEL,
+			height: 0
+		});
+		ctx.hover(topBars, (d) => ({
+			rows: [["Points", d.total]],
+			color: fill
+		}));
+		const sideBars = ctx.marks("marginal-y", "rect", bars ? perY.map((value, j) => ({
+			value,
+			j,
+			total: rowTotals[j]
+		})) : [], (d) => d.j).attr("fill", fill).attr("rx", 1);
+		ctx.set(sideBars, {
+			x: width + GAP,
+			y: (d) => ys[d.j] + 1,
+			height: (d) => Math.max(1, ys[d.j + 1] - ys[d.j] - 2),
+			width: (d) => right(d.value)
+		}, {
+			x: width + GAP,
+			y: (d) => ys[d.j] + 1,
+			height: (d) => Math.max(1, ys[d.j + 1] - ys[d.j] - 2),
+			width: 0
+		});
+		ctx.hover(sideBars, (d) => ({
+			rows: [["Points", d.total]],
+			color: fill
+		}));
+		const stepTop = `M${xs[0]},${PANEL}${perX.map((value, i) => `V${(PANEL - up(value)).toFixed(1)}H${xs[i + 1].toFixed(1)}`).join("")}V${PANEL}`;
+		const stepSide = `M${width + GAP},${ys[0]}${perY.map((value, j) => `H${(width + GAP + right(value)).toFixed(1)}V${ys[j + 1].toFixed(1)}`).join("")}H${width + GAP}`;
+		const steps = ctx.marks("marginal-steps", "path", marginal === "steps" ? [stepTop, stepSide] : []).attr("fill", "none").attr("stroke", fill).attr("stroke-width", 2).attr("stroke-linejoin", "round");
+		ctx.set(steps, { d: (d) => d });
+	}
+};
+export { HistogramBinRule, HistogramCell, HistogramMarginal, HistogramNorm, TwoDHistogram };

package/dist/charts/density/VoronoiDiagram.js

@@ -0,0 +1,124 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { PlaneGeometry } from "./PlaneGeometry.js";
+import { PointDensityChart } from "./PointDensityChart.js";
+import { Delaunay, polygonHull } from "d3";
+// src/charts/density/VoronoiDiagram.ts
+var VoronoiShape = /* @__PURE__ */ function(VoronoiShape) {
+	VoronoiShape["Sharp"] = "sharp";
+	VoronoiShape["Inset"] = "inset";
+	VoronoiShape["Rounded"] = "rounded";
+	return VoronoiShape;
+}({});
+/** What bounds the outer cells. */
+var VoronoiClip = /* @__PURE__ */ function(VoronoiClip) {
+	VoronoiClip["Frame"] = "frame";
+	VoronoiClip["Hull"] = "hull";
+	VoronoiClip["Disc"] = "disc";
+	return VoronoiClip;
+}({});
+var VoronoiStyle = /* @__PURE__ */ function(VoronoiStyle) {
+	VoronoiStyle["Filled"] = "filled";
+	VoronoiStyle["Wire"] = "wire";
+	return VoronoiStyle;
+}({});
+/** Partitions the plot by nearest point. Use it for service areas, nearest-neighbour reading and space-filling hover targets. */
+var VoronoiDiagram = class extends PointDensityChart {
+	static meta = {
+		id: "density-voronoi",
+		name: "Voronoi diagram",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Gives each point the region closer to it than to any other, so small cells show crowding and large cells show sparse areas.",
+		tags: [
+			"tessellation",
+			"thiessen",
+			"nearest neighbour",
+			"lloyd"
+		],
+		sample: (seed) => SampleData.points(seed, 90, 3),
+		variants: {
+			relax: [
+				0,
+				1,
+				4
+			],
+			cellShape: [
+				"sharp",
+				"inset",
+				"rounded"
+			],
+			clip: [
+				"frame",
+				"hull",
+				"disc"
+			],
+			style: ["filled", "wire"],
+			sites: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			relax: 0,
+			cellShape: "sharp",
+			clip: "frame",
+			style: "filled",
+			sites: true
+		};
+	}
+	cells(ctx, points) {
+		const { relax, clip, cellShape } = this.options;
+		const { width, height } = ctx.plot;
+		const sites = PlaneGeometry.relax(this.pixels(points), width, height, relax);
+		if (!sites.length) return [];
+		const voronoi = Delaunay.from(sites).voronoi([
+			0,
+			0,
+			width,
+			height
+		]);
+		const hull = sites.length > 2 ? polygonHull(sites) : null;
+		const reach = Math.sqrt(width * height / sites.length) * .75;
+		return sites.flatMap((site, index) => {
+			let polygon = voronoi.cellPolygon(index)?.slice(0, -1) ?? [];
+			if (clip === "hull" && hull) polygon = PlaneGeometry.clipConvex(polygon, hull);
+			if (clip === "disc") polygon = PlaneGeometry.clipConvex(polygon, PlaneGeometry.disc(site[0], site[1], reach));
+			if (cellShape === "inset") polygon = PlaneGeometry.inset(polygon, 2.5);
+			if (cellShape === "rounded") polygon = PlaneGeometry.rounded(PlaneGeometry.inset(polygon, 1.5), 3);
+			return polygon.length > 2 ? [{
+				index,
+				site,
+				polygon,
+				point: points[index]
+			}] : [];
+		});
+	}
+	drawDensity(ctx, _axes, points) {
+		const { style, sites, cellShape } = this.options;
+		const cells = this.cells(ctx, points);
+		const filled = style === "filled";
+		const hue = (d) => ctx.palette.color(d.point.group);
+		const paths = ctx.marks("cells", "path", cells, (d) => d.index).attr("stroke-linejoin", "round").attr("fill", (d) => filled ? hue(d) : "transparent").attr("fill-opacity", .42).attr("stroke", filled && cellShape === "sharp" ? ctx.theme.surface : "none").attr("stroke-width", 2);
+		this.reveal(ctx, paths, { d: (d) => PlaneGeometry.path(d.polygon) }, 4);
+		ctx.hover(paths, (d) => ({
+			title: d.point.group || void 0,
+			color: hue(d),
+			rows: [...this.tipRows(d.point), ["Cell area", `${Math.round(PlaneGeometry.area(d.polygon))} px²`]]
+		}));
+		const mesh = ctx.marks("wire", "path", filled ? [] : [cells.map((d) => PlaneGeometry.path(d.polygon)).join("")]).attr("fill", "none").attr("stroke", ctx.palette.sequential(.6)).attr("stroke-width", 1).style("pointer-events", "none");
+		ctx.set(mesh, { d: (d) => d });
+		const dots = ctx.marks("sites", "circle", sites ? cells : [], (d) => d.index).attr("fill", hue).attr("stroke", ctx.theme.surface).attr("stroke-width", 2).style("pointer-events", "none");
+		ctx.set(dots, {
+			cx: (d) => d.site[0],
+			cy: (d) => d.site[1],
+			r: 4
+		}, {
+			cx: (d) => d.site[0],
+			cy: (d) => d.site[1],
+			r: 0
+		}, 4);
+	}
+};
+export { VoronoiClip, VoronoiDiagram, VoronoiShape, VoronoiStyle };

package/dist/charts/density/index.js

@@ -0,0 +1,57 @@
+import { ContourLabels } from "./ContourLabels.js";
+import { DensityBandwidth, DensityKernel, DensityOverlay, DensityTransform, FieldInterpolation, LevelSpacing } from "./DensityEnums.js";
+import { FieldLevels } from "./FieldLevels.js";
+import { FieldChart } from "./FieldChart.js";
+import { FieldContours } from "./FieldContours.js";
+import { GridFieldChart } from "./GridFieldChart.js";
+import { ContourChart } from "./ContourChart.js";
+import { ContourPolarity, FilledContour } from "./FilledContour.js";
+import { KernelField } from "./KernelField.js";
+import { PointDensityChart } from "./PointDensityChart.js";
+import { DensityContourChart } from "./DensityContourChart.js";
+import { PlaneGeometry } from "./PlaneGeometry.js";
+import { KernelDensity2D, KernelMarginal, KernelReference, KernelShading } from "./KernelDensity2D.js";
+import { HexAggregate, HexEncoding, HexbinChart } from "./HexbinChart.js";
+import { HistogramBinRule, HistogramCell, HistogramMarginal, HistogramNorm, TwoDHistogram } from "./TwoDHistogram.js";
+import { ShadeRaster } from "./ShadeRaster.js";
+import { RasterDensity, RasterShading } from "./RasterDensity.js";
+import { DotLattice, LatticeKind } from "./DotLattice.js";
+import { BinnedDotChart, BinnedDotEncoding } from "./BinnedDotChart.js";
+import { SunflowerPetal, SunflowerPlot } from "./SunflowerPlot.js";
+import { TileFit, TileMapDensity, TileShape } from "./TileMapDensity.js";
+import { VoronoiClip, VoronoiDiagram, VoronoiShape, VoronoiStyle } from "./VoronoiDiagram.js";
+import { DelaunayMesh, MeshGraph, MeshStyle } from "./DelaunayMesh.js";
+import { ConvexLayers, LayerCurve, LayerStyle } from "./ConvexLayers.js";
+import { PartitionMark, QuadtreeChart, SpatialPartition } from "./QuadtreeChart.js";
+import { IsolineChart, IsolineRange, IsolineStyle } from "./IsolineChart.js";
+import { GeoFreeShadedSurface, ReliefModel } from "./GeoFreeShadedSurface.js";
+import { MarchingCell, MarchingCrossing, MarchingSquaresChart } from "./MarchingSquaresChart.js";
+import { GradientFieldChart, GradientFlow, GradientMark, GradientSeeding } from "./GradientFieldChart.js";
+import { DotDensityChart, DotPlacement, DotRegionLayout, DotShape } from "./DotDensityChart.js";
+import { DensityScatter, ScatterMode, ScatterStacking } from "./DensityScatter.js";
+import { StippleDensity } from "./StippleDensity.js";
+// src/charts/density/index.ts
+var densityCatalog = [
+	ContourChart,
+	DensityContourChart,
+	HexbinChart,
+	TwoDHistogram,
+	FilledContour,
+	RasterDensity,
+	KernelDensity2D,
+	BinnedDotChart,
+	SunflowerPlot,
+	TileMapDensity,
+	VoronoiDiagram,
+	DelaunayMesh,
+	ConvexLayers,
+	QuadtreeChart,
+	IsolineChart,
+	GeoFreeShadedSurface,
+	MarchingSquaresChart,
+	GradientFieldChart,
+	DotDensityChart,
+	DensityScatter,
+	StippleDensity
+];
+export { BinnedDotChart, BinnedDotEncoding, ContourChart, ContourLabels, ContourPolarity, ConvexLayers, DelaunayMesh, DensityBandwidth, DensityContourChart, DensityKernel, DensityOverlay, DensityScatter, DensityTransform, DotDensityChart, DotLattice, DotPlacement, DotRegionLayout, DotShape, FieldChart, FieldContours, FieldInterpolation, FieldLevels, FilledContour, GeoFreeShadedSurface, GradientFieldChart, GradientFlow, GradientMark, GradientSeeding, GridFieldChart, HexAggregate, HexEncoding, HexbinChart, HistogramBinRule, HistogramCell, HistogramMarginal, HistogramNorm, IsolineChart, IsolineRange, IsolineStyle, KernelDensity2D, KernelField, KernelMarginal, KernelReference, KernelShading, LatticeKind, LayerCurve, LayerStyle, LevelSpacing, MarchingCell, MarchingCrossing, MarchingSquaresChart, MeshGraph, MeshStyle, PartitionMark, PlaneGeometry, PointDensityChart, QuadtreeChart, RasterDensity, RasterShading, ReliefModel, ScatterMode, ScatterStacking, ShadeRaster, SpatialPartition, StippleDensity, SunflowerPetal, SunflowerPlot, TileFit, TileMapDensity, TileShape, TwoDHistogram, VoronoiClip, VoronoiDiagram, VoronoiShape, VoronoiStyle, densityCatalog };

package/dist/charts/distribution/AxisFrame.js

@@ -0,0 +1,89 @@
+import { curveLinear, line } from "d3";
+// src/charts/distribution/AxisFrame.ts
+var round = (value) => Math.round(value * 100) / 100;
+var toward = (a, b, by) => {
+	const length = Math.hypot(b[0] - a[0], b[1] - a[1]) || 1;
+	return [a[0] + (b[0] - a[0]) * by / length, a[1] + (b[1] - a[1]) * by / length];
+};
+/** Maps (value, cross) to (x, y) so a chart draws one way and flips by orientation. `cross` is always in pixels. */
+var AxisFrame = class {
+	valueOnX;
+	value;
+	constructor(valueOnX, value) {
+		this.valueOnX = valueOnX;
+		this.value = value;
+	}
+	px(along, cross) {
+		return this.valueOnX ? [along, cross] : [cross, along];
+	}
+	at(value, cross) {
+		return this.px(this.value(value), cross);
+	}
+	/** Path through (value, cross) pairs. */
+	path(points, closed = false, curve = curveLinear) {
+		const d = line().curve(curve).x((p) => round(this.at(p[0], p[1])[0])).y((p) => round(this.at(p[0], p[1])[1]))(points) ?? "";
+		return closed && d ? `${d}Z` : d;
+	}
+	/** Same as `path` with the first coordinate already in pixels. */
+	pixelPath(points, closed = false) {
+		const d = points.map((p, i) => {
+			const [x, y] = this.px(p[0], p[1]);
+			return `${i ? "L" : "M"}${round(x)},${round(y)}`;
+		}).join("");
+		return closed && d ? `${d}Z` : d;
+	}
+	rect(v0, v1, c0, c1) {
+		const a = this.at(v0, c0), b = this.at(v1, c1);
+		return {
+			x: Math.min(a[0], b[0]),
+			y: Math.min(a[1], b[1]),
+			width: Math.abs(a[0] - b[0]),
+			height: Math.abs(a[1] - b[1])
+		};
+	}
+	line(v0, c0, v1, c1) {
+		const a = this.at(v0, c0), b = this.at(v1, c1);
+		return {
+			x1: a[0],
+			y1: a[1],
+			x2: b[0],
+			y2: b[1]
+		};
+	}
+	/** Bar from `base` to `tip` across pixel span `a0..a1`, rounded only at its data end. */
+	bar(a0, a1, base, tip, radius = 4) {
+		const p0 = this.px(a0, base), p1 = this.px(a0, tip), p2 = this.px(a1, tip), p3 = this.px(a1, base);
+		const r = Math.min(radius, Math.abs(a1 - a0) / 2, Math.abs(tip - base));
+		const [q0, q1, q2, q3] = [
+			toward(p1, p0, r),
+			toward(p1, p2, r),
+			toward(p2, p1, r),
+			toward(p2, p3, r)
+		];
+		const n = (p) => `${round(p[0])},${round(p[1])}`;
+		return `M${n(p0)}L${n(q0)}Q${n(p1)} ${n(q1)}L${n(q2)}Q${n(p2)} ${n(q3)}L${n(p3)}Z`;
+	}
+};
+/** Frame whose cross axis is a band per group. */
+var BandFrame = class extends AxisFrame {
+	band;
+	constructor(valueOnX, value, band) {
+		super(valueOnX, value);
+		this.band = band;
+	}
+	center(name) {
+		return (this.band(name) ?? 0) + this.band.bandwidth() / 2;
+	}
+	get half() {
+		return this.band.bandwidth() / 2;
+	}
+};
+/** Frame whose cross axis is a continuous measure: frequency, density or probability. */
+var MeasureFrame = class extends AxisFrame {
+	measure;
+	constructor(valueOnX, value, measure) {
+		super(valueOnX, value);
+		this.measure = measure;
+	}
+};
+export { AxisFrame, BandFrame, MeasureFrame };

package/dist/charts/distribution/BackToBackHistogram.js

@@ -0,0 +1,100 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { BinnedChart } from "./BinnedChart.js";
+import { readable } from "./DistributionChart.js";
+import { DistributionSamples } from "./DistributionSamples.js";
+import { BinRule, FrequencyScale, HistogramShape } from "./enums.js";
+import { format, max } from "d3";
+// src/charts/distribution/BackToBackHistogram.ts
+/** Two histograms mirrored about a shared baseline: the first two groups, as in a population pyramid. */
+var BackToBackHistogram = class extends BinnedChart {
+	static meta = {
+		id: "back-to-back-histogram",
+		name: "Back-to-back histogram",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Mirrors two histograms on one baseline to compare their shapes bin by bin, like a population pyramid.",
+		tags: [
+			"population pyramid",
+			"mirror histogram",
+			"tornado"
+		],
+		sample: (seed) => DistributionSamples.uneven(seed, 220, 2),
+		variants: {
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			bins: [
+				BinRule.FreedmanDiaconis,
+				BinRule.Sturges,
+				BinRule.SquareRoot
+			],
+			frequency: [
+				FrequencyScale.Count,
+				FrequencyScale.Percent,
+				FrequencyScale.Density
+			],
+			shape: [HistogramShape.Bars, HistogramShape.Outline]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			orientation: Orientation.Horizontal,
+			shape: HistogramShape.Bars
+		};
+	}
+	showsLegend() {
+		return true;
+	}
+	samples() {
+		return super.samples().slice(0, 2);
+	}
+	sides(samples) {
+		const edges = this.edges(samples);
+		return samples.flatMap((sample, s) => this.bins(sample, edges).map((bin, i) => ({
+			...bin,
+			key: `${sample.name}/${i}`,
+			sample,
+			sign: s ? 1 : -1
+		})));
+	}
+	measureDomain(samples) {
+		const top = max(this.sides(samples), (b) => b.height) ?? 1;
+		return [-top, top];
+	}
+	measureFormat(reach) {
+		const show = super.measureFormat(reach);
+		return (value) => show(Math.abs(value));
+	}
+	plotSeries(ctx, frame, samples) {
+		const { shape, frequency } = this.options;
+		const sides = this.sides(samples), m = frame.measure, base = m(0);
+		const span = (b) => {
+			const a = frame.value(b.lo), z = frame.value(b.hi), gap = Math.min(2, Math.abs(z - a) * .2) * Math.sign(z - a);
+			return [a + gap / 2, z - gap / 2];
+		};
+		const bars = ctx.marks("mirror-bars", "path", shape === HistogramShape.Bars ? sides.filter((b) => b.count) : [], (b) => b.key).attr("fill", (b) => ctx.palette.color(b.sample.name));
+		ctx.set(bars, { d: (b) => frame.bar(...span(b), base, m(b.sign * b.height)) }, { d: (b) => frame.bar(...span(b), base, base) }, 4);
+		const tell = format(".1%");
+		ctx.hover(bars, (b) => ({
+			title: `${readable(b.lo)} – ${readable(b.hi)}`,
+			color: ctx.palette.color(b.sample.name),
+			rows: [[b.sample.name, frequency === FrequencyScale.Percent ? tell(b.height) : b.count]]
+		}));
+		const outline = (sample) => {
+			const own = sides.filter((b) => b.sample === sample);
+			if (!own.length) return "";
+			return frame.path([
+				[own[0].lo, base],
+				...own.flatMap((b) => [[b.lo, m(b.sign * b.height)], [b.hi, m(b.sign * b.height)]]),
+				[own[own.length - 1].hi, base]
+			]);
+		};
+		const lines = ctx.marks("mirror-outline", "path", shape === HistogramShape.Outline ? samples : [], (s) => s.name).attr("fill", (s) => ctx.palette.color(s.name)).attr("fill-opacity", .14).attr("stroke", (s) => ctx.palette.color(s.name)).attr("stroke-width", 2).attr("stroke-linejoin", "round").attr("d", outline);
+		ctx.hover(lines, (s) => this.summaryTip(s, ctx));
+		const axis = ctx.marks("mirror-axis", "line", [0], () => "axis").attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		const [lo, hi] = frame.value.domain();
+		const rule = frame.line(lo, base, hi, base);
+		axis.attr("x1", rule.x1).attr("x2", rule.x2).attr("y1", rule.y1).attr("y2", rule.y2);
+	}
+};
+export { BackToBackHistogram };