@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/threesurfaces/RibbonSurface.js

@@ -0,0 +1,167 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { short } from "./GridSurfaceBase.js";
+import { SurfaceBase } from "./SurfaceBase.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { CEIL, FLOOR } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { extent, group, interpolateBasis, max, min, scaleLinear, scalePoint, scaleUtc, utcFormat } from "d3";
+// src/charts/threesurfaces/RibbonSurface.ts
+var RibbonForm = /* @__PURE__ */ function(RibbonForm) {
+	RibbonForm["Strip"] = "strip";
+	RibbonForm["Curtain"] = "curtain";
+	RibbonForm["Tube"] = "tube";
+	RibbonForm["Slab"] = "slab";
+	return RibbonForm;
+}({});
+var RibbonSmoothing = /* @__PURE__ */ function(RibbonSmoothing) {
+	RibbonSmoothing["None"] = "raw";
+	RibbonSmoothing["Average"] = "moving-average";
+	RibbonSmoothing["Spline"] = "spline";
+	return RibbonSmoothing;
+}({});
+var RibbonLayout = /* @__PURE__ */ function(RibbonLayout) {
+	RibbonLayout["Lanes"] = "lanes";
+	RibbonLayout["Stacked"] = "stacked";
+	RibbonLayout["Rank"] = "rank";
+	return RibbonLayout;
+}({});
+var toNumber = (cell) => cell instanceof Date ? cell.getTime() : cell === null || cell === void 0 || cell === "" ? NaN : +cell;
+/** One ribbon per series, in its own depth lane: for many time series too tangled to share a flat axis. */
+var RibbonSurface = class extends SurfaceBase {
+	static meta = {
+		id: "ribbon-surface",
+		name: "Ribbon surface",
+		family: ChartFamily.Trend,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Lays each series out as a ribbon in depth, as strips, curtains, tubes or slabs, so tangled lines separate.",
+		tags: [
+			"ribbon",
+			"time series",
+			"lanes",
+			"bump"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 72, 6),
+		variants: {
+			form: [
+				"curtain",
+				"strip",
+				"tube",
+				"slab"
+			],
+			smoothing: [
+				"moving-average",
+				"raw",
+				"spline"
+			],
+			layout: [
+				"lanes",
+				"stacked",
+				"rank"
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			x: "date",
+			y: "value",
+			series: "series",
+			form: "curtain",
+			smoothing: "moving-average",
+			layout: "lanes"
+		};
+	}
+	smooth(values) {
+		const { smoothing } = this.options;
+		if (values.length < 4 || smoothing === "raw") return values;
+		if (smoothing === "spline") {
+			const spline = interpolateBasis(values);
+			return values.map((_, k) => spline(k / (values.length - 1)));
+		}
+		return values.map((_, k) => {
+			const window = values.slice(Math.max(0, k - 3), k + 4).filter(Number.isFinite);
+			return window.length ? window.reduce((sum, value) => sum + value, 0) / window.length : NaN;
+		});
+	}
+	build(ctx) {
+		const { data, x, y, series, form, layout } = this.options;
+		const rows = (data ?? []).filter((row) => Number.isFinite(toNumber(row[x])));
+		const lanes = [...group(rows, (row) => String(row[series] ?? "")).entries()].map(([name, list]) => {
+			const sorted = [...list].sort((a, b) => toNumber(a[x]) - toNumber(b[x]));
+			return {
+				name,
+				xs: sorted.map((row) => toNumber(row[x])),
+				raw: sorted,
+				ys: this.smooth(sorted.map((row) => toNumber(row[y])))
+			};
+		}).filter(({ xs }) => xs.length);
+		if (layout === "stacked") {
+			const running = /* @__PURE__ */ new Map();
+			for (const lane of lanes) lane.ys = lane.ys.map((value, k) => {
+				const total = (running.get(lane.xs[k]) ?? 0) + Math.max(0, value || 0);
+				running.set(lane.xs[k], total);
+				return total;
+			});
+		}
+		if (layout === "rank") {
+			const at = /* @__PURE__ */ new Map();
+			lanes.forEach((lane, l) => lane.xs.forEach((time, k) => {
+				if (!at.has(time)) at.set(time, []);
+				at.get(time).push([l, lane.ys[k]]);
+			}));
+			lanes.forEach((lane, l) => {
+				const ranks = lane.xs.map((time) => at.get(time).sort((a, b) => a[1] - b[1]).findIndex(([owner]) => owner === l) + 1);
+				lane.ys = ranks.map((_, k) => ranks.slice(Math.max(0, k - 2), k + 3).reduce((sum, value, _i, list) => sum + value / list.length, 0));
+			});
+		}
+		const [x0 = 0, x1 = 1] = extent(rows, (row) => toNumber(row[x]));
+		const lowest = layout === "stacked" || layout === "rank" ? 0 : Math.min(0, min(lanes, (lane) => min(lane.ys)) ?? 0);
+		const highest = max(lanes, (lane) => max(lane.ys)) ?? 1;
+		const sx = scaleLinear([x0, x1 > x0 ? x1 : x0 + 1], [-1, 1]);
+		const sz = scalePoint(lanes.map((lane) => lane.name), [.86, -.86]).padding(.1);
+		const sy = scaleLinear([lowest, highest > lowest ? highest : lowest + 1], [FLOOR, CEIL]);
+		const lane = lanes.length > 1 ? sz.step() || .4 : .4;
+		const timed = rows[0]?.[x] instanceof Date;
+		const time = scaleUtc([x0, x1], [-1, 1]);
+		const xTicks = timed ? time.ticks(4).map((d) => [time(d), utcFormat("%b %-d")(d)]) : this.ticks([x0, x1 > x0 ? x1 : x0 + 1], sx);
+		const yTicks = lanes.map(({ name }) => [sz(name) ?? 0, name]);
+		this.box(ctx, {
+			x: xTicks,
+			y: yTicks.length > 8 ? yTicks.filter((_, k) => k % 2 === 0) : yTicks,
+			z: this.ticks(sy.domain(), sy, 3)
+		});
+		const lift = this.rise(ctx);
+		lanes.forEach(({ name, xs, ys, raw }) => {
+			const color = ctx.color(ctx.palette.color(name)), deep = color.clone().lerp(ctx.color(ctx.theme.surface), .45), z = sz(name) ?? 0;
+			const top = xs.map((value, k) => [
+				sx(value),
+				Number.isFinite(ys[k]) ? sy(ys[k]) : NaN,
+				z
+			]);
+			const tip = (k) => {
+				const i = Math.min(raw.length - 1, k % raw.length);
+				return {
+					title: name,
+					color: ctx.palette.color(name),
+					rows: [[y, short(toNumber(raw[i][y]))]]
+				};
+			};
+			if (form === "tube") return void this.tubes(new TubeBatch(.017, 7).add(top, color), lift);
+			if (form === "curtain") {
+				this.solid(ctx, SurfaceGeometry.curtain(top, FLOOR, () => color, () => deep), lift, tip);
+				this.tubes(new TubeBatch(.0075).add(top, color), lift);
+				return;
+			}
+			const width = lane * .62;
+			if (form === "slab") return void this.solid(ctx, SurfaceGeometry.slab(top, [0, width], FLOOR, () => color, () => deep), lift, tip);
+			this.solid(ctx, SurfaceGeometry.grid(top.length, 2, (k, side) => [
+				top[k][0],
+				top[k][1],
+				z + (side - .5) * width
+			], () => color), lift, tip);
+		});
+	}
+};
+export { RibbonForm, RibbonLayout, RibbonSmoothing, RibbonSurface };

package/dist/charts/threesurfaces/Ridgeline3DChart.js

@@ -0,0 +1,166 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { short } from "./GridSurfaceBase.js";
+import { SurfaceBase } from "./SurfaceBase.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { CEIL, FLOOR } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { bin, deviation, extent, group, max, mean, scaleLinear, scalePoint } from "d3";
+// src/charts/threesurfaces/Ridgeline3DChart.ts
+var Ridge3DProfile = /* @__PURE__ */ function(Ridge3DProfile) {
+	Ridge3DProfile["Kernel"] = "kernel";
+	Ridge3DProfile["Histogram"] = "histogram";
+	return Ridge3DProfile;
+}({});
+var Ridge3DMark = /* @__PURE__ */ function(Ridge3DMark) {
+	Ridge3DMark["Fin"] = "fin";
+	Ridge3DMark["Tube"] = "tube";
+	Ridge3DMark["Slab"] = "slab";
+	Ridge3DMark["Terrain"] = "terrain";
+	return Ridge3DMark;
+}({});
+var Ridge3DScaling = /* @__PURE__ */ function(Ridge3DScaling) {
+	Ridge3DScaling["Peak"] = "peak";
+	Ridge3DScaling["Area"] = "area";
+	return Ridge3DScaling;
+}({});
+var Ridge3DOrder = /* @__PURE__ */ function(Ridge3DOrder) {
+	Ridge3DOrder["Given"] = "given";
+	Ridge3DOrder["Mean"] = "by-mean";
+	return Ridge3DOrder;
+}({});
+/** Distributions as a physical mountain range: for comparing the shape of many groups at once. */
+var Ridgeline3DChart = class extends SurfaceBase {
+	static meta = {
+		id: "ridgeline-3d",
+		name: "3D ridgeline",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Places one density profile per group along the depth axis, so shifts in shape and spread read as a range of ridges.",
+		tags: [
+			"joyplot",
+			"ridgeline",
+			"density",
+			"kde",
+			"histogram"
+		],
+		sample: (seed) => SampleData.distribution(seed, 180, 7),
+		variants: {
+			profile: ["kernel", "histogram"],
+			mark: [
+				"slab",
+				"fin",
+				"tube",
+				"terrain"
+			],
+			scaling: ["area", "peak"],
+			order: ["given", "by-mean"],
+			rug: [false, true]
+		},
+		valid: ({ mark, rug }) => !(mark === "terrain" && rug)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			group: "group",
+			value: "value",
+			profile: "kernel",
+			mark: "slab",
+			scaling: "area",
+			order: "given",
+			rug: false,
+			smoothing: 1,
+			azimuth: 28,
+			elevation: 24
+		};
+	}
+	/** `[x, density]` pairs on shared x positions. */
+	density(values, [lo, hi]) {
+		if (this.options.profile === "histogram") return bin().domain([lo, hi]).thresholds(24)(values).flatMap((b) => {
+			const height = values.length && b.x1 > b.x0 ? b.length / values.length / (b.x1 - b.x0) : 0;
+			return [[b.x0, height], [b.x1, height]];
+		});
+		const bandwidth = this.options.smoothing * Math.max(1.06 * (deviation(values) ?? (hi - lo) / 10) * values.length ** -.2, (hi - lo) / 200);
+		return Array.from({ length: 72 }, (_, k) => {
+			const x = lo + (hi - lo) * k / 71;
+			return [x, values.reduce((total, value) => total + Math.exp(-(((x - value) / bandwidth) ** 2) / 2), 0) / (values.length * bandwidth * Math.sqrt(2 * Math.PI))];
+		});
+	}
+	build(ctx) {
+		const { data, group: key, value, mark, scaling, order, rug } = this.options;
+		const clean = (data ?? []).map((row) => ({
+			name: String(row[key] ?? ""),
+			value: +(row[value] ?? NaN)
+		})).filter((row) => Number.isFinite(row.value));
+		const groups = [...group(clean, (row) => row.name)].map(([name, rows]) => ({
+			name,
+			values: rows.map((row) => row.value)
+		}));
+		if (order === "by-mean") groups.sort((a, b) => (mean(b.values) ?? 0) - (mean(a.values) ?? 0));
+		const [a = 0, b = 1] = extent(clean, (row) => row.value), pad = (b - a || 1) * .08;
+		const domain = [a - pad, b + pad];
+		const sx = scaleLinear(domain, [-1, 1]);
+		const sz = scalePoint(groups.map(({ name }) => name), [-.85, .85]).padding(.1);
+		const curves = groups.map(({ name, values }) => ({
+			name,
+			values,
+			curve: this.density(values, domain)
+		}));
+		const overall = max(curves, ({ curve }) => max(curve, ([, y]) => y)) ?? 1;
+		const height = (peak) => scaling === "peak" ? (CEIL - FLOOR) * .85 / (peak || 1) : (CEIL - FLOOR) * .85 / (overall || 1);
+		this.box(ctx, {
+			x: this.ticks(domain, sx),
+			y: curves.map(({ name }) => [sz(name) ?? 0, name]),
+			z: []
+		});
+		const lift = this.rise(ctx);
+		const depth = (curves.length > 1 ? sz.step() : .3) * .46;
+		if (mark === "terrain" && curves.length > 1) {
+			const across = curves[0].curve.length, top = height(overall);
+			const place = (i, j) => [
+				sx(curves[j].curve[i][0]),
+				FLOOR + curves[j].curve[i][1] * height(max(curves[j].curve, ([, y]) => y) ?? 1),
+				sz(curves[j].name) ?? 0
+			];
+			const paint = (i, j) => ctx.color(ctx.palette.sequential(.15 + .85 * Math.min(1, curves[j].curve[i][1] * top / (CEIL - FLOOR))));
+			this.solid(ctx, SurfaceGeometry.grid(across, curves.length, place, paint), lift, () => ({
+				title: this.meta.name,
+				rows: [["Groups", curves.length]]
+			}));
+			return;
+		}
+		curves.forEach(({ name, values, curve }) => {
+			const peak = max(curve, ([, y]) => y) ?? 1, scale = height(peak), z = sz(name) ?? 0;
+			const color = ctx.color(ctx.palette.color(name)), pale = color.clone().lerp(ctx.color(ctx.theme.surface), .5);
+			const kept = curve.filter(([, y], k) => Math.max(y, curve[k - 1]?.[1] ?? 0, curve[k + 1]?.[1] ?? 0) * scale > .004);
+			const top = (kept.length > 1 ? kept : curve).map(([x, y]) => [
+				sx(x),
+				FLOOR + y * scale,
+				z
+			]);
+			const tip = () => ({
+				title: name,
+				color: ctx.palette.color(name),
+				rows: [["n", values.length], ["mean", short(mean(values) ?? 0)]]
+			});
+			if (mark === "slab" || mark === "terrain") this.solid(ctx, SurfaceGeometry.slab(top, [0, depth], FLOOR, () => color, () => pale), lift, tip);
+			if (mark === "fin") this.solid(ctx, SurfaceGeometry.curtain(top, FLOOR, () => color, () => pale), lift, tip);
+			if (mark !== "slab") this.tubes(new TubeBatch(mark === "tube" ? .014 : .0075, 6).add(top, color), lift);
+			if (rug) {
+				const ticks = new TubeBatch(.0035, 4), front = z + (mark === "slab" ? depth / 2 + .006 : .006);
+				for (const v of values.slice(0, 90)) ticks.add([[
+					sx(v),
+					FLOOR + .002,
+					front
+				], [
+					sx(v),
+					FLOOR + .05,
+					front
+				]], color);
+				this.tubes(ticks, lift);
+			}
+		});
+	}
+};
+export { Ridge3DMark, Ridge3DOrder, Ridge3DProfile, Ridge3DScaling, Ridgeline3DChart };

