@classytic/labs 0.6.0 → 0.7.0

package/dist/domains/statistics/frequency-density/density-scene.mjs

@@ -3,7 +3,7 @@
 import { FigText } from "../../../kit/figure/text.mjs";
 import { Figure, HUE, STROKE, alpha, tint } from "../../../kit/figure/figure.mjs";
 import { GripKey } from "../../../kit/figure/grip.mjs";
-import "../../../kit/figure/index.mjs";
+import { useNarrow } from "../../../kit/figure/narrow.mjs";
 import { ClassAxis, valueAxis } from "../../../kit/data/index.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
@@ -12,11 +12,12 @@ const r2 = (n) => Math.round(n * 100) / 100;
 /** Written as a book writes it: 0.8, not 0.80. */
 const fmt = (n) => String(Number(n.toFixed(n < 1 ? 2 : 1)));
 function DensityScene({ bars, mode, modal, measure, label, control }) {
-	const W = 560;
-	const left = 60;
-	const right = W - 26;
-	const top = 74;
-	const bottom = 272;
+	const { ref, narrow, width } = useNarrow();
+	const W = narrow ? Math.max(280, Math.min(400, width || 344)) : 560;
+	const left = 50;
+	const right = W - 20;
+	const top = narrow ? 160 : 104;
+	const bottom = top + 220;
 	const H = bottom + 50;
 	const lo = bars[0]?.from ?? 0;
 	const hi = bars.at(-1)?.to ?? 1;
@@ -30,134 +31,138 @@ function DensityScene({ bars, mode, modal, measure, label, control }) {
 		4
 	].map((i) => tallest * i / 4);
 	const density = mode === "density";
-	const keyW = 180;
-	return /* @__PURE__ */ jsxs(Figure, {
-		viewBox: [W, H],
-		domain: "math",
-		interactive: true,
-		label,
-		className: "statistics-density",
-		children: [
-			/* @__PURE__ */ jsx(GripKey, {
-				x: r2(W / 2 - keyW / 2 - 6),
-				y: 20,
-				w: keyW,
-				h: 30,
-				text: "Height = frequency",
-				label: control.options.find((option) => option.value === "frequency")?.label,
-				control,
-				option: "frequency"
-			}),
-			/* @__PURE__ */ jsx(GripKey, {
-				x: r2(W / 2 + keyW / 2 + 6),
-				y: 20,
-				w: keyW,
-				h: 30,
-				text: "Height = frequency ÷ width",
-				label: control.options.find((option) => option.value === "density")?.label,
-				control,
-				option: "density"
-			}),
-			/* @__PURE__ */ jsx("line", {
-				x1: left,
-				y1: top - 8,
-				x2: left,
-				y2: bottom,
-				stroke: HUE.ink,
-				strokeWidth: STROKE.line
-			}),
-			/* @__PURE__ */ jsx(FigText, {
-				x: left,
-				y: r2(top - 16),
-				anchor: "middle",
-				size: "label",
-				caps: false,
-				children: density ? "Frequency density" : "Frequency"
-			}),
-			ticks.map((t) => /* @__PURE__ */ jsxs("g", { children: [
-				/* @__PURE__ */ jsx("line", {
-					x1: left,
-					y1: Y(t),
-					x2: right,
-					y2: Y(t),
-					stroke: alpha(HUE.ink, 8),
-					strokeWidth: STROKE.hair
+	const keyW = 210;
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		children: /* @__PURE__ */ jsxs(Figure, {
+			viewBox: [W, H],
+			composition: "content",
+			domain: "math",
+			interactive: true,
+			label,
+			className: "statistics-density",
+			children: [
+				/* @__PURE__ */ jsx(GripKey, {
+					x: narrow ? W / 2 : r2(W / 2 - keyW / 2 - 8),
+					y: 28,
+					w: keyW,
+					h: 44,
+					text: "Height = frequency",
+					label: control.options.find((option) => option.value === "frequency")?.label,
+					control,
+					option: "frequency"
+				}),
+				/* @__PURE__ */ jsx(GripKey, {
+					x: narrow ? W / 2 : r2(W / 2 + keyW / 2 + 8),
+					y: narrow ? 84 : 28,
+					w: keyW,
+					h: 44,
+					text: "Height = frequency ÷ width",
+					label: control.options.find((option) => option.value === "density")?.label,
+					control,
+					option: "density"
 				}),
 				/* @__PURE__ */ jsx("line", {
-					x1: left - 4,
-					y1: Y(t),
+					x1: left,
+					y1: top - 8,
 					x2: left,
-					y2: Y(t),
-					stroke: HUE.soft,
-					strokeWidth: STROKE.hair
+					y2: bottom,
+					stroke: HUE.ink,
+					strokeWidth: STROKE.line
 				}),
 				/* @__PURE__ */ jsx(FigText, {
-					x: left - 7,
-					y: r2(Y(t) + 3),
-					anchor: "end",
-					size: "note",
-					tone: "soft",
+					x: left,
+					y: r2(top - 22),
+					anchor: "start",
+					size: "label",
 					caps: false,
-					children: fmt(t)
-				})
-			] }, t)),
-			bars.map((bar, i) => {
-				const x0 = axis.X(bar.from);
-				const x1 = axis.X(bar.to);
-				const y = Y(bar.height);
-				const h = bottom - y;
-				const picked = density && i === modal;
-				const ink = picked ? HUE[2] : HUE[1];
-				const slice = bar.frequency > 0 ? h / bar.frequency : 0;
-				return /* @__PURE__ */ jsxs("g", { children: [
-					/* @__PURE__ */ jsx("rect", {
-						x: x0,
-						y,
-						width: r2(x1 - x0),
-						height: r2(h),
-						fill: tint(ink, 30),
-						stroke: ink,
-						strokeWidth: STROKE.line
+					children: density ? "Frequency density" : "Frequency"
+				}),
+				ticks.map((t) => /* @__PURE__ */ jsxs("g", { children: [
+					/* @__PURE__ */ jsx("line", {
+						x1: left,
+						y1: Y(t),
+						x2: right,
+						y2: Y(t),
+						stroke: alpha(HUE.ink, 8),
+						strokeWidth: STROKE.hair
 					}),
-					slice >= 3.5 ? Array.from({ length: bar.frequency - 1 }, (_, k) => /* @__PURE__ */ jsx("line", {
-						x1: x0,
-						y1: r2(bottom - (k + 1) * slice),
-						x2: x1,
-						y2: r2(bottom - (k + 1) * slice),
-						stroke: alpha(ink, 35),
+					/* @__PURE__ */ jsx("line", {
+						x1: left - 4,
+						y1: Y(t),
+						x2: left,
+						y2: Y(t),
+						stroke: HUE.soft,
 						strokeWidth: STROKE.hair
-					}, k)) : null,
-					/* @__PURE__ */ jsx(FigText, {
-						x: r2((x0 + x1) / 2),
-						y: r2(y + h / 2 + 4),
-						anchor: "middle",
-						weight: "semibold",
-						caps: false,
-						halo: true,
-						children: `${bar.frequency}`
 					}),
-					density ? /* @__PURE__ */ jsx(FigText, {
-						x: r2((x0 + x1) / 2),
-						y: r2(y - 6),
-						anchor: "middle",
+					/* @__PURE__ */ jsx(FigText, {
+						x: left - 7,
+						y: r2(Y(t) + 3),
+						anchor: "end",
 						size: "note",
-						color: picked ? HUE[2] : undefined,
 						tone: "soft",
 						caps: false,
-						children: fmt(bar.height)
-					}) : null
-				] }, i);
-			}),
-			/* @__PURE__ */ jsx(ClassAxis, {
-				axis,
-				classes: bars.map((b) => ({
-					from: b.from,
-					to: b.to,
-					count: b.frequency
-				})),
-				label: measure
-			})
-		]
+						children: fmt(t)
+					})
+				] }, t)),
+				bars.map((bar, i) => {
+					const x0 = axis.X(bar.from);
+					const x1 = axis.X(bar.to);
+					const y = Y(bar.height);
+					const h = bottom - y;
+					const picked = density && i === modal;
+					const ink = picked ? HUE[2] : HUE[1];
+					const slice = bar.frequency > 0 ? h / bar.frequency : 0;
+					return /* @__PURE__ */ jsxs("g", { children: [
+						/* @__PURE__ */ jsx("rect", {
+							x: x0,
+							y,
+							width: r2(x1 - x0),
+							height: r2(h),
+							fill: tint(ink, 30),
+							stroke: ink,
+							strokeWidth: STROKE.line
+						}),
+						slice >= 3.5 ? Array.from({ length: bar.frequency - 1 }, (_, k) => /* @__PURE__ */ jsx("line", {
+							x1: x0,
+							y1: r2(bottom - (k + 1) * slice),
+							x2: x1,
+							y2: r2(bottom - (k + 1) * slice),
+							stroke: alpha(ink, 35),
+							strokeWidth: STROKE.hair
+						}, k)) : null,
+						/* @__PURE__ */ jsx(FigText, {
+							x: r2((x0 + x1) / 2),
+							y: r2(y + h / 2 + 4),
+							anchor: "middle",
+							weight: "semibold",
+							caps: false,
+							halo: true,
+							children: `${bar.frequency}`
+						}),
+						density ? /* @__PURE__ */ jsx(FigText, {
+							x: r2((x0 + x1) / 2),
+							y: r2(y - 6),
+							anchor: "middle",
+							size: "note",
+							color: picked ? HUE[2] : undefined,
+							tone: "soft",
+							caps: false,
+							children: fmt(bar.height)
+						}) : null
+					] }, i);
+				}),
+				/* @__PURE__ */ jsx(ClassAxis, {
+					axis,
+					classes: bars.map((b) => ({
+						from: b.from,
+						to: b.to,
+						count: b.frequency
+					})),
+					label: measure
+				})
+			]
+		})
 	});
 }
 

package/dist/domains/statistics/frequency-density/manifest.mjs

@@ -116,7 +116,7 @@ var manifest_default = defineLab({
 			}
 		},
 		{
-			name: "Which class is most crowded? (modal class by density)",
+			name: "Which class has the greatest frequency density?",
 			props: {
 				classes: [
 					{
@@ -194,7 +194,7 @@ var manifest_default = defineLab({
 		objectives: [
 			"Plot frequency density, not frequency, when class widths differ",
 			"Read the frequency of a class as the AREA of its bar",
-			"Identify the modal class from density rather than from the raw count"
+			"Distinguish the greatest frequency density from the greatest frequency"
 		],
 		phases: [
 			"predict",

package/dist/domains/statistics/frequency-density/runtime.mjs

@@ -28,14 +28,15 @@ function FrequencyDensity(props) {
 			] }),
 			/* @__PURE__ */ jsxs("li", { children: ["Class widths: ", reading.bars.map((b) => b.width).join(", ")] }),
 			/* @__PURE__ */ jsxs("li", { children: [
-				"Modal class: ",
+				"Greatest frequency density: ",
 				reading.bars[reading.modal].from,
-				" to ",
+				" to",
+				" ",
 				reading.bars[reading.modal].to,
-				", the greatest density"
+				", the greatest concentration of values per unit of class width"
 			] })
 		] }),
-		observation: ({ reading }) => reading.mode === "density" ? "Every slice now has the same area: one value each. The number inside each bar is its area. The modal class is the one with the greatest density, not the greatest count." : "Look at the slices: a wider class spreads its frequency over more width, so each of its values gets far more area than a value in a narrow class.",
+		observation: ({ reading }) => reading.mode === "density" ? "Every slice now has the same area: one value each. The number inside each bar is its area. The tallest bar has the greatest frequency density: the greatest concentration of values per unit of class width. The greatest frequency may belong to a different class; compare the counts inside the bars." : "Look at the slices: a wider class spreads its frequency over more width, so each of its values gets far more area than a value in a narrow class.",
 		children: /* @__PURE__ */ jsx(FrequencyDensityScene, {})
 	});
 }

package/dist/domains/statistics/galton/model.mjs

@@ -1,128 +1,163 @@
 import { defineLabModel } from "../../../model/define.mjs";
-import { mulberry32 } from "@classytic/stage/rng";
+import { refuse } from "@classytic/stage/result";
 import { z } from "zod";
-import { binomialPmf, binomialStats } from "@classytic/stage/math";
+import { binomialPmf, binomialSampleSummary, binomialStats, sampleBinomialPaths } from "@classytic/stage/math";
 
 //#region src/domains/statistics/galton/model.ts
-/** Simulate dropping `count` balls with a seeded RNG starting from seedOffset. */
-function simulateDrops(rows, seed, offset, count) {
-	const rng = mulberry32(seed + offset & 4294967295);
-	const bins = [];
-	for (let i = 0; i < count; i++) {
-		let rights = 0;
-		for (let r = 0; r < rows; r++) {
-			if (rng() < .5) rights++;
-		}
-		bins.push(rights);
+const MAX_PENDING = 1e3;
+const MAX_FLIGHT = 28;
+const FALL_SECONDS = .75;
+const pending = (state) => state.queued.length + state.inFlight.length;
+const initial = (scenario) => ({
+	counts: new Array(scenario.rows + 1).fill(0),
+	randomState: scenario.seed,
+	nextId: 0,
+	queued: [],
+	inFlight: [],
+	spawnBalance: 0,
+	showCurve: scenario.showCurve,
+	speed: 40,
+	refusal: undefined
+});
+function queueDrops(scenario, state, count) {
+	if (!Number.isInteger(count) || count < 1 || count > MAX_PENDING - pending(state)) return {
+		...state,
+		refusal: refuse("invalid-drop-count", "Request a positive integer batch with at most 1,000 pending balls.")
+	};
+	if (!Number.isSafeInteger(state.nextId + count)) return {
+		...state,
+		refusal: refuse("trial-range", "Restart the experiment before exhausting exact trial identities.")
+	};
+	const sampled = sampleBinomialPaths(scenario.rows, .5, count, state.randomState);
+	if (!sampled.ok) return {
+		...state,
+		refusal: sampled
+	};
+	return {
+		...state,
+		randomState: sampled.value.randomState,
+		nextId: state.nextId + count,
+		queued: [...state.queued, ...sampled.value.paths.map((path, index) => ({
+			id: state.nextId + index,
+			path
+		}))],
+		refusal: undefined
+	};
+}
+/** A timed reveal of already recorded Stage outcomes; no sampling occurs while painting/stepping. */
+function step(_scenario, state, dt) {
+	if (pending(state) === 0 || dt === 0) return state;
+	const balance = state.spawnBalance + state.speed * dt;
+	const launch = Math.min(Math.floor(balance), MAX_FLIGHT - state.inFlight.length, state.queued.length);
+	const flights = [...state.inFlight, ...state.queued.slice(0, launch).map((ball) => ({
+		...ball,
+		progress: 0
+	}))];
+	const counts = [...state.counts];
+	const inFlight = [];
+	for (const ball of flights) {
+		const progress = ball.progress + dt / FALL_SECONDS;
+		if (progress >= 1 - 1e-12) counts[ball.path.successes]++;
+		else inFlight.push({
+			...ball,
+			progress
+		});
 	}
+	const queued = state.queued.slice(launch);
 	return {
-		bins,
-		newOffset: offset + count
+		...state,
+		counts,
+		queued,
+		inFlight,
+		spawnBalance: queued.length ? balance - launch : 0
 	};
 }
 const galtonModel = defineLabModel({
 	id: "galton",
 	params: z.object({
 		rows: z.number().int().min(4).max(16).default(12).describe("Number of peg rows"),
-		seed: z.number().default(7).describe("Random seed for repeatable bounce sequence"),
-		showCurve: z.boolean().default(true).describe("Show theoretical bell curve overlay")
+		seed: z.number().int().min(-2147483648).max(4294967295).default(7).describe("32-bit seed for repeatable bounce sequence"),
+		showCurve: z.boolean().default(true).describe("Show theoretical binomial curve overlay")
 	}),
 	resolve: (p) => {
-		const rows = Math.max(4, Math.min(16, Math.round(p.rows)));
-		const bStats = binomialStats(rows, .5);
-		const theoreticalMean = bStats.ok ? bStats.value.mean : rows / 2;
-		const theoreticalStddev = bStats.ok ? bStats.value.standardDeviation : Math.sqrt(rows) / 2;
+		const stats = binomialStats(p.rows, .5);
+		if (!stats.ok) return stats;
 		const pmf = [];
-		for (let k = 0; k <= rows; k++) {
-			const res = binomialPmf(rows, .5, k);
-			pmf.push(res.ok ? res.value : 0);
+		for (let k = 0; k <= p.rows; k++) {
+			const value = binomialPmf(p.rows, .5, k);
+			if (!value.ok) return value;
+			pmf.push(value.value);
 		}
 		return {
-			rows,
-			seed: p.seed,
+			rows: p.rows,
+			seed: p.seed | 0,
 			showCurve: p.showCurve,
-			theoreticalMean,
-			theoreticalStddev,
+			theoreticalMean: stats.value.mean,
+			theoreticalStddev: stats.value.standardDeviation,
 			pmf
 		};
 	},
-	initial: (scenario) => ({
-		counts: new Array(scenario.rows + 1).fill(0),
-		total: 0,
-		seedOffset: 0,
-		showCurve: scenario.showCurve,
-		speed: 40
+	initial,
+	controls: (c) => ({
+		dropOne: c.action({
+			label: "Drop one ball",
+			enabled: (_s, st) => pending(st) < MAX_PENDING,
+			run: (s, st) => queueDrops(s, st, 1)
+		}),
+		dropBatch: c.action({
+			label: "Drop 100 balls",
+			enabled: (_s, st) => pending(st) <= MAX_PENDING - 100,
+			run: (s, st) => queueDrops(s, st, 100)
+		}),
+		dropThousand: c.action({
+			label: "Drop 1,000",
+			enabled: (_s, st) => pending(st) === 0,
+			run: (s, st) => queueDrops(s, st, 1e3)
+		}),
+		showCurve: c.toggle({
+			label: "binomial curve",
+			get: (st) => st.showCurve,
+			set: (st, value) => ({
+				...st,
+				showCurve: value
+			})
+		}),
+		speed: c.number({
+			label: "speed",
+			unit: "balls/s",
+			step: 10,
+			range: () => [10, 200],
+			get: (st) => st.speed,
+			set: (st, value) => ({
+				...st,
+				speed: value
+			})
+		})
 	}),
 	actions: {
 		drop: (scenario, state, payload) => {
-			const { count = 1 } = payload ?? {};
-			const n = Math.max(1, Math.round(count));
-			const { bins, newOffset } = simulateDrops(scenario.rows, scenario.seed, state.seedOffset, n);
-			const nextCounts = [...state.counts];
-			for (const b of bins) {
-				if (b >= 0 && b < nextCounts.length) {
-					nextCounts[b] = (nextCounts[b] ?? 0) + 1;
-				}
-			}
-			return {
-				...state,
-				counts: nextCounts,
-				total: state.total + n,
-				seedOffset: newOffset
-			};
-		},
-		land: (_scenario, state, payload) => {
-			const { bins = [] } = payload ?? {};
-			if (!bins.length) return state;
-			const nextCounts = [...state.counts];
-			for (const b of bins) {
-				if (b >= 0 && b < nextCounts.length) {
-					nextCounts[b] = (nextCounts[b] ?? 0) + 1;
-				}
-			}
-			return {
-				...state,
-				counts: nextCounts,
-				total: state.total + bins.length
-			};
+			const count = typeof payload === "object" && payload !== null && "count" in payload ? payload.count : 1;
+			return queueDrops(scenario, state, typeof count === "number" ? count : NaN);
 		},
 		reset: (scenario, state) => ({
-			counts: new Array(scenario.rows + 1).fill(0),
-			total: 0,
-			seedOffset: 0,
+			...initial(scenario),
 			showCurve: state.showCurve,
 			speed: state.speed
-		}),
-		"toggle-curve": (_scenario, state) => ({
-			...state,
-			showCurve: !state.showCurve
-		}),
-		"set-speed": (_scenario, state, payload) => {
-			const { speed } = payload ?? {};
-			if (speed == null || speed <= 0) return state;
-			return {
-				...state,
-				speed
-			};
-		}
+		})
 	},
-	read: (scenario, state) => {
-		const total = state.total;
-		let mean = scenario.theoreticalMean;
-		let stddev = scenario.theoreticalStddev;
-		if (total > 0) {
-			let sum = 0;
-			for (let k = 0; k < state.counts.length; k++) {
-				sum += k * (state.counts[k] ?? 0);
-			}
-			mean = sum / total;
-			let ss = 0;
-			for (let k = 0; k < state.counts.length; k++) {
-				ss += (state.counts[k] ?? 0) * (k - mean) ** 2;
-			}
-			stddev = Math.sqrt(ss / total);
-		}
-		const spoken = `${total.toLocaleString()} balls landed; mean bin ${mean.toFixed(2)}, standard deviation ${stddev.toFixed(2)}.`;
+	step,
+	settled: (_scenario, state) => pending(state) === 0,
+	clock: {
+		hz: 120,
+		maxSubSteps: 8,
+		autoplay: true,
+		publishHz: 12
+	},
+	read: (_scenario, state) => {
+		const summary = binomialSampleSummary(state.counts);
+		if (!summary.ok) throw new Error(`Invalid Galton frequency state: ${summary.code}`);
+		const { total, mean, standardDeviation: stddev } = summary.value;
+		const spoken = total ? `${total.toLocaleString()} balls landed; mean bin ${mean.toFixed(2)}, standard deviation ${stddev.toFixed(2)}.` : "No balls have landed; empirical mean and standard deviation are not yet observed.";
 		return {
 			counts: state.counts,
 			total,
@@ -130,24 +165,18 @@ const galtonModel = defineLabModel({
 			stddev,
 			showCurve: state.showCurve,
 			speed: state.speed,
+			pending: pending(state),
+			inFlight: state.inFlight,
+			refusal: state.refusal,
 			solved: total > 0,
 			spoken
 		};
 	},
 	goals: { solved: (r) => r.solved },
 	witness: (scenario) => {
-		const { bins, newOffset } = simulateDrops(scenario.rows, scenario.seed, 0, 100);
-		const counts = new Array(scenario.rows + 1).fill(0);
-		for (const b of bins) {
-			if (b >= 0 && b < counts.length) counts[b]++;
-		}
-		return {
-			counts,
-			total: 100,
-			seedOffset: newOffset,
-			showCurve: scenario.showCurve,
-			speed: 40
-		};
+		let state = queueDrops(scenario, initial(scenario), 100);
+		while (pending(state)) state = step(scenario, state, 1 / 120);
+		return state;
 	},
 	describe: (_scenario, _state, reading) => reading.spoken
 });