@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/scatter/Regression.js

@@ -0,0 +1,157 @@
+import { extent, mean, sum } from "d3";
+// src/charts/scatter/Regression.ts
+var RegressionMethod = /* @__PURE__ */ function(RegressionMethod) {
+	RegressionMethod["Linear"] = "linear";
+	RegressionMethod["Quadratic"] = "quadratic";
+	RegressionMethod["Cubic"] = "cubic";
+	RegressionMethod["Loess"] = "loess";
+	RegressionMethod["Exponential"] = "exponential";
+	RegressionMethod["Logarithmic"] = "logarithmic";
+	RegressionMethod["Power"] = "power";
+	return RegressionMethod;
+}({});
+var STEPS = 64;
+/** Student t critical value at 95%, by Cornish-Fisher expansion of the normal quantile. */
+var critical = (df) => {
+	const z = 1.96;
+	return z + (z ** 3 + z) / (4 * df) + (5 * z ** 5 + 16 * z ** 3 + 3 * z) / (96 * df ** 2);
+};
+function solve(matrix, vector) {
+	const n = vector.length, a = matrix.map((row, i) => [...row, vector[i]]);
+	for (let col = 0; col < n; col++) {
+		let pivot = col;
+		for (let row = col + 1; row < n; row++) if (Math.abs(a[row][col]) > Math.abs(a[pivot][col])) pivot = row;
+		if (Math.abs(a[pivot][col]) < 1e-12) return null;
+		[a[col], a[pivot]] = [a[pivot], a[col]];
+		for (let row = 0; row < n; row++) {
+			if (row === col) continue;
+			const factor = a[row][col] / a[col][col];
+			for (let k = col; k <= n; k++) a[row][k] = a[row][k] - factor * a[col][k];
+		}
+	}
+	return a.map((row, i) => row[n] / row[i]);
+}
+function invert(matrix) {
+	const columns = matrix.map((_, i) => solve(matrix, matrix.map((__, j) => +(i === j))));
+	if (columns.some((column) => !column)) return null;
+	return matrix.map((_, r) => columns.map((column) => column[r]));
+}
+var cross = (rows, weights) => rows[0].map((_, a) => rows[0].map((__, b) => sum(rows, (row, i) => row[a] * row[b] * (weights?.[i] ?? 1))));
+var dot = (a, b) => sum(a, (value, i) => value * b[i]);
+/** Least-squares and local fits with 95% confidence and prediction bands. */
+var Regression = class Regression {
+	static fit(input, method, span = .65) {
+		return method === "loess" ? Regression.loess(input, span) : Regression.parametric(input, method);
+	}
+	static parametric(input, method) {
+		const logX = method === "logarithmic" || method === "power";
+		const logY = method === "exponential" || method === "power";
+		const clean = input.filter((d) => (!logX || d.x > 0) && (!logY || d.y > 0));
+		const degree = method === "cubic" ? 3 : method === "quadratic" ? 2 : 1;
+		if (clean.length < degree + 2) return null;
+		const [low, high] = extent(clean, (d) => d.x);
+		if (low === high) return null;
+		const center = mean(clean, (d) => d.x), width = (high - low) / 2;
+		const u = (x) => logX ? Math.log(x) : (x - center) / width;
+		const basis = (x) => Array.from({ length: degree + 1 }, (_, power) => u(x) ** power);
+		const target = (y) => logY ? Math.log(y) : y;
+		const back = (v) => logY ? Math.exp(v) : v;
+		const X = clean.map((d) => basis(d.x)), Y = clean.map((d) => target(d.y));
+		const inverse = invert(cross(X));
+		if (!inverse) return null;
+		const coefficient = inverse.map((row) => sum(row, (value, i) => value * sum(X, (r, k) => r[i] * Y[k])));
+		const rss = sum(X, (row, i) => (Y[i] - dot(row, coefficient)) ** 2);
+		const df = Math.max(1, clean.length - degree - 1), sigma2 = rss / df, t = critical(df);
+		const curve = Regression.grid(low, high).map((x) => {
+			const row = basis(x), fit = dot(row, coefficient);
+			const leverage = dot(row, inverse.map((line) => dot(line, row)));
+			const se = Math.sqrt(sigma2 * leverage), sp = Math.sqrt(sigma2 * (1 + leverage));
+			return {
+				x,
+				fit: back(fit),
+				low: back(fit - t * se),
+				high: back(fit + t * se),
+				predictLow: back(fit - t * sp),
+				predictHigh: back(fit + t * sp)
+			};
+		});
+		const average = mean(Y);
+		const total = sum(Y, (y) => (y - average) ** 2);
+		return {
+			curve,
+			r2: total ? 1 - rss / total : 0,
+			equation: Regression.equation(method, coefficient, center, width),
+			count: clean.length
+		};
+	}
+	static loess(input, span) {
+		const sorted = [...input].sort((a, b) => a.x - b.x), n = sorted.length;
+		if (n < 4) return null;
+		const low = sorted[0].x, high = sorted[n - 1].x;
+		if (low === high) return null;
+		const reach = Math.max(4, Math.ceil(span * n));
+		const local = (at) => {
+			const near = sorted.map((d) => Math.abs(d.x - at)).sort((a, b) => a - b);
+			const h = Math.max(near[reach - 1], (high - low) * .001);
+			const weights = sorted.map((d) => Math.max(0, 1 - (Math.abs(d.x - at) / h) ** 3) ** 3);
+			const X = sorted.map((d) => [1, (d.x - at) / (high - low)]);
+			const inverse = invert(cross(X, weights));
+			if (!inverse) return null;
+			const hat = sorted.map((_, i) => weights[i] * dot(inverse[0], X[i]));
+			return {
+				fit: sum(hat, (w, i) => w * sorted[i].y),
+				hat
+			};
+		};
+		const fits = sorted.map((d) => local(d.x)?.fit ?? d.y);
+		const rss = sum(sorted, (d, i) => (d.y - fits[i]) ** 2);
+		const df = Math.max(1, n - 2 / span), sigma2 = rss / df, t = critical(df);
+		const curve = Regression.grid(low, high).flatMap((x) => {
+			const part = local(x);
+			if (!part) return [];
+			const leverage = sum(part.hat, (w) => w * w);
+			const se = Math.sqrt(sigma2 * leverage), sp = Math.sqrt(sigma2 * (1 + leverage));
+			return [{
+				x,
+				fit: part.fit,
+				low: part.fit - t * se,
+				high: part.fit + t * se,
+				predictLow: part.fit - t * sp,
+				predictHigh: part.fit + t * sp
+			}];
+		});
+		const average = mean(sorted, (d) => d.y);
+		const total = sum(sorted, (d) => (d.y - average) ** 2);
+		return {
+			curve,
+			r2: total ? 1 - rss / total : 0,
+			equation: `loess, span ${span}`,
+			count: n
+		};
+	}
+	/** Fitted y at any x, for residuals. */
+	static at(result, x) {
+		const { curve } = result;
+		const after = curve.findIndex((point) => point.x >= x);
+		if (after <= 0) return curve[Math.max(0, after)]?.fit ?? 0;
+		const a = curve[after - 1], b = curve[after];
+		return a.fit + (b.fit - a.fit) * (x - a.x) / (b.x - a.x || 1);
+	}
+	static grid(low, high) {
+		return Array.from({ length: 65 }, (_, i) => low + (high - low) * i / STEPS);
+	}
+	static equation(method, c, center, width) {
+		const n = (value) => +value.toPrecision(3);
+		switch (method) {
+			case "linear": {
+				const m = c[1] / width;
+				return `y = ${n(m)}x ${c[0] - m * center < 0 ? "-" : "+"} ${Math.abs(n(c[0] - m * center))}`;
+			}
+			case "logarithmic": return `y = ${n(c[0])} + ${n(c[1])} ln x`;
+			case "power": return `y = ${n(Math.exp(c[0]))} x^${n(c[1])}`;
+			case "exponential": return `y = ${n(Math.exp(c[0] - c[1] / width * center))} e^${n(c[1] / width)}x`;
+			default: return method === "quadratic" ? "quadratic fit" : "cubic fit";
+		}
+	}
+};
+export { Regression, RegressionMethod };

