@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/demography/Nomogram.js

@@ -0,0 +1,447 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { DemographyMarks } from "./DemographyMarks.js";
+import { NomogramLawKind, NomogramLaws, NomogramRail } from "./NomogramLaw.js";
+import { NomogramSolver } from "./NomogramSolver.js";
+import { drag, symbol, symbolCircle, symbolDiamond } from "d3";
+// src/charts/demography/Nomogram.ts
+var NomogramIsopleth = /* @__PURE__ */ function(NomogramIsopleth) {
+	NomogramIsopleth["Single"] = "single";
+	NomogramIsopleth["Cases"] = "cases";
+	NomogramIsopleth["Pencil"] = "pencil";
+	return NomogramIsopleth;
+}({});
+var MAJOR = 8;
+var MINOR = 4;
+var NUDGE = .01;
+var CIRCLE = symbol(symbolCircle, 113)();
+var DIAMOND = symbol(symbolDiamond, 170)();
+/** Reads off a three-variable equation with a straightedge: a line through two parallel scales crosses the third at the answer. */
+var Nomogram = class extends Chart2D {
+	static meta = {
+		id: "nomogram",
+		name: "Nomogram",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Solves a three-variable law on aligned parallel scales, with a draggable isopleth through a worked example.",
+		tags: [
+			"alignment chart",
+			"parallel scales",
+			"isopleth",
+			"fagan",
+			"bmi"
+		],
+		sample: (seed) => nomogramSample(seed),
+		variants: {
+			law: Object.values(NomogramLawKind),
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			minor: [true, false],
+			isopleths: Object.values(NomogramIsopleth),
+			bands: [false, true]
+		},
+		valid: (values) => !values.bands || values.law === NomogramLawKind.BodyMass
+	};
+	#held = null;
+	#dragging = false;
+	defaults() {
+		return {
+			law: NomogramLawKind.BodyMass,
+			name: "place",
+			selected: 0,
+			orientation: Orientation.Vertical,
+			minor: true,
+			bands: false,
+			isopleths: "single"
+		};
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 12,
+			bottom: 6,
+			left: 12
+		};
+	}
+	get #solver() {
+		return new NomogramSolver(NomogramLaws.of(this.options.law));
+	}
+	/** The three readings of the live isopleth. */
+	get solution() {
+		const solver = this.#solver;
+		return solver.read(this.#hold(solver).line);
+	}
+	/** Moves an input rail to `value`, as dragging its handle would. */
+	place(rail, value) {
+		const solver = this.#solver;
+		if (solver.inputs.includes(rail)) this.#move(solver, rail, solver.scales[rail].place(value));
+		this.render();
+		return this;
+	}
+	#column(rail) {
+		return this.options[rail] ?? NomogramLaws.of(this.options.law)[rail].column;
+	}
+	#cases(solver) {
+		return this.options.data.flatMap((row, index) => {
+			const read = (rail) => DemographyMarks.number(row[this.#column(rail)]);
+			const line = solver.fit({
+				left: read(NomogramRail.Left),
+				middle: read(NomogramRail.Middle),
+				right: read(NomogramRail.Right)
+			});
+			return line ? [{
+				key: `case-${index}`,
+				index,
+				name: String(row[this.options.name] ?? `Case ${index + 1}`),
+				line
+			}] : [];
+		});
+	}
+	/** The dragged line survives a redraw, and resets when the rows, law or selected row change. */
+	#hold(solver) {
+		const { data, law, selected } = this.options;
+		const held = this.#held;
+		if (held && held.source === data && held.law === law && held.selected === selected) return held;
+		const cases = this.#cases(solver);
+		const pick = cases.find((d) => d.index === selected) ?? cases[0];
+		this.#held = {
+			source: data,
+			law,
+			selected,
+			name: pick?.name ?? "Example",
+			line: pick?.line ?? solver.complete({
+				left: .5,
+				middle: .5,
+				right: .5
+			})
+		};
+		return this.#held;
+	}
+	#move(solver, rail, place) {
+		const held = this.#hold(solver);
+		held.line = solver.complete({
+			...held.line,
+			[rail]: Math.max(0, Math.min(1, place))
+		});
+		this.options.onSolve?.(solver.read(held.line));
+	}
+	#frame({ plot }, solver) {
+		const vertical = this.options.orientation === Orientation.Vertical;
+		const across = {
+			[NomogramRail.Left]: 0,
+			[NomogramRail.Middle]: solver.spacing,
+			[NomogramRail.Right]: 1
+		};
+		const startX = vertical ? 44 : 10, startY = vertical ? 42 : 18;
+		const long = vertical ? plot.height - startY - 22 : plot.width - 2 * startX;
+		const wide = vertical ? plot.width - 2 * startX : plot.height - startY - 40;
+		const at = (over, place) => vertical ? [startX + over * wide, startY + (1 - place) * long] : [startX + place * long, startY + over * wide];
+		const gap = vertical ? 15 : 34;
+		const rails = [
+			NomogramRail.Left,
+			NomogramRail.Middle,
+			NomogramRail.Right
+		].map((rail) => {
+			const marks = solver.scales[rail].graduate(long, gap);
+			return {
+				rail,
+				scale: solver.scales[rail],
+				across: across[rail],
+				side: vertical && rail === NomogramRail.Left ? -1 : 1,
+				marks: this.options.minor ? marks : {
+					...marks,
+					minor: []
+				}
+			};
+		});
+		const tick = (rail, value, size) => {
+			const [x, y] = at(rail.across, rail.scale.place(value));
+			return vertical ? `M${x.toFixed(2)},${y.toFixed(2)}h${rail.side * size}` : `M${x.toFixed(2)},${y.toFixed(2)}v${size}`;
+		};
+		const roomy = solver.spacing * wide >= 72;
+		return {
+			vertical,
+			rails,
+			at,
+			tick,
+			roomy,
+			heads: Object.fromEntries(rails.map(({ rail, across: over }) => [rail, vertical ? [rail === NomogramRail.Left ? 0 : rail === NomogramRail.Right ? plot.width : at(over, 0)[0], 13] : [startX, at(over, 0)[1] - (rail === NomogramRail.Middle && this.options.bands ? roomy ? 26 : 16 : 8)]])),
+			anchors: vertical ? {
+				left: "start",
+				middle: "middle",
+				right: "end"
+			} : {
+				left: "start",
+				middle: "start",
+				right: "start"
+			}
+		};
+	}
+	draw(ctx) {
+		const solver = this.#solver;
+		const frame = this.#frame(ctx, solver);
+		this.#drawBands(ctx, frame);
+		this.#drawRails(ctx, frame);
+		this.#drawLabels(ctx, frame, solver);
+		this.#drawLive(ctx, frame, solver);
+		this.#bindHandles(ctx, frame, solver);
+	}
+	#drawBands(ctx, frame) {
+		const rail = frame.rails.find((d) => d.rail === NomogramRail.Middle);
+		const [low, high] = rail.scale.domain;
+		const bands = !this.options.bands ? [] : (rail.scale.spec.bands ?? []).filter((d) => d.to > low && d.from < high);
+		const shape = (d) => {
+			const [x0, y0] = frame.at(rail.across, rail.scale.place(Math.max(low, d.from)));
+			const [x1, y1] = frame.at(rail.across, rail.scale.place(Math.min(high, d.to)));
+			return frame.vertical ? `M${(x0 - 8).toFixed(2)},${(y0 - 1).toFixed(2)}H${(x0 - 2).toFixed(2)}V${(y1 + 1).toFixed(2)}H${(x0 - 8).toFixed(2)}Z` : `M${(x0 + 1).toFixed(2)},${(y0 - 8).toFixed(2)}V${(y0 - 2).toFixed(2)}H${(x1 - 1).toFixed(2)}V${(y0 - 8).toFixed(2)}Z`;
+		};
+		const strips = ctx.marks("bands", "path", bands, (d) => d.label).attr("fill", (d) => ctx.theme[d.tone]);
+		ctx.set(strips, { d: shape });
+		ctx.hover(strips, (d) => ({
+			title: d.label,
+			color: ctx.theme[d.tone],
+			rows: [[rail.scale.spec.label, `${d.from}–${d.to}`]]
+		}));
+		const labels = bands.flatMap((d) => {
+			const from = rail.scale.place(Math.max(low, d.from)), to = rail.scale.place(Math.min(high, d.to));
+			const [x, y] = frame.at(rail.across, (from + to) / 2), [x0, y0] = frame.at(rail.across, from), [x1, y1] = frame.at(rail.across, to);
+			const base = {
+				key: d.label,
+				text: d.label,
+				size: 10,
+				tone: "muted",
+				halo: true
+			};
+			if (frame.vertical) return Math.abs(y0 - y1) >= 12 ? [{
+				...base,
+				x: x - 12,
+				y: y + 4,
+				anchor: "end"
+			}] : [];
+			return frame.roomy && Math.abs(x1 - x0) >= d.label.length * 5.6 + 4 ? [{
+				...base,
+				x,
+				y: y - 11
+			}] : [];
+		});
+		DemographyMarks.captions(ctx, "band-labels", labels);
+	}
+	#drawRails(ctx, frame) {
+		const { at, rails, tick } = frame;
+		const lines = ctx.marks("axis-rails", "path", rails, (d) => d.rail).attr("stroke", ctx.theme.inkSecondary).attr("stroke-width", 2).attr("stroke-linecap", "round").attr("fill", "none");
+		ctx.set(lines, { d: (d) => DemographyMarks.segment(at(d.across, 0), at(d.across, 1)) });
+		const stroke = (name, pick, size) => {
+			const ticks = ctx.marks(name, "path", rails, (d) => d.rail).attr("stroke", ctx.theme.inkSecondary).attr("stroke-width", 1).attr("fill", "none");
+			ctx.set(ticks, { d: (d) => pick(d).map((value) => tick(d, value, size)).join("") });
+		};
+		stroke("axis-major", (d) => d.marks.major, MAJOR);
+		stroke("axis-minor", (d) => d.marks.minor, MINOR);
+		const numbers = rails.flatMap((rail) => rail.marks.major.map((value) => {
+			const [x, y] = at(rail.across, rail.scale.place(value));
+			const out = 11;
+			return frame.vertical ? {
+				key: `${rail.rail}-${value}`,
+				text: value.toLocaleString("en"),
+				x: x + rail.side * out,
+				y: y + 4,
+				anchor: rail.side < 0 ? "end" : "start",
+				halo: rail.rail === NomogramRail.Middle
+			} : {
+				key: `${rail.rail}-${value}`,
+				text: value.toLocaleString("en"),
+				x,
+				y: y + out + 9,
+				halo: rail.rail === NomogramRail.Middle
+			};
+		}));
+		DemographyMarks.captions(ctx, "tick-labels", numbers);
+	}
+	#drawLabels(ctx, frame, solver) {
+		const heads = frame.rails.map(({ rail, scale }) => {
+			const [x, y] = frame.heads[rail];
+			return {
+				key: rail,
+				text: scale.spec.label,
+				x,
+				y,
+				anchor: frame.anchors[rail],
+				tone: "secondary"
+			};
+		});
+		const { plot } = ctx;
+		heads.push({
+			key: "equation",
+			text: solver.law.equation,
+			x: plot.width / 2,
+			y: plot.height - 3,
+			tone: "muted",
+			size: 10.5
+		});
+		DemographyMarks.captions(ctx, "heads", heads);
+	}
+	#put(ctx, selection, final, from = {}) {
+		if (!this.#dragging) {
+			ctx.set(selection, final, from);
+			return;
+		}
+		selection.interrupt();
+		for (const [name, value] of Object.entries(final)) selection.attr(name, value);
+	}
+	#drawLive(ctx, frame, solver) {
+		const { isopleths } = this.options;
+		const held = this.#hold(solver);
+		const cases = this.#cases(solver);
+		const live = {
+			key: "live",
+			index: this.options.selected,
+			name: held.name,
+			line: held.line
+		};
+		const others = isopleths === "cases" ? cases.filter((d) => d.index !== held.selected) : [];
+		const color = ctx.palette.color(held.name);
+		const edge = (d) => DemographyMarks.segment(frame.at(0, d.line.left), frame.at(1, d.line.right));
+		const collapsed = (d) => DemographyMarks.segment(frame.at(0, d.line.left), frame.at(0, d.line.left));
+		const pencil = ctx.marks("pencil", "path", isopleths === "pencil" ? this.#pencil(frame, solver, held.line) : [], (_, i) => i).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1).attr("fill", "none").style("pointer-events", "none");
+		this.#put(ctx, pencil, { d: (d) => d });
+		const rest = ctx.marks("isopleths", "path", others, (d) => d.key).attr("stroke", (d) => ctx.palette.color(d.name)).attr("stroke-width", 1.5).attr("stroke-linecap", "round").attr("fill", "none");
+		this.#put(ctx, rest, { d: edge }, { d: collapsed });
+		ctx.hover(rest, (d) => this.#tip(solver, d, ctx.palette.color(d.name)));
+		rest.on("click.pick", (_, d) => this.update({ selected: d.index }));
+		const main = ctx.marks("isopleth", "path", [live], (d) => d.key).attr("stroke", color).attr("stroke-width", 2.5).attr("stroke-linecap", "round").attr("fill", "none");
+		this.#put(ctx, main, { d: edge }, { d: collapsed });
+		ctx.hover(main, (d) => this.#tip(solver, d, color));
+		const nodes = frame.rails.map(({ rail, across }) => ({
+			rail,
+			across,
+			place: held.line[rail],
+			solved: rail === solver.law.solve
+		}));
+		const toTransform = (d) => {
+			const [x, y] = frame.at(d.across, d.place);
+			return `translate(${x.toFixed(2)},${y.toFixed(2)})`;
+		};
+		const dots = ctx.marks("handles", "path", nodes, (d) => d.rail).attr("d", (d) => d.solved ? DIAMOND : CIRCLE).attr("fill", color).attr("stroke", ctx.theme.surface).attr("stroke-width", 2).style("pointer-events", "none");
+		this.#put(ctx, dots, { transform: toTransform });
+		const reading = solver.read(held.line);
+		const values = frame.rails.map(({ rail, scale }) => {
+			const [x, y] = frame.heads[rail];
+			const solved = rail === solver.law.solve;
+			const text = `${DemographyMarks.figure(reading[rail])}${scale.spec.unit ?? ""}`;
+			return frame.vertical ? {
+				key: rail,
+				text,
+				x,
+				y: y + 16,
+				anchor: frame.anchors[rail],
+				tone: "ink",
+				size: 13,
+				weight: solved ? 700 : 500
+			} : {
+				key: rail,
+				text,
+				x: ctx.plot.width - 10,
+				y,
+				anchor: "end",
+				tone: "ink",
+				size: 12,
+				weight: solved ? 700 : 500
+			};
+		});
+		DemographyMarks.captions(ctx, "readings", values);
+	}
+	#tip(solver, d, color) {
+		const reading = solver.read(d.line);
+		const rows = [
+			NomogramRail.Left,
+			NomogramRail.Middle,
+			NomogramRail.Right
+		].map((rail) => {
+			const { label, unit } = solver.scales[rail].spec;
+			return [label, `${DemographyMarks.figure(reading[rail])}${unit ?? ""}`];
+		});
+		return {
+			title: d.name,
+			color,
+			rows
+		};
+	}
+	/** Every line through the solved point: the input pairs that all give this same answer. */
+	#pencil(frame, solver, line) {
+		const { spacing } = solver;
+		const pivot = solver.law.solve === NomogramRail.Right ? 1 : spacing;
+		const start = frame.rails.find((d) => d.rail === NomogramRail.Left);
+		return start.marks.major.flatMap((value) => {
+			const left = start.scale.place(value);
+			const right = left + (line[solver.law.solve] - left) / pivot;
+			if (right < 0 || right > 1) return [];
+			return [DemographyMarks.segment(frame.at(0, left), frame.at(1, right))];
+		});
+	}
+	#bindHandles(ctx, frame, solver) {
+		const held = this.#hold(solver);
+		const inputs = frame.rails.filter((d) => d.rail !== solver.law.solve);
+		const long = frame.vertical ? Math.abs(frame.at(0, 0)[1] - frame.at(0, 1)[1]) : Math.abs(frame.at(0, 1)[0] - frame.at(0, 0)[0]);
+		const redraw = () => {
+			this.#drawLive(ctx, frame, solver);
+		};
+		const grips = ctx.marks("grips", "circle", inputs, (d) => d.rail).attr("r", 18).attr("fill", "transparent").attr("tabindex", 0).attr("aria-label", (d) => d.scale.spec.label).style("touch-action", "none").style("outline", "none");
+		const place = (d) => frame.at(d.across, this.#held.line[d.rail]);
+		ctx.set(grips, {
+			cx: (d) => place(d)[0],
+			cy: (d) => place(d)[1]
+		});
+		const follow = () => grips.attr("cx", (d) => place(d)[0]).attr("cy", (d) => place(d)[1]);
+		const reach = (event) => {
+			const [x0] = frame.at(0, 0), [, y1] = frame.at(0, 1);
+			return frame.vertical ? 1 - (event.y - y1) / long : (event.x - x0) / long;
+		};
+		grips.style("cursor", frame.vertical ? "ns-resize" : "ew-resize").call(drag().on("start", () => {
+			this.#dragging = true;
+			this.untip();
+		}).on("drag", (event, d) => {
+			this.#move(solver, d.rail, reach(event));
+			redraw();
+			follow();
+		}).on("end", () => {
+			this.#dragging = false;
+		}));
+		grips.on("keydown", (event, d) => {
+			const delta = {
+				ArrowUp: NUDGE,
+				ArrowRight: NUDGE,
+				ArrowDown: -.01,
+				ArrowLeft: -.01
+			}[event.key];
+			if (!delta) return;
+			event.preventDefault();
+			this.#dragging = true;
+			this.#move(solver, d.rail, held.line[d.rail] + delta);
+			redraw();
+			follow();
+			this.#dragging = false;
+		});
+	}
+};
+/**
+* Regional profiles reshaped from SampleData's categories: one row per region,
+* with each series' 20..100 value rescaled to a plausible range for that measure.
+*/
+function nomogramSample(seed) {
+	const rows = SampleData.categories(seed, 7, 8);
+	return [...new Set(rows.map((row) => row.category))].map((place) => {
+		const [a, b, c, d, e, f, g, h] = rows.filter((row) => row.category === place).map((row) => (row.value - 20) / 80);
+		return {
+			place,
+			weight: Math.round(58 + a * 34),
+			height: Math.round(156 + b * 30),
+			birthRate: +(10 + c * 32).toFixed(1),
+			deathRate: +(5 + d * 12).toFixed(1),
+			years: 10 + Math.round(e * 9) * 10,
+			growth: +(.3 + f * 2.7).toFixed(1),
+			pretest: +(2 + g * 28).toFixed(1),
+			ratio: +(2 + h * 14).toFixed(1)
+		};
+	});
+}
+export { Nomogram, NomogramIsopleth };

