@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/comparison/BarMeanChart.js

@@ -0,0 +1,130 @@
+import { ChartFamily, DataShape, Dimension, LegendPosition, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BandValueChart } from "./BandValueChart.js";
+import { ComparisonCenter, ComparisonSpread, Tally } from "./Tally.js";
+import { settleMarks } from "./settleMarks.js";
+// src/charts/comparison/BarMeanChart.ts
+/** How the observations behind each bar are shown. */
+var BarMeanRaw = /* @__PURE__ */ function(BarMeanRaw) {
+	BarMeanRaw["None"] = "none";
+	BarMeanRaw["Strip"] = "strip";
+	BarMeanRaw["Rug"] = "rug";
+	return BarMeanRaw;
+}({});
+var GOLDEN = .618034;
+/** The mean-and-error-bar column of every lab report, with the raw observations available beneath it. */
+var BarMeanChart = class extends BandValueChart {
+	static meta = {
+		id: "comparison-bar-mean",
+		name: "Mean bar chart",
+		family: ChartFamily.Comparison,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Compares group averages as zero-based bars, each carrying an error bar for its uncertainty.",
+		tags: [
+			"bar with error bars",
+			"dynamite plot",
+			"group means"
+		],
+		sample: (seed) => SampleData.distribution(seed, 40, 5),
+		variants: {
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			spread: [
+				ComparisonSpread.Ci95,
+				ComparisonSpread.StdError,
+				ComparisonSpread.StdDev,
+				ComparisonSpread.Iqr
+			],
+			raw: [
+				"none",
+				"strip",
+				"rug"
+			],
+			cap: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			legend: LegendPosition.None,
+			group: "group",
+			value: "value",
+			orientation: Orientation.Vertical,
+			spread: ComparisonSpread.Ci95,
+			raw: "none",
+			cap: true
+		};
+	}
+	bandLayout() {
+		const { data, group, value, spread, raw } = this.options;
+		const items = Tally.group(data, group, value).map((tally) => {
+			const centre = Tally.center(tally, spread === ComparisonSpread.Iqr ? ComparisonCenter.Median : ComparisonCenter.Mean);
+			const [low, high] = Tally.interval(tally, spread);
+			return {
+				tally,
+				centre,
+				low,
+				high
+			};
+		});
+		const observed = raw === "none" ? [] : items.flatMap((d) => d.tally.values);
+		return {
+			bands: items.map((d) => d.tally.key),
+			items,
+			values: [
+				0,
+				...observed,
+				...items.flatMap((d) => [d.low, d.high])
+			]
+		};
+	}
+	plotBands(ctx, { items, band, mid, value }) {
+		const { raw, cap } = this.options;
+		const fill = ctx.palette.color(this.options.value);
+		const width = band.bandwidth();
+		const along = (d) => mid(d.tally.key);
+		const zero = () => value(0);
+		const tip = (d) => ({
+			title: d.tally.key,
+			color: fill,
+			rows: [
+				["Centre", Tally.format(d.centre)],
+				["Interval", `${Tally.format(d.low)} to ${Tally.format(d.high)}`],
+				["n", d.tally.n]
+			]
+		});
+		const bars = ctx.marks("bars", "rect", items, (d) => d.tally.key).attr("fill", fill).attr("fill-opacity", raw === "none" ? 1 : .38).attr("rx", Math.min(4, width / 2));
+		settleMarks(ctx, bars, this.span(along, width, zero, (d) => value(d.centre)), this.span(along, width, zero, zero), 30);
+		ctx.hover(bars, tip);
+		const points = raw === "none" ? [] : items.flatMap((d) => d.tally.values.map((v, index) => ({
+			group: d.tally.key,
+			value: v,
+			index
+		})));
+		const offset = (d) => d.index * GOLDEN % 1 * width * .7 - width * .35;
+		const strip = ctx.marks("strip", "circle", raw === "strip" ? points : [], (d) => `${d.group}/${d.index}`).attr("fill", ctx.theme.ink).attr("fill-opacity", .45);
+		settleMarks(ctx, strip, {
+			...this.spot((d) => mid(d.group) + offset(d), (d) => value(d.value)),
+			r: 2
+		}, { r: 0 });
+		const rug = ctx.marks("rug", "line", raw === "rug" ? points : [], (d) => `${d.group}/${d.index}`).attr("stroke", ctx.theme.ink).attr("stroke-opacity", .4);
+		settleMarks(ctx, rug, this.cross((d) => mid(d.group), (d) => value(d.value), width * .42));
+		const halo = ctx.marks("halo", "line", items, (d) => d.tally.key).attr("stroke", ctx.theme.surface).attr("stroke-width", 4).attr("stroke-linecap", "round");
+		settleMarks(ctx, halo, this.rule(along, (d) => value(d.low), (d) => value(d.high)));
+		const whiskers = ctx.marks("whiskers", "line", items, (d) => d.tally.key).attr("stroke", ctx.theme.ink).attr("stroke-width", 2);
+		settleMarks(ctx, whiskers, this.rule(along, (d) => value(d.low), (d) => value(d.high)), this.rule(along, (d) => value(d.centre), (d) => value(d.centre)), 30);
+		ctx.hover(whiskers, tip);
+		const half = Math.min(9, width / 4);
+		const ends = cap ? items.flatMap((d) => [{
+			key: `${d.tally.key}/low`,
+			d,
+			at: d.low
+		}, {
+			key: `${d.tally.key}/high`,
+			d,
+			at: d.high
+		}]) : [];
+		const caps = ctx.marks("caps", "line", ends, (e) => e.key).attr("stroke", ctx.theme.ink).attr("stroke-width", 2);
+		settleMarks(ctx, caps, this.cross((e) => along(e.d), (e) => value(e.at), half));
+	}
+};
+export { BarMeanChart, BarMeanRaw };

