@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/statistics/KaplanMeierCurve.js

@@ -0,0 +1,249 @@
+import { ChartFamily, CurveKind, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { StatisticalChart } from "./StatisticalChart.js";
+import { ascending, group } from "d3";
+// src/charts/statistics/KaplanMeierCurve.ts
+/** Estimator of the survival function. */
+var SurvivalEstimator = /* @__PURE__ */ function(SurvivalEstimator) {
+	SurvivalEstimator["KaplanMeier"] = "kaplan-meier";
+	SurvivalEstimator["NelsonAalen"] = "nelson-aalen";
+	return SurvivalEstimator;
+}({});
+/** Which transform of survival the y axis shows. */
+var SurvivalScale = /* @__PURE__ */ function(SurvivalScale) {
+	SurvivalScale["Survival"] = "survival";
+	SurvivalScale["Failure"] = "cumulative-incidence";
+	SurvivalScale["Hazard"] = "cumulative-hazard";
+	SurvivalScale["LogLog"] = "log-log";
+	return SurvivalScale;
+}({});
+/** Time-to-event outcomes with censoring: the share of subjects still event-free over time, by group. */
+var KaplanMeierCurve = class extends StatisticalChart {
+	static meta = {
+		id: "kaplan-meier-curve",
+		name: "Kaplan-Meier curve",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Estimates the probability of remaining event-free over time from censored follow-up data, by group.",
+		tags: [
+			"survival",
+			"time to event",
+			"censoring",
+			"nelson-aalen",
+			"clinical"
+		],
+		sample: (seed) => SampleData.distribution(seed, 70, 3).map((row, i) => {
+			const time = Math.max(1, +row.value - 14), follow = 44 + i % 7 * 3, lost = i % 6 === 0;
+			return {
+				time: +(lost ? time * .7 : Math.min(time, follow)).toFixed(1),
+				event: lost || time > follow ? 0 : 1,
+				group: row.group
+			};
+		}),
+		variants: {
+			estimator: Object.values(SurvivalEstimator),
+			scale: Object.values(SurvivalScale),
+			band: [false, true],
+			censors: [true, false],
+			atRisk: [false, true],
+			median: [false, true]
+		},
+		valid: ({ scale, median }) => !median || scale === "survival" || scale === "cumulative-incidence"
+	};
+	defaults() {
+		return {
+			time: "time",
+			event: "event",
+			group: "group",
+			estimator: "kaplan-meier",
+			scale: "survival",
+			band: false,
+			censors: true,
+			atRisk: false,
+			median: false
+		};
+	}
+	axisTitles() {
+		const { scale } = this.options;
+		return {
+			x: scale === "log-log" ? "Time (log)" : "Time",
+			y: {
+				["survival"]: "Survival probability",
+				["cumulative-incidence"]: "Cumulative incidence",
+				["cumulative-hazard"]: "Cumulative hazard",
+				["log-log"]: "log(-log S)"
+			}[scale]
+		};
+	}
+	arms() {
+		const { data, time, event, group: field, estimator } = this.options;
+		const rows = this.complete(data, time, event).filter((row) => +row[time] >= 0);
+		return [...group(rows, (row) => String(row[field] ?? "All"))].map(([key, part]) => {
+			const sorted = part.map((row) => ({
+				time: +row[time],
+				event: +row[event] ? 1 : 0
+			})).sort((a, b) => ascending(a.time, b.time));
+			const steps = [{
+				time: 0,
+				survival: 1,
+				low: 1,
+				high: 1,
+				atRisk: sorted.length
+			}];
+			const censored = [];
+			let risk = sorted.length, survival = 1, hazard = 0, greenwood = 0, median = null, events = 0;
+			for (const [at, tied] of group(sorted, (d) => d.time)) {
+				const deaths = tied.filter((d) => d.event).length;
+				if (deaths) {
+					events += deaths;
+					hazard += deaths / risk;
+					survival = estimator === "kaplan-meier" ? survival * (1 - deaths / risk) : Math.exp(-hazard);
+					if (risk > deaths) greenwood += deaths / (risk * (risk - deaths));
+					const logged = Math.log(Math.max(1e-12, survival)), error = logged ? 1.96 * Math.sqrt(greenwood) / Math.abs(logged) : 0;
+					steps.push({
+						time: at,
+						survival,
+						atRisk: risk,
+						low: survival ** Math.exp(error),
+						high: survival ** Math.exp(-error)
+					});
+					if (median === null && survival <= .5) median = at;
+				}
+				if (tied.length > deaths) censored.push({
+					time: at,
+					survival
+				});
+				risk -= tied.length;
+			}
+			const last = sorted.at(-1)?.time ?? 0;
+			if (steps.at(-1).time < last) steps.push({
+				...steps.at(-1),
+				time: last
+			});
+			return {
+				key,
+				steps,
+				censored,
+				median,
+				events,
+				times: sorted.map((d) => d.time)
+			};
+		});
+	}
+	y(survival) {
+		const { scale } = this.options;
+		if (scale === "cumulative-incidence") return 1 - survival;
+		if (scale === "cumulative-hazard") return -Math.log(Math.max(1e-6, survival));
+		if (scale === "log-log") return Math.log(Math.max(1e-6, -Math.log(Math.min(1 - 1e-6, survival))));
+		return survival;
+	}
+	get logTime() {
+		return this.options.scale === "log-log";
+	}
+	plotMargin() {
+		const base = super.plotMargin();
+		const groups = this.options.atRisk ? new Set((this.options.data ?? []).map((row) => String(row[this.options.group] ?? "All"))).size : 0;
+		return {
+			...base,
+			bottom: base.bottom + (groups ? 22 + groups * 13 : 0)
+		};
+	}
+	scales(ctx) {
+		const arms = this.arms(), { scale, band } = this.options;
+		const reachTime = Math.max(1, ...arms.flatMap((arm) => arm.times));
+		const firstEvent = Math.min(reachTime, ...arms.flatMap((arm) => arm.steps.slice(1).map((d) => d.time)).filter((t) => t > 0));
+		const x = this.logTime ? this.logarithmic([firstEvent * .9, reachTime * 1.05], [0, ctx.plot.width]) : this.linear([0, reachTime * 1.02], [0, ctx.plot.width]);
+		const fixed = scale === "survival" || scale === "cumulative-incidence";
+		const steps = arms.flatMap((arm) => arm.steps.slice(this.logTime ? 1 : 0));
+		const y = fixed ? [0, 1] : this.span(steps.flatMap((d) => [this.y(d.survival), ...band ? [this.y(d.low), this.y(d.high)] : []]), .05);
+		return {
+			x,
+			y: this.linear(scale === "cumulative-hazard" ? [0, y[1]] : y, [ctx.plot.height, 0])
+		};
+	}
+	path(arm, axes, at) {
+		const [lowest] = axes.x.domain(), [floor, ceiling] = axes.y.domain();
+		return arm.steps.filter((d) => !this.logTime || d.time >= lowest).map((d) => [d.time, Math.max(floor, Math.min(ceiling, at(d)))]);
+	}
+	plotMarks(ctx, axes) {
+		const { band, censors, atRisk, median } = this.options;
+		const arms = this.arms(), color = (arm) => ctx.palette.color(arm.key);
+		this.ribbons(ctx, "band", band ? arms.map((arm) => {
+			const low = this.path(arm, axes, (d) => this.y(d.low)), high = this.path(arm, axes, (d) => this.y(d.high));
+			return {
+				key: arm.key,
+				color: color(arm),
+				opacity: .13,
+				curve: CurveKind.StepAfter,
+				points: low.map((d, i) => [
+					d[0],
+					d[1],
+					high[i][1]
+				])
+			};
+		}) : [], axes);
+		const guide = median ? arms.filter((arm) => arm.median !== null) : [];
+		const level = .5;
+		const right = axes.x.domain()[1];
+		this.rules(ctx, "median-level", guide.length ? [{
+			key: "level",
+			from: [0, level],
+			to: [right, level],
+			dash: "2 3"
+		}] : [], axes);
+		this.rules(ctx, "median-drops", guide.map((arm) => ({
+			key: arm.key,
+			from: [arm.median, level],
+			to: [arm.median, 0],
+			dash: "2 3"
+		})), axes);
+		this.traces(ctx, "curves", arms.map((arm) => ({
+			key: arm.key,
+			color: color(arm),
+			curve: CurveKind.StepAfter,
+			points: this.path(arm, axes, (d) => this.y(d.survival)),
+			tip: {
+				title: arm.key,
+				color: color(arm),
+				rows: [
+					["Subjects", arm.times.length],
+					["Events", arm.events],
+					["Median", arm.median ?? "not reached"]
+				]
+			}
+		})), axes);
+		const marks = censors ? arms.flatMap((arm) => arm.censored.filter((d) => !this.logTime || d.time >= axes.x.domain()[0]).map((d) => ({
+			arm,
+			...d
+		}))) : [];
+		const ticks = ctx.marks("censored", "line", marks, (d) => `${d.arm.key}/${d.time}`).attr("stroke", (d) => color(d.arm)).attr("stroke-width", 2);
+		const [floor, ceiling] = axes.y.domain();
+		const cy = (d) => axes.y(Math.max(floor, Math.min(ceiling, this.y(d.survival))));
+		ctx.set(ticks, {
+			x1: (d) => axes.x(d.time),
+			x2: (d) => axes.x(d.time),
+			y1: (d) => Math.max(0, cy(d) - 4),
+			y2: (d) => cy(d) + 4
+		});
+		ctx.hover(ticks, (d) => ({
+			title: `${d.arm.key}, censored`,
+			color: color(d.arm),
+			rows: [["Time", d.time], ["Survival", +d.survival.toFixed(3)]]
+		}));
+		this.riskTable(ctx, atRisk ? arms : [], axes);
+	}
+	riskTable(ctx, arms, axes) {
+		const top = ctx.plot.height + 54;
+		const stops = arms.length ? axes.x.ticks(5).filter((t, i, all) => i === 0 || axes.x(t) - axes.x(all[i - 1]) >= 24) : [];
+		const cells = arms.flatMap((arm, row) => stops.map((t) => ({
+			key: `${arm.key}/${t}`,
+			x: axes.x(t),
+			y: top + row * 13,
+			text: `${arm.times.filter((time) => time >= t).length}`
+		})));
+		ctx.text(ctx.marks("risk", "text", cells, (d) => d.key).attr("x", (d) => d.x).attr("y", (d) => d.y).attr("text-anchor", "middle").text((d) => d.text), 10.5, "muted");
+		ctx.text(ctx.marks("risk-names", "text", arms, (d) => d.key).attr("x", -12).attr("y", (_, row) => top + row * 13).attr("text-anchor", "end").text((d) => d.key.slice(0, 9)), 10.5);
+	}
+};
+export { KaplanMeierCurve, SurvivalEstimator, SurvivalScale };

package/dist/charts/statistics/LagPlot.js

@@ -0,0 +1,96 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { RegressionFit } from "./RegressionFit.js";
+import { StatisticalChart } from "./StatisticalChart.js";
+// src/charts/statistics/LagPlot.ts
+/** Reveals serial structure at a glance: random data is a cloud, autocorrelated data a diagonal, seasonality a loop. */
+var LagPlot = class extends StatisticalChart {
+	static meta = {
+		id: "lag-plot",
+		name: "Lag plot",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots each value against the value a fixed lag later, revealing randomness, autocorrelation and cycles.",
+		tags: [
+			"time series",
+			"phase plot",
+			"return map",
+			"poincare"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 90, 1),
+		variants: {
+			lag: [
+				1,
+				2,
+				7,
+				14
+			],
+			path: [false, true],
+			fit: [true, false],
+			differenced: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			value: "value",
+			lag: 1,
+			path: false,
+			fit: true,
+			differenced: false
+		};
+	}
+	axisTitles() {
+		return {
+			x: "Value at t",
+			y: `Value at t + ${this.options.lag}`
+		};
+	}
+	pairs() {
+		const { data, value, lag, differenced } = this.options;
+		let values = this.complete(data, value).map((row) => +row[value]);
+		if (differenced) values = values.slice(1).map((v, i) => v - values[i]);
+		return values.slice(lag).map((v, i) => [values[i], v]);
+	}
+	scales(ctx) {
+		const pairs = this.pairs(), domain = this.span(pairs.flat());
+		return {
+			x: this.linear(domain, [0, ctx.plot.width]),
+			y: this.linear(domain, [ctx.plot.height, 0])
+		};
+	}
+	plotMarks(ctx, axes) {
+		const { path, fit } = this.options;
+		const pairs = this.pairs();
+		const [low, high] = axes.x.domain();
+		const ink = ctx.palette.color("Series");
+		this.rules(ctx, "identity", [{
+			key: "identity",
+			from: [low, low],
+			to: [high, high],
+			dash: "5 4"
+		}], axes);
+		this.traces(ctx, "phase", path ? [{
+			key: "Time order",
+			color: ink,
+			width: 1.5,
+			points: pairs
+		}] : [], axes);
+		const line = fit && pairs.length > 2 ? new RegressionFit(pairs.map((d) => d[0]), pairs.map((d) => d[1])) : null;
+		const clip = (x) => [x, Math.max(low, Math.min(high, line.predict(x)))];
+		this.traces(ctx, "fit", line ? [{
+			key: "Least squares",
+			color: ctx.theme.ink,
+			points: [clip(low), clip(high)]
+		}] : [], axes);
+		this.dots(ctx, "points", pairs, (d) => [axes.x(d[0]), axes.y(d[1])], () => ink, (d) => ({
+			title: "Pair",
+			color: ink,
+			rows: [["At t", d[0]], [`At t + ${this.options.lag}`, d[1]]]
+		}), {
+			r: path ? 3 : 4,
+			ring: !path
+		});
+	}
+};
+export { LagPlot };

package/dist/charts/statistics/LiftChart.js

@@ -0,0 +1,178 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { ClassifierCurveBase } from "./ClassifierCurveBase.js";
+import { sum } from "d3";
+// src/charts/statistics/LiftChart.ts
+/** What the chart reads off each ranked bucket. */
+var LiftMetric = /* @__PURE__ */ function(LiftMetric) {
+	LiftMetric["CumulativeGain"] = "cumulative-gain";
+	LiftMetric["CumulativeLift"] = "cumulative-lift";
+	LiftMetric["BucketLift"] = "bucket-lift";
+	LiftMetric["ResponseRate"] = "response-rate";
+	return LiftMetric;
+}({});
+/** Mark drawn per bucket. */
+var LiftMarks = /* @__PURE__ */ function(LiftMarks) {
+	LiftMarks["Line"] = "line";
+	LiftMarks["Bars"] = "bars";
+	return LiftMarks;
+}({});
+/** Decides how deep into a ranked list to act: how much better than random each slice of the population performs. */
+var LiftChart = class extends ClassifierCurveBase {
+	static meta = {
+		id: "lift-chart",
+		name: "Lift chart",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Ranks cases by predicted score and shows how much better than random each slice performs, for targeting decisions.",
+		tags: [
+			"gains",
+			"classifier",
+			"marketing",
+			"decile"
+		],
+		sample: (seed) => ClassifierCurveBase.scored(seed),
+		variants: {
+			metric: Object.values(LiftMetric),
+			marks: Object.values(LiftMarks),
+			buckets: [
+				10,
+				5,
+				20
+			],
+			ideal: [false, true]
+		},
+		valid: ({ metric, marks, ideal }) => !(ideal && (metric === "bucket-lift" || marks === "bars"))
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			metric: "cumulative-gain",
+			marks: "line",
+			buckets: 10,
+			ideal: false
+		};
+	}
+	axisTitles() {
+		return {
+			x: "Population targeted",
+			y: {
+				["cumulative-gain"]: "Positives captured",
+				["cumulative-lift"]: "Cumulative lift",
+				["bucket-lift"]: "Lift in bucket",
+				["response-rate"]: "Response rate"
+			}[this.options.metric]
+		};
+	}
+	buckets(model) {
+		const { metric, buckets } = this.options;
+		const n = model.cases.length, prevalence = model.positives / (n || 1);
+		let seen = 0, hits = 0;
+		return Array.from({ length: Math.min(buckets, n) }, (_, index) => {
+			const count = Math.round((index + 1) * n / Math.min(buckets, n)) - seen;
+			const slice = model.cases.slice(seen, seen + count), inside = sum(slice, (d) => +d.hit);
+			seen += count;
+			hits += inside;
+			const rate = hits / seen;
+			const value = {
+				["cumulative-gain"]: hits / (model.positives || 1),
+				["cumulative-lift"]: rate / (prevalence || 1),
+				["bucket-lift"]: inside / (count || 1) / (prevalence || 1),
+				["response-rate"]: rate
+			}[metric];
+			return {
+				model,
+				index,
+				share: seen / n,
+				value,
+				hits: inside,
+				size: count
+			};
+		});
+	}
+	ideal(model) {
+		if (model.positives <= 0) return [];
+		const prevalence = model.positives / (model.cases.length || 1), lift = 1 / prevalence;
+		const shares = [
+			1e-4,
+			prevalence,
+			1
+		].filter((x) => x > 0);
+		const at = {
+			["cumulative-gain"]: (x) => Math.min(1, x / (prevalence || 1)),
+			["cumulative-lift"]: (x) => Math.min(lift, 1 / x),
+			["response-rate"]: (x) => Math.min(1, prevalence / x),
+			["bucket-lift"]: () => 1
+		}[this.options.metric];
+		return (this.options.metric === "cumulative-gain" ? shares : Array.from({ length: 30 }, (_, i) => prevalence + i / 29 * (1 - prevalence))).map((x) => [x, at(x)]);
+	}
+	scales(ctx) {
+		const { metric, ideal } = this.options;
+		const values = this.models().flatMap((model) => [...this.buckets(model).map((d) => d.value), ...ideal ? this.ideal(model).map((d) => d[1]) : []]);
+		const top = metric === "cumulative-gain" ? 1 : Math.max(1.1, ...values) * 1.06;
+		return {
+			x: this.linear([0, 1], [0, ctx.plot.width]),
+			y: this.linear([0, top], [ctx.plot.height, 0])
+		};
+	}
+	tickFormat(scale) {
+		const horizontal = scale.range()[0] === 0;
+		const rate = this.options.metric === "cumulative-gain" || this.options.metric === "response-rate";
+		return horizontal || rate ? (value) => `${Math.round(+value * 100)}%` : super.tickFormat(scale);
+	}
+	plotMarks(ctx, axes) {
+		const { metric, marks, ideal, buckets } = this.options;
+		const models = this.models(), color = (model) => this.color(ctx, model);
+		const base = models[0];
+		const prevalence = base ? base.positives / (base.cases.length || 1) : 0;
+		const baseline = metric === "cumulative-gain" ? [[0, 0], [1, 1]] : metric === "response-rate" ? [[0, prevalence], [1, prevalence]] : [[0, 1], [1, 1]];
+		this.rules(ctx, "random", [{
+			key: "random",
+			from: baseline[0],
+			to: baseline[1],
+			dash: "5 4"
+		}], axes);
+		this.traces(ctx, "ideal", ideal && base ? [{
+			key: "Perfect model",
+			color: ctx.theme.inkMuted,
+			width: 1.5,
+			points: this.ideal(base)
+		}] : [], axes);
+		const all = models.flatMap((model) => this.buckets(model));
+		const tip = (d) => ({
+			title: `${d.model.key}, top ${Math.round(d.share * 100)}%`,
+			color: color(d.model),
+			rows: [
+				[this.axisTitles().y, +d.value.toFixed(3)],
+				["Cases", d.size],
+				["Positives", d.hits]
+			]
+		});
+		if (marks === "bars") {
+			const band = axes.x(1 / (buckets || 1)) - axes.x(0), thick = Math.max(2, (band - 2) / (models.length || 1));
+			const bars = ctx.marks("bars", "rect", all, (d) => `${d.model.key}/${d.index}`).attr("fill", (d) => color(d.model)).attr("rx", Math.min(4, thick / 3));
+			const left = (d) => axes.x(d.index / (buckets || 1)) + 1 + models.indexOf(d.model) * thick;
+			ctx.set(bars, {
+				x: left,
+				width: Math.max(1, thick - 2),
+				y: (d) => axes.y(d.value),
+				height: (d) => axes.y(0) - axes.y(d.value)
+			}, {
+				x: left,
+				width: Math.max(1, thick - 2),
+				y: axes.y(0),
+				height: 0
+			}, 6);
+			ctx.hover(bars, tip);
+			return;
+		}
+		const origin = metric === "cumulative-gain" ? [[0, 0]] : [];
+		this.traces(ctx, "curves", models.map((model) => ({
+			key: model.key,
+			color: color(model),
+			points: [...origin, ...this.buckets(model).map((d) => [d.share, d.value])]
+		})), axes);
+		this.dots(ctx, "buckets", all, (d) => [axes.x(d.share), axes.y(d.value)], (d) => color(d.model), tip, { key: (d) => `${d.model.key}/${d.index}` });
+	}
+};
+export { LiftChart, LiftMarks, LiftMetric };