package/dist/charts/scatter/RegressionScatter.js

@@ -0,0 +1,142 @@
+import { ChartFamily, CurveKind, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { Regression, RegressionMethod } from "./Regression.js";
+import { ScatterBase } from "./ScatterBase.js";
+import { area, group, line } from "d3";
+// src/charts/scatter/RegressionScatter.ts
+var RegressionBand = /* @__PURE__ */ function(RegressionBand) {
+	RegressionBand["None"] = "no-band";
+	RegressionBand["Confidence"] = "confidence";
+	RegressionBand["Prediction"] = "prediction";
+	return RegressionBand;
+}({});
+var RegressionScope = /* @__PURE__ */ function(RegressionScope) {
+	RegressionScope["Overall"] = "overall";
+	RegressionScope["PerGroup"] = "per-group";
+	return RegressionScope;
+}({});
+/** Scatter with a fitted trend: linear, polynomial, transformed or loess, with uncertainty bands. */
+var RegressionScatter = class extends ScatterBase {
+	static meta = {
+		id: "regression-scatter",
+		name: "Regression scatter",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Fits a trend through a scatter plot and shows how much of the relationship it explains.",
+		tags: [
+			"trend line",
+			"loess",
+			"polynomial",
+			"least squares"
+		],
+		sample: (seed) => SampleData.points(seed, 90, 2),
+		variants: {
+			method: [
+				RegressionMethod.Linear,
+				RegressionMethod.Quadratic,
+				RegressionMethod.Cubic,
+				RegressionMethod.Loess,
+				RegressionMethod.Exponential,
+				RegressionMethod.Logarithmic,
+				RegressionMethod.Power
+			],
+			band: [
+				"confidence",
+				"prediction",
+				"no-band"
+			],
+			scope: ["overall", "per-group"],
+			residuals: [false, true]
+		},
+		valid: (v) => !(v.residuals && v.scope === "per-group" && v.band === "prediction")
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			method: RegressionMethod.Linear,
+			band: "confidence",
+			scope: "overall",
+			residuals: false,
+			span: .65,
+			summary: true
+		};
+	}
+	fits(points) {
+		const { method, span, scope } = this.options;
+		return (scope === "per-group" ? [...group(points, (point) => point.group)] : [["Overall", points]]).flatMap(([key, set]) => {
+			const result = Regression.fit(set, method, span);
+			return result ? [{
+				key,
+				result
+			}] : [];
+		});
+	}
+	bounds(point) {
+		const { band } = this.options;
+		if (band === "prediction") return [point.predictLow, point.predictHigh];
+		return band === "confidence" ? [point.low, point.high] : [point.fit, point.fit];
+	}
+	yValues(points) {
+		const fitted = this.fits(points).flatMap((fit) => fit.result.curve.flatMap((point) => [point.fit, ...this.bounds(point)]));
+		return [...super.yValues(points), ...fitted.filter(Number.isFinite)];
+	}
+	plotPoints(ctx, axes, points) {
+		const fits = this.fits(points), perGroup = this.options.scope === "per-group";
+		const ink = (fit) => perGroup ? ctx.palette.color(fit.key) : ctx.theme.ink;
+		const clamp = (value) => {
+			const [lo, hi] = [...axes.y.range()].sort((a, b) => a - b);
+			return Math.min(hi, Math.max(lo, value));
+		};
+		const X = (d) => axes.x(d.x);
+		const shaded = this.options.band === "no-band" ? [] : fits;
+		const bands = ctx.marks("bands", "path", shaded, (fit) => fit.key).attr("fill", ink).attr("fill-opacity", .12).attr("stroke", "none");
+		ctx.set(bands, { d: (fit) => area().x(X).y0((d) => clamp(axes.y(this.bounds(d)[0]))).y1((d) => clamp(axes.y(this.bounds(d)[1]))).curve(Scales.curve(CurveKind.Monotone))(fit.result.curve) });
+		ctx.hover(bands, (fit) => ({
+			title: fit.key,
+			rows: [["95% band", this.options.band]]
+		}));
+		const reach = this.options.residuals ? points.flatMap((point) => {
+			const fit = perGroup ? fits.find((candidate) => candidate.key === point.group) : fits[0];
+			return fit ? [{
+				point,
+				end: clamp(axes.y(Regression.at(fit.result, point.x)))
+			}] : [];
+		}) : [];
+		const stems = ctx.marks("residuals", "line", reach, (d) => d.point.index).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1);
+		ctx.set(stems, {
+			x1: (d) => d.point.px,
+			x2: (d) => d.point.px,
+			y1: (d) => d.point.py,
+			y2: (d) => d.end
+		});
+		this.drawDots(ctx, points, { radius: this.options.radius - 1 });
+		const lines = ctx.marks("fits", "path", fits, (fit) => fit.key).attr("fill", "none").attr("stroke", ink).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		ctx.set(lines, { d: (fit) => line().x(X).y((d) => clamp(axes.y(d.fit))).curve(Scales.curve(CurveKind.Monotone))(fit.result.curve) });
+		ctx.drawOn(lines);
+		ctx.hover(lines, (fit) => ({
+			title: fit.key,
+			color: ink(fit),
+			rows: [
+				["Fit", fit.result.equation],
+				["R²", +fit.result.r2.toFixed(3)],
+				["n", fit.result.count]
+			]
+		}));
+		this.drawSummary(ctx, points, fits);
+	}
+	drawSummary(ctx, points, fits) {
+		const shown = this.options.summary ? fits.slice(0, 3) : [];
+		const corner = this.quietCorner(ctx, points);
+		const lift = corner.y > ctx.plot.height / 2 ? -(shown.length - 1) * 14 : 0;
+		const notes = ctx.marks("fit-summary", "text", shown, (fit) => fit.key).attr("text-anchor", corner.anchor).text((fit) => `${fit.key === "Overall" ? "" : `${fit.key}: `}R² = ${fit.result.r2.toFixed(2)}`);
+		ctx.text(notes, 11, "secondary");
+		this.halo(notes, ctx);
+		ctx.set(notes, {
+			x: corner.x,
+			y: (_, i) => corner.y + lift + i * 14
+		});
+	}
+};
+export { RegressionBand, RegressionScatter, RegressionScope };