package/dist/charts/threesurfaces/SaddleSurface.js

@@ -0,0 +1,214 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GridSurfaceBase, short } from "./GridSurfaceBase.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { CEIL, FLOOR, SurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { scaleLinear } from "d3";
+// src/charts/threesurfaces/SaddleSurface.ts
+var SaddleModel = /* @__PURE__ */ function(SaddleModel) {
+	SaddleModel["Quadratic"] = "quadratic";
+	SaddleModel["Bilinear"] = "bilinear";
+	SaddleModel["Cubic"] = "cubic";
+	return SaddleModel;
+}({});
+var SaddleFootprint = /* @__PURE__ */ function(SaddleFootprint) {
+	SaddleFootprint["Square"] = "square";
+	SaddleFootprint["Disc"] = "disc";
+	return SaddleFootprint;
+}({});
+var TERMS = {
+	["bilinear"]: [
+		[0, 0],
+		[1, 0],
+		[0, 1],
+		[1, 1]
+	],
+	["quadratic"]: [
+		[0, 0],
+		[1, 0],
+		[0, 1],
+		[2, 0],
+		[1, 1],
+		[0, 2]
+	],
+	["cubic"]: [
+		[0, 0],
+		[1, 0],
+		[0, 1],
+		[2, 0],
+		[1, 1],
+		[0, 2],
+		[3, 0],
+		[2, 1],
+		[1, 2],
+		[0, 3]
+	]
+};
+/** Gauss-Jordan with partial pivoting; a singular column solves to zero. */
+function solve(a, b) {
+	const n = b.length, m = a.map((row, i) => [...row, b[i]]);
+	for (let c = 0; c < n; c++) {
+		let pivot = c;
+		for (let r = c + 1; r < n; r++) if (Math.abs(m[r][c]) > Math.abs(m[pivot][c])) pivot = r;
+		[m[c], m[pivot]] = [m[pivot], m[c]];
+		if (Math.abs(m[c][c]) < 1e-12) continue;
+		for (let r = 0; r < n; r++) {
+			if (r === c) continue;
+			const scale = m[r][c] / m[c][c];
+			for (let k = c; k <= n; k++) m[r][k] -= scale * m[c][k];
+		}
+	}
+	return m.map((row, i) => Math.abs(row[i]) < 1e-12 ? 0 : row[n] / row[i]);
+}
+/** Observed grid bent toward a saddle, with the wave left in as measurement noise. */
+var saddleSample = (seed) => {
+	const grid = SampleData.surface(seed, 13);
+	return {
+		...grid,
+		z: grid.z.map((row, j) => row.map((value, i) => .9 * (grid.x[i] ** 2 - grid.y[j] ** 2) + .28 * grid.x[i] * grid.y[j] + .16 * value))
+	};
+};
+/** Response surface fitted by least squares: for locating and classifying the stationary point of an experiment. */
+var SaddleSurface = class extends GridSurfaceBase {
+	static meta = {
+		id: "saddle-surface",
+		name: "Saddle surface",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Three,
+		shape: DataShape.Grid,
+		description: "Fits a polynomial response surface to observations, marks the stationary point and shows the directions of steepest curvature.",
+		tags: [
+			"saddle",
+			"response surface",
+			"hyperbolic paraboloid",
+			"rsm",
+			"regression"
+		],
+		sample: saddleSample,
+		variants: {
+			model: [
+				"quadratic",
+				"bilinear",
+				"cubic"
+			],
+			principalAxes: [true, false],
+			residuals: [true, false],
+			footprint: ["square", "disc"]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			model: "quadratic",
+			principalAxes: true,
+			residuals: true,
+			footprint: "square"
+		};
+	}
+	build(ctx) {
+		const { model, principalAxes, residuals, footprint } = this.options;
+		const data = this.field(40);
+		const terms = TERMS[model];
+		const toX = (x) => data.xDomain[1] > data.xDomain[0] ? (x - data.xDomain[0]) / (data.xDomain[1] - data.xDomain[0]) * 2 - 1 : 0;
+		const toY = (y) => data.yDomain[1] > data.yDomain[0] ? (y - data.yDomain[0]) / (data.yDomain[1] - data.yDomain[0]) * 2 - 1 : 0;
+		const basis = (x, y) => terms.map(([a, b]) => x ** a * y ** b);
+		const normal = terms.map(() => terms.map(() => 0)), target = terms.map(() => 0);
+		let observations = 0;
+		for (let j = 0; j < data.ny; j++) for (let i = 0; i < data.nx; i++) {
+			const z = data.at(i, j);
+			if (Number.isNaN(z)) continue;
+			observations++;
+			const row = basis(toX(data.x[i]), toY(data.y[j]));
+			row.forEach((a, r) => {
+				target[r] += a * z;
+				row.forEach((b, c) => {
+					normal[r][c] += a * b;
+				});
+			});
+		}
+		const fit = observations ? solve(normal, target) : terms.map(() => 0);
+		const predict = (x, y) => terms.reduce((sum, [a, b], k) => sum + fit[k] * x ** a * y ** b, 0);
+		const n = 64, grid = Array.from({ length: n }, (_, k) => k / 63 * 2 - 1);
+		const disc = footprint === "disc";
+		/** Elliptical square-to-disc map, so a disc footprint gets a smooth rim rather than a staircase of clipped cells. */
+		const footprintAt = (u, v) => disc ? [u * Math.sqrt(1 - v * v / 2), v * Math.sqrt(1 - u * u / 2)] : [u, v];
+		const heights = grid.flatMap((v) => grid.map((u) => predict(...footprintAt(u, v))));
+		const domain = observations ? [Math.min(...heights, data.zDomain[0]), Math.max(...heights, data.zDomain[1])] : data.zDomain;
+		const level = scaleLinear(domain, [FLOOR, CEIL]);
+		const paint = this.painter(ctx, domain);
+		const world = (x, y, z = predict(x, y)) => [
+			x,
+			level(z),
+			-y
+		];
+		this.box(ctx, {
+			...this.axes(new SurfaceSpace(data)),
+			z: this.ticks(domain, level, 3)
+		});
+		const lift = this.rise(ctx);
+		this.solid(ctx, SurfaceGeometry.grid(n, n, (i, j) => observations ? world(...footprintAt(grid[i], grid[j])) : [
+			NaN,
+			NaN,
+			NaN
+		], (i, j) => paint(heights[i + j * n])), lift, (k) => ({ rows: [["fitted", short(heights[k])]] }));
+		if (!observations) return;
+		if (residuals) {
+			const stems = new TubeBatch(.0028), points = [], gaps = [];
+			for (let j = 0; j < data.ny; j++) for (let i = 0; i < data.nx; i++) {
+				const z = data.at(i, j), x = toX(data.x[i]), y = toY(data.y[j]);
+				if (Number.isNaN(z) || disc && Math.hypot(x, y) > 1) continue;
+				const off = world(x, y, z);
+				stems.add([world(x, y), off]);
+				points.push(off);
+				gaps.push(z - predict(x, y));
+			}
+			this.tubes(stems, lift, ctx.theme.inkMuted);
+			this.dots(ctx, points, .016, () => ctx.color(ctx.theme.ink), lift, (k) => ({ rows: [["residual", short(gaps[k])]] }));
+		}
+		if (principalAxes) this.critical(ctx, predict, world, lift, disc);
+	}
+	/** Newton from the centre to the stationary point, then the Hessian's eigenvectors give the principal directions. */
+	critical(ctx, f, world, lift, disc) {
+		const e = .001;
+		const hessian = (x, y) => ({
+			xx: (f(x + e, y) - 2 * f(x, y) + f(x - e, y)) / e ** 2,
+			yy: (f(x, y + e) - 2 * f(x, y) + f(x, y - e)) / e ** 2,
+			xy: (f(x + e, y + e) - f(x + e, y - e) - f(x - e, y + e) + f(x - e, y - e)) / (4 * e ** 2)
+		});
+		let x = 0, y = 0;
+		for (let step = 0; step < 12; step++) {
+			const gx = (f(x + e, y) - f(x - e, y)) / (2 * e), gy = (f(x, y + e) - f(x, y - e)) / (2 * e);
+			const { xx, yy, xy } = hessian(x, y), det = xx * yy - xy * xy;
+			if (Math.abs(det) < 1e-9) break;
+			x = Math.max(-.9, Math.min(.9, x - (yy * gx - xy * gy) / det));
+			y = Math.max(-.9, Math.min(.9, y - (xx * gy - xy * gx) / det));
+		}
+		const { xx, yy, xy } = hessian(x, y);
+		const angle = .5 * Math.atan2(2 * xy, xx - yy), mean = (xx + yy) / 2, spread = Math.hypot((xx - yy) / 2, xy);
+		const curvatures = [mean + spread, mean - spread];
+		const limit = (px, py) => Math.abs(px) <= 1 && Math.abs(py) <= 1 && (!disc || Math.hypot(px, py) <= 1);
+		const batch = new TubeBatch(.011, 6);
+		curvatures.forEach((curvature, k) => {
+			const dir = angle + k * Math.PI / 2, path = [];
+			for (let t = -2.8; t <= 2.8; t += .04) {
+				const px = x + Math.cos(dir) * t, py = y + Math.sin(dir) * t;
+				if (limit(px, py)) path.push(world(px, py));
+			}
+			batch.add(path, ctx.color(ctx.palette.diverging(Math.sign(curvature) || 1)));
+		});
+		this.tubes(batch, lift);
+		const centre = world(x, y);
+		const kind = curvatures[0] * curvatures[1] < 0 ? "Saddle point" : curvatures[0] < 0 ? "Maximum" : "Minimum";
+		this.dots(ctx, [centre], .03, () => ctx.color(ctx.theme.ink), lift, () => ({
+			title: kind,
+			rows: [["value", short(f(x, y))]]
+		}));
+		ctx.label(kind, [
+			centre[0],
+			Math.min(centre[1] + .5, 1),
+			centre[2]
+		], "ink", 11);
+	}
+};
+export { SaddleFootprint, SaddleModel, SaddleSurface };