package/dist/charts/demography/NomogramLaw.js

@@ -0,0 +1,221 @@
+// src/charts/demography/NomogramLaw.ts
+var { exp, log } = Math;
+var NomogramRail = /* @__PURE__ */ function(NomogramRail) {
+	NomogramRail["Left"] = "left";
+	NomogramRail["Middle"] = "middle";
+	NomogramRail["Right"] = "right";
+	return NomogramRail;
+}({});
+var NomogramLawKind = /* @__PURE__ */ function(NomogramLawKind) {
+	NomogramLawKind["NaturalIncrease"] = "natural-increase";
+	NomogramLawKind["Growth"] = "growth";
+	NomogramLawKind["BodyMass"] = "body-mass";
+	NomogramLawKind["Fagan"] = "fagan";
+	return NomogramLawKind;
+}({});
+var same = (value) => value;
+var flip = (value) => -value;
+var logit = (percent) => log(percent / (100 - percent));
+var PERCENT = [
+	50,
+	10,
+	90,
+	1,
+	99,
+	20,
+	80,
+	5,
+	95,
+	30,
+	70,
+	40,
+	60,
+	2,
+	98,
+	.5,
+	.2,
+	.1
+];
+var LAWS = {
+	["natural-increase"]: {
+		solve: "middle",
+		equation: "Natural increase = birth rate − death rate",
+		left: {
+			label: "Crude birth rate",
+			unit: "‰",
+			column: "birthRate",
+			domain: [5, 55],
+			fn: same,
+			inverse: same
+		},
+		middle: {
+			label: "Natural increase",
+			unit: "‰",
+			fn: same,
+			inverse: same
+		},
+		right: {
+			label: "Crude death rate",
+			unit: "‰",
+			column: "deathRate",
+			domain: [0, 30],
+			fn: flip,
+			inverse: flip
+		}
+	},
+	["growth"]: {
+		solve: "middle",
+		equation: "Population multiple = e^(rate × years)",
+		left: {
+			label: "Years",
+			column: "years",
+			domain: [5, 200],
+			fn: log,
+			inverse: exp
+		},
+		middle: {
+			label: "Multiple",
+			unit: "×",
+			fn: (multiple) => log(log(multiple)),
+			inverse: (term) => exp(exp(term)),
+			values: [
+				2,
+				10,
+				100,
+				1e3,
+				1e4,
+				1.5,
+				1.1,
+				5,
+				3,
+				20,
+				50,
+				1.2,
+				200,
+				500,
+				1.05,
+				1.02,
+				4,
+				1.01,
+				2e3,
+				5e3
+			]
+		},
+		right: {
+			label: "Growth rate",
+			unit: "%/yr",
+			column: "growth",
+			domain: [.1, 5],
+			fn: (rate) => log(rate / 100),
+			inverse: (term) => 100 * exp(term)
+		}
+	},
+	["body-mass"]: {
+		solve: "middle",
+		equation: "BMI = weight / height²",
+		left: {
+			label: "Weight",
+			unit: " kg",
+			column: "weight",
+			domain: [40, 160],
+			fn: log,
+			inverse: exp
+		},
+		middle: {
+			label: "BMI",
+			unit: " kg/m²",
+			fn: log,
+			inverse: exp,
+			bands: [
+				{
+					from: 0,
+					to: 18.5,
+					label: "Underweight",
+					tone: "warning"
+				},
+				{
+					from: 18.5,
+					to: 25,
+					label: "Normal",
+					tone: "good"
+				},
+				{
+					from: 25,
+					to: 30,
+					label: "Overweight",
+					tone: "serious"
+				},
+				{
+					from: 30,
+					to: 1e3,
+					label: "Obese",
+					tone: "critical"
+				}
+			]
+		},
+		right: {
+			label: "Height",
+			unit: " cm",
+			column: "height",
+			domain: [140, 210],
+			fn: (height) => -2 * log(height / 100),
+			inverse: (term) => 100 * exp(-term / 2)
+		}
+	},
+	["fagan"]: {
+		solve: "right",
+		equation: "Post-test odds = pre-test odds × likelihood ratio",
+		left: {
+			label: "Pre-test",
+			unit: "%",
+			column: "pretest",
+			domain: [.1, 99],
+			fn: (percent) => -logit(percent),
+			inverse: (term) => 100 / (1 + exp(term)),
+			values: PERCENT
+		},
+		middle: {
+			label: "Likelihood ratio",
+			column: "ratio",
+			fn: log,
+			inverse: exp,
+			values: [
+				1,
+				10,
+				100,
+				1e3,
+				.1,
+				.01,
+				.001,
+				2,
+				.5,
+				5,
+				.2,
+				20,
+				.05,
+				50,
+				.02,
+				200,
+				500,
+				.005,
+				.002
+			]
+		},
+		right: {
+			label: "Post-test",
+			unit: "%",
+			column: "posttest",
+			domain: [.1, 99],
+			fn: logit,
+			inverse: (term) => 100 / (1 + exp(-term)),
+			values: PERCENT
+		}
+	}
+};
+/** The worked equations `Nomogram` ships with, each already in parallel-scale form. */
+var NomogramLaws = class {
+	static of(law) {
+		return typeof law === "string" ? LAWS[law] : law;
+	}
+};
+export { NomogramLawKind, NomogramLaws, NomogramRail };