package/dist/charts/comparison/CycleChart.js

@@ -0,0 +1,227 @@
+import { ChartFamily, DataShape, Dimension, LegendPosition } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BandValueChart } from "./BandValueChart.js";
+import { Tally } from "./Tally.js";
+import { settleMarks } from "./settleMarks.js";
+import { mean, median, rollup, scaleLinear, sum } from "d3";
+// src/charts/comparison/CycleChart.ts
+/** Which repeating calendar unit forms the panels. */
+var CycleUnit = /* @__PURE__ */ function(CycleUnit) {
+	CycleUnit["Month"] = "month";
+	CycleUnit["Quarter"] = "quarter";
+	CycleUnit["Weekday"] = "weekday";
+	return CycleUnit;
+}({});
+var CycleMark = /* @__PURE__ */ function(CycleMark) {
+	CycleMark["Line"] = "line";
+	CycleMark["Spike"] = "spike";
+	CycleMark["Dots"] = "dots";
+	return CycleMark;
+}({});
+var CycleReference = /* @__PURE__ */ function(CycleReference) {
+	CycleReference["Mean"] = "mean";
+	CycleReference["Median"] = "median";
+	CycleReference["None"] = "none";
+	return CycleReference;
+}({});
+var CycleAggregate = /* @__PURE__ */ function(CycleAggregate) {
+	CycleAggregate["Mean"] = "mean";
+	CycleAggregate["Sum"] = "sum";
+	return CycleAggregate;
+}({});
+var MONTHS = [
+	"Jan",
+	"Feb",
+	"Mar",
+	"Apr",
+	"May",
+	"Jun",
+	"Jul",
+	"Aug",
+	"Sep",
+	"Oct",
+	"Nov",
+	"Dec"
+];
+var DAYS = [
+	"Mon",
+	"Tue",
+	"Wed",
+	"Thu",
+	"Fri",
+	"Sat",
+	"Sun"
+];
+var asDate = (cell) => {
+	if (cell === null || cell === void 0 || cell === "") return null;
+	const date = cell instanceof Date ? cell : new Date(cell);
+	return Number.isNaN(+date) ? null : date;
+};
+/** Seasonal subseries: each month, quarter or weekday gets its own run through the years, around its own level. */
+var CycleChart = class extends BandValueChart {
+	static meta = {
+		id: "comparison-cycle",
+		name: "Cycle chart",
+		family: ChartFamily.Comparison,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Splits a time series by season so each period compares against itself in other years, and against other seasons.",
+		tags: [
+			"seasonal subseries",
+			"month plot",
+			"cycle plot"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 1461, 1).map((row, i) => ({
+			date: row.date,
+			value: +(100 + 22 * Math.sin(i / 365.25 * 2 * Math.PI - 1.2) + i * .012 + +row.value % 9).toFixed(2)
+		})),
+		variants: {
+			cycle: [
+				"month",
+				"quarter",
+				"weekday"
+			],
+			mark: [
+				"line",
+				"spike",
+				"dots"
+			],
+			reference: [
+				"mean",
+				"median",
+				"none"
+			],
+			aggregate: ["mean", "sum"]
+		}
+	};
+	defaults() {
+		return {
+			legend: LegendPosition.None,
+			date: "date",
+			value: "value",
+			cycle: "month",
+			mark: "line",
+			reference: "mean",
+			aggregate: "mean"
+		};
+	}
+	bandPadding() {
+		return .16;
+	}
+	/** PanelCell a date falls in, and the occurrence it belongs to within that panel. */
+	bucket(date) {
+		const year = date.getUTCFullYear(), month = date.getUTCMonth();
+		if (this.options.cycle === "weekday") return {
+			band: DAYS[(date.getUTCDay() + 6) % 7],
+			order: year * 12 + month,
+			label: `${MONTHS[month]} ${year}`
+		};
+		if (this.options.cycle === "quarter") return {
+			band: `Q${Math.floor(month / 3) + 1}`,
+			order: year,
+			label: `${year}`
+		};
+		return {
+			band: MONTHS[month],
+			order: year,
+			label: `${year}`
+		};
+	}
+	bandLayout() {
+		const { data, date, value, aggregate, reference, cycle } = this.options;
+		const entries = data.flatMap((row) => {
+			const when = asDate(row[date]), amount = Tally.num(row[value]);
+			return when === null || amount === null ? [] : [{
+				...this.bucket(when),
+				amount
+			}];
+		});
+		const fold = (list) => aggregate === "sum" ? sum(list) : mean(list) ?? 0;
+		const rolled = rollup(entries, (rows) => ({
+			label: rows[0].label,
+			value: fold(rows.map((d) => d.amount))
+		}), (d) => d.band, (d) => d.order);
+		const items = (cycle === "weekday" ? DAYS : cycle === "quarter" ? [
+			"Q1",
+			"Q2",
+			"Q3",
+			"Q4"
+		] : MONTHS).flatMap((name) => {
+			const line = rolled.get(name);
+			if (!line) return [];
+			const visits = [...line].sort((a, b) => a[0] - b[0]).map(([at, d]) => ({
+				band: name,
+				order: at,
+				label: d.label,
+				value: d.value
+			}));
+			const values = visits.map((d) => d.value);
+			return [{
+				name,
+				visits,
+				level: reference === "mean" ? mean(values) ?? null : reference === "median" ? median(values) ?? null : null
+			}];
+		});
+		const shown = items.flatMap((d) => d.visits.map((v) => v.value));
+		return {
+			bands: items.map((d) => d.name),
+			items,
+			values: shown
+		};
+	}
+	plotBands(ctx, { items, band, value }) {
+		const { mark } = this.options;
+		const stroke = ctx.palette.color(this.options.value);
+		const width = band.bandwidth();
+		const placement = new Map(items.map((panel) => {
+			const orders = [...new Set(panel.visits.map((v) => v.order))];
+			const inner = scaleLinear([0, Math.max(1, orders.length - 1)], [band(panel.name) + 3, band(panel.name) + width - 3]);
+			return [panel.name, (visit) => inner(orders.indexOf(visit.order))];
+		}));
+		const along = (d) => placement.get(d.band)(d);
+		const at = (d) => value(d.value);
+		const visits = items.flatMap((d) => d.visits);
+		const baseline = value.range()[0];
+		const tip = (d) => ({
+			title: `${d.band} · ${d.label}`,
+			color: stroke,
+			rows: [["Value", Tally.format(d.value)]]
+		});
+		const levels = items.filter((d) => d.level !== null);
+		const rules = ctx.marks("levels", "line", levels, (d) => d.name).attr("stroke", ctx.theme.ink).attr("stroke-width", 2);
+		settleMarks(ctx, rules, {
+			x1: (d) => band(d.name),
+			x2: (d) => band(d.name) + width,
+			y1: (d) => value(d.level),
+			y2: (d) => value(d.level)
+		});
+		const runs = ctx.marks("runs", "path", mark === "line" ? items : [], (d) => d.name).attr("fill", "none").attr("stroke", stroke).attr("stroke-width", 2);
+		settleMarks(ctx, runs, { d: (d) => this.trace(along, at)(d.visits) }, { d: (d) => this.trace(along, () => baseline)(d.visits) });
+		ctx.hover(runs, (d) => ({
+			title: d.name,
+			color: stroke,
+			rows: d.level === null ? [] : [["Level", Tally.format(d.level)]]
+		}));
+		const spikes = ctx.marks("spikes", "line", mark === "spike" ? visits : [], (d) => `${d.band}/${d.order}`).attr("stroke", stroke).attr("stroke-width", 2);
+		const anchor = new Map(items.map((d) => [d.name, d.level]));
+		const foot = (d) => {
+			return value(anchor.get(d.band) ?? value.domain()[0]);
+		};
+		settleMarks(ctx, spikes, {
+			x1: along,
+			x2: along,
+			y1: foot,
+			y2: at
+		}, { y2: foot });
+		ctx.hover(spikes, tip);
+		const ends = mark === "dots" ? visits : mark === "line" && width > 18 ? items.flatMap((d) => d.visits.slice(-1)) : [];
+		const dots = ctx.marks("dots", "circle", ends, (d) => `${d.band}/${d.order}`).attr("fill", stroke).attr("stroke", ctx.theme.surface).attr("stroke-width", mark === "dots" ? 1.5 : 2);
+		settleMarks(ctx, dots, {
+			cx: along,
+			cy: at,
+			r: mark === "dots" ? Math.min(4, Math.max(2.5, width / Math.max(4, visits.length / items.length) / 2)) : 4
+		}, { r: 0 });
+		ctx.hover(dots, tip);
+	}
+};
+export { CycleAggregate, CycleChart, CycleMark, CycleReference, CycleUnit };