package/dist/charts/threesurfaces/ShortTimeTransform.js

@@ -0,0 +1,53 @@
+import { SampleData } from "../../data/SampleData.js";
+// src/charts/threesurfaces/ShortTimeTransform.ts
+var SpectrogramWindow = /* @__PURE__ */ function(SpectrogramWindow) {
+	SpectrogramWindow["Hann"] = "hann";
+	SpectrogramWindow["Hamming"] = "hamming";
+	SpectrogramWindow["Blackman"] = "blackman";
+	SpectrogramWindow["Rectangular"] = "rectangular";
+	return SpectrogramWindow;
+}({});
+var WINDOWS = {
+	["hann"]: (t) => .5 - .5 * Math.cos(2 * Math.PI * t),
+	["hamming"]: (t) => .54 - .46 * Math.cos(2 * Math.PI * t),
+	["blackman"]: (t) => .42 - .5 * Math.cos(2 * Math.PI * t) + .08 * Math.cos(4 * Math.PI * t),
+	["rectangular"]: () => 1
+};
+/** Short-time Fourier transform. Plain DFT: window sizes here are small and it spares a dependency. */
+var ShortTimeTransform = class {
+	/** Magnitudes as a grid: `x` is frequency in cycles per sample, `y` the start sample of each frame. */
+	static spectrogram(signal, size, hop, window) {
+		const clean = signal.map((value) => Number.isFinite(value) ? value : 0);
+		const mean = clean.reduce((sum, value) => sum + value, 0) / (clean.length || 1);
+		const shape = Array.from({ length: size }, (_, k) => WINDOWS[window](k / Math.max(1, size - 1)));
+		const bins = Math.floor(size / 2) + 1;
+		const cosines = Array.from({ length: bins * size }, (_, k) => Math.cos(-2 * Math.PI * Math.floor(k / size) * (k % size) / size));
+		const sines = Array.from({ length: bins * size }, (_, k) => Math.sin(-2 * Math.PI * Math.floor(k / size) * (k % size) / size));
+		const starts = Array.from({ length: Math.max(1, Math.floor((clean.length - size) / hop) + 1) }, (_, k) => k * hop);
+		const z = starts.map((start) => Array.from({ length: bins }, (_, bin) => {
+			let re = 0, im = 0;
+			for (let n = 0; n < size; n++) {
+				const value = ((clean[start + n] ?? mean) - mean) * shape[n];
+				re += value * cosines[bin * size + n];
+				im += value * sines[bin * size + n];
+			}
+			return 2 * Math.hypot(re, im) / size;
+		}));
+		return {
+			x: Array.from({ length: bins }, (_, k) => k / size),
+			y: starts,
+			z
+		};
+	}
+	/** The sample walk carrying a rising chirp and a steady tone, so its spectrum has something to show. */
+	static sampleSignal(seed, points = 600) {
+		return SampleData.timeSeries(seed, points, 1).map((row, t) => {
+			const u = t / points, chirp = Math.sin(2 * Math.PI * (.05 * t + .185 * t * u)), tone = .6 * Math.sin(2 * Math.PI * .09 * t) * (u < .65 ? 1 : .15);
+			return {
+				...row,
+				value: +(chirp * (.5 + .5 * Math.sin(u * 9) ** 2) + tone + row.value * .002).toFixed(4)
+			};
+		});
+	}
+};
+export { ShortTimeTransform, SpectrogramWindow };