@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/statistics/CorrelogramBase.js

@@ -0,0 +1,152 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { StatisticalChart } from "./StatisticalChart.js";
+import { group } from "d3";
+// src/charts/statistics/CorrelogramBase.ts
+/** Mark for each lag. */
+var CorrelogramMarks = /* @__PURE__ */ function(CorrelogramMarks) {
+	CorrelogramMarks["Stems"] = "stems";
+	CorrelogramMarks["Bars"] = "bars";
+	CorrelogramMarks["Steps"] = "steps";
+	return CorrelogramMarks;
+}({});
+/** Correlation by lag with a significance band: the shared drawing behind ACF, PACF and CCF plots. */
+var CorrelogramBase = class extends StatisticalChart {
+	static family = {
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table
+	};
+	lagRange(rows) {
+		return [Math.min(0, ...rows.map((d) => d.lag)) - .8, Math.max(1, ...rows.map((d) => d.lag)) + .8];
+	}
+	/** Transform applied to a raw series before differencing. */
+	prepare(values) {
+		return values;
+	}
+	/** Each series' values in row order, differenced `difference` times. */
+	sequences() {
+		const { data, value, series, difference } = this.options;
+		return [...group(this.complete(data, value), (row) => String(row[series] ?? value))].map(([key, rows]) => {
+			let values = this.prepare(rows.map((row) => +row[value]));
+			for (let d = 0; d < difference; d++) values = values.slice(1).map((v, i) => v - values[i]);
+			return [key, values];
+		});
+	}
+	lags(length) {
+		return Math.max(1, Math.min(this.options.maxLag ?? 36, Math.floor(length / 3), length - 1));
+	}
+	get upright() {
+		return this.options.orientation === Orientation.Vertical;
+	}
+	axisTitles() {
+		return this.upright ? {
+			x: "Lag",
+			y: this.statisticName()
+		} : {
+			x: this.statisticName(),
+			y: "Lag"
+		};
+	}
+	scales(ctx) {
+		const rows = this.estimates();
+		const reach = Math.min(1.05, Math.max(.2, ...rows.map((d) => Math.abs(d.value)), ...rows.map((d) => d.limit)) * 1.08);
+		const low = rows.some((d) => d.value < 0 || d.limit > 0) ? -reach : 0;
+		const lags = this.lagRange(rows), values = [low, reach];
+		const { width, height } = ctx.plot;
+		return this.upright ? {
+			x: this.linear(lags, [0, width]),
+			y: this.linear(values, [height, 0])
+		} : {
+			x: this.linear(values, [0, width]),
+			y: this.linear(lags, [0, height])
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { marks } = this.options;
+		const rows = this.estimates(), upright = this.upright;
+		const lagScale = upright ? axes.x : axes.y, valueScale = upright ? axes.y : axes.x;
+		const at = (lag, value) => upright ? [lagScale(lag), valueScale(value)] : [valueScale(value), lagScale(lag)];
+		const color = (d) => ctx.palette.color(d.series);
+		const names = [...new Set(rows.map((d) => d.series))];
+		const step = Math.abs(lagScale(1) - lagScale(0)), dodge = (d) => ((names.indexOf(d.series) + .5) / names.length - .5) * step * .8;
+		const seat = (d) => {
+			const [x, y] = at(d.lag, d.value);
+			return upright ? [x + dodge(d), y] : [x, y + dodge(d)];
+		};
+		const root = (d) => {
+			const [x, y] = at(d.lag, 0);
+			return upright ? [x + dodge(d), y] : [x, y + dodge(d)];
+		};
+		const banded = rows.filter((d) => d.limit > 0 && d.series === names[0]).sort((a, b) => a.lag - b.lag);
+		const outline = [...banded.map((d) => at(d.lag, d.limit)), ...[...banded].reverse().map((d) => at(d.lag, -d.limit))];
+		const band = ctx.marks("band", "path", outline.length ? [outline] : []).attr("fill", ctx.theme.inkMuted).attr("fill-opacity", .18);
+		const shape = (points) => `M${points.join("L")}Z`;
+		ctx.set(band, { d: shape }, { d: shape });
+		const [p0, p1] = [at(lagScale.domain()[0], 0), at(lagScale.domain()[1], 0)];
+		const baseline = ctx.marks("zero", "line", [0]).attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		ctx.set(baseline, {
+			x1: p0[0],
+			y1: p0[1],
+			x2: p1[0],
+			y2: p1[1]
+		});
+		const significant = (d) => d.limit === 0 || Math.abs(d.value) > d.limit;
+		const tip = (d) => ({
+			title: `Lag ${d.lag}`,
+			color: color(d),
+			rows: [[d.series, +d.value.toFixed(3)], ["95% band", d.limit ? `±${d.limit.toFixed(3)}` : "none"]]
+		});
+		const thick = Math.max(1, step * .8 / names.length - 2);
+		const bars = ctx.marks("bars", "rect", marks === "bars" ? rows : [], (d) => `${d.series}/${d.lag}`).attr("fill", color).attr("fill-opacity", (d) => significant(d) ? 1 : .45).attr("rx", Math.min(2, thick / 3));
+		const box = (d) => {
+			const [x0, y0] = root(d), [x1, y1] = seat(d);
+			return upright ? {
+				x: x0 - thick / 2,
+				y: Math.min(y0, y1),
+				width: thick,
+				height: Math.abs(y1 - y0)
+			} : {
+				x: Math.min(x0, x1),
+				y: y0 - thick / 2,
+				width: Math.abs(x1 - x0),
+				height: thick
+			};
+		};
+		ctx.set(bars, {
+			x: (d) => box(d).x,
+			y: (d) => box(d).y,
+			width: (d) => box(d).width,
+			height: (d) => box(d).height
+		});
+		ctx.hover(bars, tip);
+		const stems = marks === "stems" ? rows : [];
+		const lines = ctx.marks("stems", "line", stems, (d) => `${d.series}/${d.lag}`).attr("stroke", color).attr("stroke-width", 2).attr("stroke-opacity", (d) => significant(d) ? 1 : .45);
+		ctx.set(lines, {
+			x1: (d) => root(d)[0],
+			y1: (d) => root(d)[1],
+			x2: (d) => seat(d)[0],
+			y2: (d) => seat(d)[1]
+		}, {
+			x1: (d) => root(d)[0],
+			y1: (d) => root(d)[1],
+			x2: (d) => root(d)[0],
+			y2: (d) => root(d)[1]
+		}, 12);
+		this.dots(ctx, "heads", stems, seat, color, tip, {
+			key: (d) => `${d.series}/${d.lag}`,
+			r: step < 9 ? 2.5 : 4,
+			ring: step >= 9,
+			opacity: 1
+		});
+		const walks = marks === "steps" ? names.map((name) => {
+			const own = rows.filter((d) => d.series === name).sort((a, b) => a.lag - b.lag);
+			return {
+				key: name,
+				color: color({ series: name }),
+				points: own.flatMap((d) => [[d.lag - .5, d.value], [d.lag + .5, d.value]]).map(([lag, value]) => upright ? [lag, value] : [value, lag])
+			};
+		}) : [];
+		this.traces(ctx, "steps", walks, axes);
+	}
+};
+export { CorrelogramBase, CorrelogramMarks };

package/dist/charts/statistics/CrossCorrelationPlot.js

@@ -0,0 +1,66 @@
+import { Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { CorrelogramBase, CorrelogramMarks } from "./CorrelogramBase.js";
+import { RegressionFit } from "./RegressionFit.js";
+import { StatMath } from "./StatMath.js";
+// src/charts/statistics/CrossCorrelationPlot.ts
+/** Finds lead and lag between two series: a peak at positive lag means the first leads the second. */
+var CrossCorrelationPlot = class extends CorrelogramBase {
+	static meta = {
+		id: "cross-correlation-plot",
+		name: "Cross-correlation plot",
+		...CorrelogramBase.family,
+		description: "Correlates two time series at positive and negative lags to show which one leads the other.",
+		tags: [
+			"ccf",
+			"lead lag",
+			"time series"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 120, 2),
+		variants: {
+			marks: Object.values(CorrelogramMarks),
+			difference: [1, 0],
+			band: [true, false],
+			prewhiten: [false, true],
+			orientation: [Orientation.Vertical, Orientation.Horizontal]
+		}
+	};
+	defaults() {
+		return {
+			value: "value",
+			series: "series",
+			marks: CorrelogramMarks.Stems,
+			difference: 1,
+			band: true,
+			prewhiten: false,
+			orientation: Orientation.Vertical
+		};
+	}
+	statisticName() {
+		return "Cross-correlation";
+	}
+	estimates() {
+		const { band, prewhiten } = this.options;
+		const [first, second] = this.sequences();
+		if (!first || !second) return [];
+		let a = first[1], b = second[1];
+		const n = Math.min(a.length, b.length);
+		if (n < 6) return [];
+		if (prewhiten) {
+			const fit = new RegressionFit(a.slice(0, n - 1), a.slice(1, n));
+			const phi = fit.predict(1) - fit.predict(0);
+			const whiten = (values) => values.slice(1, n).map((v, i) => v - phi * values[i]);
+			a = whiten(a);
+			b = whiten(b);
+		}
+		const reach = Math.min(this.lags(a.length), 24), series = `${first[0]} leads ${second[0]}`;
+		const limit = band ? 1.96 / Math.sqrt(a.length) : 0;
+		return StatMath.ccf(a, b, -reach, reach).map((value, i) => ({
+			series,
+			lag: i - reach,
+			value,
+			limit
+		}));
+	}
+};
+export { CrossCorrelationPlot };

package/dist/charts/statistics/CusumChart.js

@@ -0,0 +1,132 @@
+import { CurveKind } from "../../core/enums.js";
+import { ProcessChartBase } from "./ProcessChartBase.js";
+import { mean } from "d3";
+// src/charts/statistics/CusumChart.ts
+/** How deviations accumulate. */
+var CusumForm = /* @__PURE__ */ function(CusumForm) {
+	CusumForm["TwoSided"] = "two-sided";
+	CusumForm["UpperOnly"] = "upper-only";
+	CusumForm["RawSum"] = "raw-sum";
+	return CusumForm;
+}({});
+/** Cumulative sum of deviations: catches small sustained shifts a Shewhart chart takes far longer to see. */
+var CusumChart = class extends ProcessChartBase {
+	static meta = {
+		id: "cusum-chart",
+		name: "CUSUM chart",
+		...ProcessChartBase.family,
+		description: "Accumulates deviations from target so small sustained process shifts cross a decision interval quickly.",
+		tags: [
+			"spc",
+			"cumulative sum",
+			"change detection",
+			"quality"
+		],
+		sample: (seed) => ProcessChartBase.measurements(seed),
+		variants: {
+			form: Object.values(CusumForm),
+			allowance: [
+				.5,
+				.25,
+				1
+			],
+			interval: [5, 4],
+			connect: [true, false]
+		},
+		valid: ({ form, allowance, interval }) => form !== "raw-sum" || allowance === .5 && interval === 5
+	};
+	defaults() {
+		return {
+			value: "value",
+			form: "two-sided",
+			allowance: .5,
+			interval: 5,
+			connect: true,
+			zones: false
+		};
+	}
+	statisticName() {
+		return "Upper CUSUM";
+	}
+	axisTitles() {
+		return {
+			x: "Sample",
+			y: "Cumulative sum"
+		};
+	}
+	states() {
+		const { data, value, allowance } = this.options;
+		const values = this.complete(data, value).map((row) => +row[value]);
+		const cut = Math.max(2, Math.ceil(values.length * .6)), base = values.slice(0, cut);
+		const target = mean(base) ?? 0, sigma = (mean(base.slice(1).map((v, i) => Math.abs(v - base[i]))) ?? 0) / 1.128 || 1;
+		let up = 0, down = 0, raw = 0;
+		return {
+			sigma,
+			rows: values.map((v, i) => {
+				up = Math.max(0, up + v - target - allowance * sigma);
+				down = Math.max(0, down + target - v - allowance * sigma);
+				raw += v - target;
+				return {
+					slot: i + 1,
+					up,
+					down,
+					raw
+				};
+			})
+		};
+	}
+	points() {
+		const { form, interval } = this.options;
+		const { rows, sigma } = this.states(), h = interval * sigma;
+		if (form === "raw-sum") {
+			const reach = 3 * sigma * Math.sqrt(rows.length);
+			return rows.map((d) => ({
+				slot: d.slot,
+				value: d.raw,
+				center: 0,
+				upper: reach,
+				lower: -reach
+			}));
+		}
+		return rows.map((d) => ({
+			slot: d.slot,
+			value: d.up,
+			center: 0,
+			upper: h,
+			lower: form === "two-sided" ? -h : 0
+		}));
+	}
+	scales(ctx) {
+		const axes = super.scales(ctx);
+		if (this.options.form !== "two-sided") return axes;
+		const [low, high] = axes.y.domain();
+		const deepest = Math.max(0, ...this.states().rows.map((d) => d.down));
+		return {
+			...axes,
+			y: this.linear(this.span([
+				low,
+				high,
+				-deepest
+			], .04), [ctx.plot.height, 0])
+		};
+	}
+	underlay(ctx, _points, axes) {
+		const { rows, sigma } = this.states(), two = this.options.form === "two-sided";
+		const breaches = two ? rows.filter((d) => d.down > this.options.interval * sigma) : [];
+		this.dots(ctx, "lower-breaches", breaches, (d) => [axes.x(d.slot), axes.y(-d.down)], () => ctx.theme.critical, (d) => ({
+			title: `Sample ${d.slot}`,
+			color: ctx.theme.critical,
+			rows: [["Lower CUSUM", +d.down.toFixed(3)]]
+		}), {
+			r: 5,
+			key: (d) => d.slot
+		});
+		this.traces(ctx, "lower-sum", two ? [{
+			key: "Lower CUSUM",
+			color: ctx.palette.color("Lower CUSUM"),
+			curve: CurveKind.Linear,
+			points: rows.map((d) => [d.slot, -d.down])
+		}] : [], axes);
+	}
+};
+export { CusumChart, CusumForm };

package/dist/charts/statistics/DetectionErrorCurve.js

@@ -0,0 +1,108 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { ClassifierCurveBase } from "./ClassifierCurveBase.js";
+import { StatMath } from "./StatMath.js";
+import { deviation, mean, minIndex } from "d3";
+// src/charts/statistics/DetectionErrorCurve.ts
+/** Warping of the error-rate axes. */
+var ErrorAxisScale = /* @__PURE__ */ function(ErrorAxisScale) {
+	ErrorAxisScale["Probit"] = "probit";
+	ErrorAxisScale["Log"] = "log";
+	return ErrorAxisScale;
+}({});
+/** How the error trade-off is estimated. */
+var ErrorCurveFit = /* @__PURE__ */ function(ErrorCurveFit) {
+	ErrorCurveFit["Empirical"] = "empirical";
+	ErrorCurveFit["Binormal"] = "binormal";
+	return ErrorCurveFit;
+}({});
+var LOW = .005;
+var HIGH = .8;
+/** Biometric and speech systems: both error rates on warped axes, so strong detectors stay readable. */
+var DetectionErrorCurve = class extends ClassifierCurveBase {
+	static meta = {
+		id: "det-curve",
+		name: "Detection error tradeoff",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots missed detections against false alarms on warped axes to compare accurate detectors.",
+		tags: [
+			"classifier",
+			"equal error rate",
+			"biometrics",
+			"det"
+		],
+		sample: (seed) => ClassifierCurveBase.scored(seed),
+		variants: {
+			axisScale: Object.values(ErrorAxisScale),
+			fit: Object.values(ErrorCurveFit),
+			equalError: [true, false],
+			diagonal: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			axisScale: "probit",
+			fit: "empirical",
+			equalError: true,
+			diagonal: true
+		};
+	}
+	axisTitles() {
+		return {
+			x: "False alarm rate",
+			y: "Miss rate"
+		};
+	}
+	errors(model) {
+		const inside = (value) => value >= LOW && value <= HIGH;
+		const shown = (points) => points.filter((d) => inside(d[0]) && inside(d[1]));
+		if (this.options.fit === "empirical") return shown(model.sweep.map((d) => [d.fpr, 1 - d.tpr]));
+		const on = model.cases.filter((d) => d.hit).map((d) => d.score), off = model.cases.filter((d) => !d.hit).map((d) => d.score);
+		const a = ((mean(on) ?? 0) - (mean(off) ?? 0)) / (deviation(on) || 1), b = (deviation(off) || 1) / (deviation(on) || 1);
+		return shown(Array.from({ length: 50 }, (_, i) => {
+			const fpr = LOW * (HIGH / LOW) ** (i / 49);
+			return [fpr, 1 - StatMath.normalCdf(a + b * StatMath.normalQuantile(fpr))];
+		}));
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot;
+		const build = (range) => this.options.axisScale === "probit" ? this.probit([LOW, HIGH], range) : this.logarithmic([LOW, HIGH], range);
+		return {
+			x: build([0, width]),
+			y: build([height, 0])
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { equalError, diagonal } = this.options;
+		const models = this.models(), color = (model) => this.color(ctx, model);
+		this.rules(ctx, "diagonal", diagonal ? [{
+			key: "equal",
+			from: [LOW, LOW],
+			to: [HIGH, HIGH],
+			dash: "5 4"
+		}] : [], axes);
+		this.traces(ctx, "curves", models.map((model) => ({
+			key: model.key,
+			color: color(model),
+			points: this.errors(model)
+		})), axes);
+		const crossings = equalError ? models.filter((model) => this.errors(model).length).map((model) => {
+			const points = this.errors(model), d = points[minIndex(points, ([x, y]) => Math.abs(x - y))];
+			return {
+				model,
+				rate: (d[0] + d[1]) / 2
+			};
+		}) : [];
+		this.dots(ctx, "equal-error", crossings, (d) => [axes.x(d.rate), axes.y(d.rate)], (d) => color(d.model), (d) => ({
+			title: d.model.key,
+			color: color(d.model),
+			rows: [["Equal error rate", `${(d.rate * 100).toFixed(1)}%`]]
+		}), {
+			r: 6,
+			key: (d) => d.model.key
+		});
+	}
+};
+export { DetectionErrorCurve, ErrorAxisScale, ErrorCurveFit };

package/dist/charts/statistics/EwmaChart.js

@@ -0,0 +1,99 @@
+import { ProcessChartBase } from "./ProcessChartBase.js";
+import { mean } from "d3";
+// src/charts/statistics/EwmaChart.ts
+/** Shape of the EWMA control limits. */
+var EwmaLimits = /* @__PURE__ */ function(EwmaLimits) {
+	EwmaLimits["Exact"] = "exact-limits";
+	EwmaLimits["Asymptotic"] = "asymptotic-limits";
+	return EwmaLimits;
+}({});
+/** Exponentially weighted control chart: remembers recent history, so it is robust to non-normal data and small shifts. */
+var EwmaChart = class extends ProcessChartBase {
+	static meta = {
+		id: "ewma-chart",
+		name: "EWMA chart",
+		...ProcessChartBase.family,
+		description: "Plots an exponentially weighted moving average against limits to detect small persistent process shifts.",
+		tags: [
+			"spc",
+			"moving average",
+			"change detection",
+			"quality"
+		],
+		sample: (seed) => ProcessChartBase.measurements(seed),
+		variants: {
+			lambda: [
+				.2,
+				.1,
+				.4
+			],
+			limits: Object.values(EwmaLimits),
+			raw: [false, true],
+			connect: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			value: "value",
+			lambda: .2,
+			limits: "exact-limits",
+			raw: false,
+			connect: true,
+			zones: false
+		};
+	}
+	statisticName() {
+		return "EWMA";
+	}
+	axisTitles() {
+		return {
+			x: "Sample",
+			y: "EWMA"
+		};
+	}
+	values() {
+		const { data, value } = this.options;
+		return this.complete(data, value).map((row) => +row[value]);
+	}
+	points() {
+		const { lambda, limits } = this.options, values = this.values(), l = lambda;
+		const cut = Math.max(2, Math.ceil(values.length * .6)), base = values.slice(0, cut);
+		const center = mean(base) ?? 0, sigma = (mean(base.slice(1).map((v, i) => Math.abs(v - base[i]))) ?? 0) / 1.128 || 1;
+		let z = center;
+		return values.map((v, i) => {
+			z = l * v + (1 - l) * z;
+			const growth = limits === "exact-limits" ? 1 - (1 - l) ** (2 * (i + 1)) : 1;
+			const reach = 3 * sigma * Math.sqrt(l / (2 - l) * growth);
+			return {
+				slot: i + 1,
+				value: z,
+				center,
+				upper: center + reach,
+				lower: center - reach
+			};
+		});
+	}
+	scales(ctx) {
+		const axes = super.scales(ctx);
+		if (!this.options.raw) return axes;
+		return {
+			...axes,
+			y: this.linear(this.span([...axes.y.domain(), ...this.values()], .02), [ctx.plot.height, 0])
+		};
+	}
+	underlay(ctx, _points, axes) {
+		const values = this.options.raw ? this.values() : [];
+		const raw = ctx.marks("raw", "circle", values, (_, i) => i).attr("fill", ctx.theme.inkMuted).attr("fill-opacity", .45);
+		ctx.set(raw, {
+			cx: (_, i) => axes.x(i + 1),
+			cy: (d) => axes.y(d),
+			r: 2.5
+		});
+		ctx.hover(raw, (d, i) => ({
+			title: `Sample ${i + 1}`,
+			color: ctx.theme.inkMuted,
+			rows: [["Observation", d]]
+		}));
+	}
+};
+export { EwmaChart, EwmaLimits };