package/dist/charts/scatter/RugScatter.js

@@ -0,0 +1,138 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { ScatterBase, ScatterScaling } from "./ScatterBase.js";
+import { bin, max } from "d3";
+// src/charts/scatter/RugScatter.ts
+var RugAxes = /* @__PURE__ */ function(RugAxes) {
+	RugAxes["Both"] = "both-rugs";
+	RugAxes["X"] = "x-rug";
+	RugAxes["Y"] = "y-rug";
+	return RugAxes;
+}({});
+var RugMark = /* @__PURE__ */ function(RugMark) {
+	RugMark["Tick"] = "ticks";
+	RugMark["Dot"] = "beads";
+	RugMark["Density"] = "density-strip";
+	return RugMark;
+}({});
+var RugPlacement = /* @__PURE__ */ function(RugPlacement) {
+	RugPlacement["Outer"] = "outer";
+	RugPlacement["Inner"] = "inner";
+	return RugPlacement;
+}({});
+var STRIP = 14;
+/** Scatter with each coordinate echoed along the axes, so marginal gaps and clumps stay visible. */
+var RugScatter = class extends ScatterBase {
+	static meta = {
+		id: "rug-scatter",
+		name: "Rug scatter",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Adds a rug of one-dimensional marks along the axes to show each marginal distribution.",
+		tags: [
+			"rug plot",
+			"marginal ticks",
+			"carpet"
+		],
+		sample: (seed) => SampleData.points(seed, 90, 3),
+		variants: {
+			rug: [
+				"both-rugs",
+				"x-rug",
+				"y-rug"
+			],
+			rugMark: [
+				"ticks",
+				"beads",
+				"density-strip"
+			],
+			placement: ["outer", "inner"],
+			scaling: [
+				ScatterScaling.Linear,
+				ScatterScaling.SemilogX,
+				ScatterScaling.SemilogY,
+				ScatterScaling.LogLog
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			rug: "both-rugs",
+			rugMark: "ticks",
+			placement: "outer",
+			radius: 4.5
+		};
+	}
+	get onX() {
+		return this.options.rug !== "y-rug";
+	}
+	get onY() {
+		return this.options.rug !== "x-rug";
+	}
+	frame(ctx) {
+		const outer = this.options.placement === "outer";
+		return {
+			left: outer && this.onY ? 18 : 0,
+			right: ctx.plot.width,
+			top: 0,
+			bottom: ctx.plot.height - (outer && this.onX ? 18 : 0)
+		};
+	}
+	plotPoints(ctx, _axes, points) {
+		const { rugMark } = this.options, { height } = ctx.plot;
+		const { left, bottom } = this.frame(ctx);
+		const lane = {
+			x: this.options.placement === "outer" ? height - STRIP : bottom - STRIP,
+			y: 0
+		};
+		const laneY = this.options.placement === "outer" ? 0 : left;
+		const ticks = [...this.onX ? points.map((point) => ({
+			point,
+			axis: "x"
+		})) : [], ...this.onY ? points.map((point) => ({
+			point,
+			axis: "y"
+		})) : []];
+		const key = (d) => `${d.axis}/${d.point.index}`;
+		const color = (d) => this.hue(ctx, d.point);
+		const lines = ctx.marks("rug-ticks", "line", rugMark === "ticks" ? ticks : [], key).attr("stroke", color).attr("stroke-width", 1.5).attr("stroke-opacity", .6);
+		ctx.set(lines, {
+			x1: (d) => d.axis === "x" ? d.point.px : laneY,
+			x2: (d) => d.axis === "x" ? d.point.px : laneY + STRIP,
+			y1: (d) => d.axis === "x" ? lane.x : d.point.py,
+			y2: (d) => d.axis === "x" ? lane.x + STRIP : d.point.py
+		});
+		ctx.hover(lines, (d) => this.tooltip(ctx, d.point));
+		const beads = ctx.marks("rug-beads", "circle", rugMark === "beads" ? ticks : [], key).attr("fill", color).attr("fill-opacity", .55);
+		ctx.set(beads, {
+			cx: (d) => d.axis === "x" ? d.point.px : laneY + STRIP / 2,
+			cy: (d) => d.axis === "x" ? lane.x + STRIP / 2 : d.point.py,
+			r: 2.5
+		});
+		ctx.hover(beads, (d) => this.tooltip(ctx, d.point));
+		const cells = rugMark === "density-strip" ? this.cells(ctx, points) : [];
+		const peak = max(cells, (cell) => cell.count) ?? 1;
+		const strips = ctx.marks("rug-strip", "rect", cells, (d) => `${d.axis}/${d.x0}`).attr("fill", (d) => ctx.palette.sequential(.1 + d.count / peak * .9));
+		ctx.set(strips, {
+			x: (d) => d.axis === "x" ? d.x0 : laneY,
+			y: (d) => d.axis === "x" ? lane.x : d.x0,
+			width: (d) => d.axis === "x" ? Math.max(1, d.x1 - d.x0 - 1) : STRIP,
+			height: (d) => d.axis === "x" ? STRIP : Math.max(1, d.x1 - d.x0 - 1)
+		});
+		ctx.hover(strips, (d) => ({ title: `${d.count} points` }));
+		this.drawDots(ctx, points);
+	}
+	cells(ctx, points) {
+		const { left, right, top, bottom } = this.frame(ctx);
+		const count = (axis, low, high, value) => bin().value(value).domain([low, high]).thresholds(28)(points).filter((set) => set.length).map((set) => ({
+			axis,
+			x0: set.x0,
+			x1: set.x1,
+			count: set.length
+		}));
+		return [...this.onX ? count("x", left, right, (p) => p.px) : [], ...this.onY ? count("y", top, bottom, (p) => p.py) : []];
+	}
+};
+export { RugAxes, RugMark, RugPlacement, RugScatter };