package/dist/charts/comparison/DeviationChart.js

@@ -0,0 +1,137 @@
+import { ChartFamily, DataShape, Dimension, LegendPosition, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BandValueChart } from "./BandValueChart.js";
+import { ComparisonSort, Tally } from "./Tally.js";
+import { settleMarks } from "./settleMarks.js";
+import { extent, max, mean, median } from "d3";
+// src/charts/comparison/DeviationChart.ts
+var DeviationReference = /* @__PURE__ */ function(DeviationReference) {
+	DeviationReference["Mean"] = "mean";
+	DeviationReference["Median"] = "median";
+	DeviationReference["First"] = "first";
+	return DeviationReference;
+}({});
+var DeviationUnit = /* @__PURE__ */ function(DeviationUnit) {
+	DeviationUnit["Absolute"] = "absolute";
+	DeviationUnit["Percent"] = "percent";
+	return DeviationUnit;
+}({});
+var DeviationMark = /* @__PURE__ */ function(DeviationMark) {
+	DeviationMark["Bar"] = "bar";
+	DeviationMark["Lollipop"] = "lollipop";
+	DeviationMark["Tick"] = "tick";
+	return DeviationMark;
+}({});
+/** Above or below the norm: each row's distance from a mean, median or chosen first row. */
+var DeviationChart = class extends BandValueChart {
+	static meta = {
+		id: "comparison-deviation",
+		name: "Deviation chart",
+		family: ChartFamily.Comparison,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots how far each category sits above or below a reference, with direction shown by side and colour.",
+		tags: [
+			"diverging",
+			"variance",
+			"above below",
+			"surplus deficit"
+		],
+		sample: (seed) => SampleData.categories(seed, 10, 1),
+		variants: {
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			reference: [
+				"mean",
+				"median",
+				"first"
+			],
+			unit: ["absolute", "percent"],
+			mark: [
+				"bar",
+				"lollipop",
+				"tick"
+			],
+			sort: [ComparisonSort.Descending, ComparisonSort.Input]
+		}
+	};
+	defaults() {
+		return {
+			legend: LegendPosition.None,
+			category: "category",
+			value: "value",
+			orientation: Orientation.Horizontal,
+			reference: "mean",
+			unit: "absolute",
+			mark: "bar",
+			sort: ComparisonSort.Descending
+		};
+	}
+	bandPadding() {
+		return .22;
+	}
+	bandLayout() {
+		const { data, category, value, reference, unit, sort } = this.options;
+		const rows = Tally.group(data, category, value).map((tally) => ({
+			name: tally.key,
+			raw: tally.mean
+		}));
+		const raws = rows.map((d) => d.raw);
+		const base = reference === "first" ? raws[0] ?? 0 : reference === "median" ? median(raws) ?? 0 : mean(raws) ?? 0;
+		const gap = (raw) => unit === "percent" ? base ? (raw - base) / Math.abs(base) * 100 : 0 : raw - base;
+		const items = Tally.sorted(rows.map((d) => ({
+			...d,
+			gap: gap(d.raw)
+		})), sort, (d) => d.gap, (d) => d.name);
+		const [low = 0, high = 0] = extent(items, (d) => d.gap);
+		const room = (high - low) * .16;
+		return {
+			bands: items.map((d) => d.name),
+			items,
+			values: [Math.min(0, low - room), Math.max(0, high + room)]
+		};
+	}
+	plotBands(ctx, { items, band, mid, value }) {
+		const { mark, unit } = this.options;
+		const reach = max(items, (d) => Math.abs(d.gap)) || 1;
+		const tone = (d) => d.gap === 0 ? ctx.theme.inkMuted : ctx.palette.diverging(-Math.sign(d.gap) * (.55 + .45 * Math.abs(d.gap) / reach));
+		const along = (d) => mid(d.name);
+		const zero = () => value(0);
+		const at = (d) => value(d.gap);
+		const width = band.bandwidth();
+		const suffix = unit === "percent" ? "%" : "";
+		const tip = (d) => ({
+			title: d.name,
+			color: tone(d),
+			rows: [["Value", Tally.format(d.raw)], ["Deviation", `${d.gap > 0 ? "+" : ""}${Tally.format(d.gap)}${suffix}`]]
+		});
+		const bars = ctx.marks("bars", "rect", mark === "bar" ? items : [], (d) => d.name).attr("fill", tone).attr("rx", Math.min(4, width / 2));
+		settleMarks(ctx, bars, this.span(along, width, zero, at), this.span(along, width, zero, zero), 25);
+		ctx.hover(bars, tip);
+		const stems = ctx.marks("stems", "line", mark === "lollipop" ? items : [], (d) => d.name).attr("stroke", tone).attr("stroke-width", 2);
+		settleMarks(ctx, stems, this.rule(along, zero, at), this.rule(along, zero, zero), 25);
+		ctx.hover(stems, tip);
+		const dots = ctx.marks("dots", "circle", mark === "lollipop" ? items : [], (d) => d.name).attr("fill", tone).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		settleMarks(ctx, dots, {
+			...this.spot(along, at),
+			r: 5.5
+		}, {
+			...this.spot(along, zero),
+			r: 0
+		}, 25);
+		ctx.hover(dots, tip);
+		const ticks = ctx.marks("ticks", "rect", mark === "tick" ? items : [], (d) => d.name).attr("fill", tone).attr("rx", 1.5);
+		settleMarks(ctx, ticks, this.span(along, width, (d) => at(d) - 2, (d) => at(d) + 2), this.span(along, width, (d) => zero() - 2, (d) => zero() + 2), 25);
+		ctx.hover(ticks, tip);
+		const [lowest, highest] = extent(items, (d) => d.gap);
+		const extremes = items.filter((d) => d.gap === lowest || d.gap === highest).filter((d, i, all) => d.gap !== 0 && all.findIndex((e) => e.gap === d.gap) === i);
+		const texts = ctx.text(ctx.marks("extremes", "text", extremes, (d) => d.name), 11, "ink").text((d) => `${d.gap > 0 ? "+" : ""}${Tally.format(Math.round(d.gap))}${suffix}`).attr("text-anchor", (d) => this.vertical ? "middle" : d.gap > 0 ? "start" : "end");
+		settleMarks(ctx, texts, this.vertical ? {
+			x: along,
+			y: (d) => at(d) + (d.gap > 0 ? -7 : 15)
+		} : {
+			y: (d) => along(d) + 4,
+			x: (d) => at(d) + (d.gap > 0 ? 7 : -7)
+		});
+	}
+};
+export { DeviationChart, DeviationMark, DeviationReference, DeviationUnit };