@voila.dev/chart 4.0.0

package/src/core/marks/stats/histogram.ts

@@ -0,0 +1,108 @@
+import { isPlaceable, numericValue, readChannel } from "#/core/channel.ts";
+import { rectY } from "#/core/marks/rect.ts";
+import type { ChartMarkOptions } from "#/core/marks/shared.ts";
+import { tickStep } from "#/core/ticks.ts";
+import type { ChartAccessor, ChartMark, ChartValue } from "#/core/types.ts";
+
+export interface HistogramOptions<TDatum> extends ChartMarkOptions<TDatum> {
+	readonly x: ChartAccessor<TDatum, ChartValue>;
+	/** About how many bins: the edges land on round numbers, so the count is approximate. */
+	readonly bins?: number;
+	readonly fill?: string;
+	/** Each bin's share of the total instead of its count. */
+	readonly normalize?: boolean;
+}
+
+export interface Bin {
+	readonly x1: number;
+	readonly x2: number;
+	readonly count: number;
+	readonly series?: ChartValue;
+}
+
+/** Round-edged bins over the values' extent, every value in exactly one. */
+export function binValues(
+	values: ReadonlyArray<number>,
+	target: number,
+): ReadonlyArray<{ x1: number; x2: number }> {
+	const finite = values.filter(Number.isFinite);
+	if (finite.length === 0) {
+		return [];
+	}
+	const low = Math.min(...finite);
+	const high = Math.max(...finite);
+	const step = tickStep(low, high, target) || 1;
+	const first = Math.floor(low / step) * step;
+	const count = Math.max(
+		1,
+		Math.ceil((high - first) / step + (high === first ? 1 : 0)),
+	);
+	return Array.from({ length: count }, (_unused, index) => ({
+		x1: first + index * step,
+		x2: first + (index + 1) * step,
+	}));
+}
+
+const DEFAULT_BINS = 20;
+
+/**
+ * Counts per bin, as touching rectangles over a continuous x. With a color
+ * channel the series stack inside each bin.
+ */
+export function histogram<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: HistogramOptions<TDatum>,
+): ChartMark {
+	const xs = readChannel(data, options.x).map(numericValue);
+	const colors = readChannel(data, options.color);
+	const edges = binValues(
+		xs.filter((value): value is number => value !== undefined),
+		options.bins ?? DEFAULT_BINS,
+	);
+	const seriesValues =
+		options.color === undefined
+			? [undefined]
+			: [
+					...new Map(
+						colors.filter(isPlaceable).map((value) => [String(value), value]),
+					).values(),
+				];
+	const total = xs.filter((value) => value !== undefined).length || 1;
+	const bins: Bin[] = [];
+	for (const series of seriesValues) {
+		for (const [binIndex, edge] of edges.entries()) {
+			const last = binIndex === edges.length - 1;
+			let count = 0;
+			for (const [index, x] of xs.entries()) {
+				const inSeries =
+					series === undefined || String(colors[index]) === String(series);
+				if (
+					inSeries &&
+					x !== undefined &&
+					x >= edge.x1 &&
+					(x < edge.x2 || (last && x <= edge.x2))
+				) {
+					count += 1;
+				}
+			}
+			bins.push({
+				...edge,
+				count: options.normalize ? count / total : count,
+				series,
+			});
+		}
+	}
+	return rectY(bins, {
+		id: options.id,
+		label: options.label,
+		tip: options.tip,
+		opacity: options.opacity,
+		fill: options.fill,
+		x1: (bin) => bin.x1,
+		x2: (bin) => bin.x2,
+		y: (bin) => bin.count,
+		...(options.color === undefined
+			? {}
+			: { color: (bin: Bin) => bin.series as ChartValue }),
+	});
+}

package/src/core/marks/stats/regression.ts

@@ -0,0 +1,108 @@
+import { isPlaceable, numericValue, readChannel } from "#/core/channel.ts";
+import { markId, paint } from "#/core/marks/shared.ts";
+import { linearFit } from "#/core/marks/stats/statistics.ts";
+import { areaPath, linePath } from "#/core/paths.ts";
+import { toNumber } from "#/core/scales/continuous.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface RegressionOptions<TDatum> {
+	readonly id?: string;
+	readonly x: ChartAccessor<TDatum, ChartValue>;
+	readonly y: ChartAccessor<TDatum, ChartValue>;
+	readonly stroke?: string;
+	/** Shade the 95 % confidence band of the fitted mean. */
+	readonly band?: boolean;
+	readonly label?: string;
+}
+
+const BAND_SAMPLES = 24;
+
+/** The least-squares line through x and y, and how sure it is. Drawn over a scatter. */
+export function regressionY<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: RegressionOptions<TDatum>,
+): ChartMark {
+	const pairs = readChannel(data, options.x)
+		.map((x, index) => ({
+			x,
+			y: numericValue(readChannel(data, options.y)[index]),
+		}))
+		.filter(
+			(pair): pair is { x: ChartValue; y: number } =>
+				isPlaceable(pair.x) && pair.y !== undefined,
+		);
+	const xs = pairs.map((pair) => toNumber(pair.x));
+	const fit = linearFit(
+		xs,
+		pairs.map((pair) => pair.y),
+	);
+	const dates = pairs.some((pair) => pair.x instanceof Date);
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		channels: {
+			x: { values: pairs.map((pair) => pair.x) },
+			y: { values: pairs.map((pair) => pair.y) },
+		},
+		render(context) {
+			const id = markId(options.id, "regressionY", context);
+			const { x: xScale, y: yScale } = context.scales;
+			if (
+				fit === undefined ||
+				xScale === undefined ||
+				yScale === undefined ||
+				xs.length === 0
+			) {
+				return { nodes: [] };
+			}
+			const low = Math.min(...xs);
+			const high = Math.max(...xs);
+			const at = Array.from(
+				{ length: BAND_SAMPLES },
+				(_unused, index) => low + ((high - low) * index) / (BAND_SAMPLES - 1),
+			);
+			const place = (x: number) => xScale.map(dates ? new Date(x) : x);
+			const stroke = options.stroke ?? context.theme.foreground;
+			const nodes: SceneNode[] = [];
+			if (options.band !== false) {
+				nodes.push({
+					kind: "path",
+					key: `${id}:band`,
+					role: "mark",
+					d: areaPath(
+						at.map((x) => ({
+							x: place(x),
+							y: yScale.map(fit.intercept + fit.slope * x + fit.margin(x)),
+						})),
+						at.map((x) => ({
+							x: place(x),
+							y: yScale.map(fit.intercept + fit.slope * x - fit.margin(x)),
+						})),
+					),
+					paint: { fill: stroke, fillOpacity: 0.12 },
+				});
+			}
+			nodes.push({
+				kind: "path",
+				key: `${id}:line`,
+				role: "mark",
+				d: linePath([
+					{ x: place(low), y: yScale.map(fit.intercept + fit.slope * low) },
+					{ x: place(high), y: yScale.map(fit.intercept + fit.slope * high) },
+				]),
+				paint: paint({ fill: "none", stroke, strokeWidth: 2 }),
+			});
+			return {
+				nodes,
+				legend: options.label
+					? [{ key: id, label: options.label, color: stroke, shape: "line" }]
+					: [],
+			};
+		},
+	};
+}

package/src/core/marks/stats/statistics.ts

@@ -0,0 +1,153 @@
+/**
+ * The few statistics the statistical marks need, written out: quantiles,
+ * kernel density, least squares. Each is a handful of lines, which is less to
+ * carry than a dependency.
+ */
+
+/** Linear-interpolated quantile of sorted values (the R-7 / Excel definition). */
+export function quantile(sorted: ReadonlyArray<number>, p: number): number {
+	if (sorted.length === 0) {
+		return Number.NaN;
+	}
+	const position = (sorted.length - 1) * p;
+	const below = Math.floor(position);
+	const above = Math.ceil(position);
+	return sorted[below] + (sorted[above] - sorted[below]) * (position - below);
+}
+
+export interface BoxSummary {
+	readonly min: number;
+	readonly q1: number;
+	readonly median: number;
+	readonly q3: number;
+	readonly max: number;
+	/** Whisker ends: the furthest values within 1.5 IQR of the box. */
+	readonly low: number;
+	readonly high: number;
+	readonly outliers: ReadonlyArray<number>;
+	readonly count: number;
+}
+
+const TUKEY_FENCE = 1.5;
+
+export function boxSummary(
+	values: ReadonlyArray<number>,
+): BoxSummary | undefined {
+	const sorted = values
+		.filter(Number.isFinite)
+		.sort((left, right) => left - right);
+	if (sorted.length === 0) {
+		return undefined;
+	}
+	const q1 = quantile(sorted, 0.25);
+	const q3 = quantile(sorted, 0.75);
+	const fence = (q3 - q1) * TUKEY_FENCE;
+	const inside = sorted.filter(
+		(value) => value >= q1 - fence && value <= q3 + fence,
+	);
+	return {
+		min: sorted[0],
+		q1,
+		median: quantile(sorted, 0.5),
+		q3,
+		max: sorted[sorted.length - 1],
+		low: inside[0] ?? q1,
+		high: inside[inside.length - 1] ?? q3,
+		outliers: sorted.filter(
+			(value) => value < q1 - fence || value > q3 + fence,
+		),
+		count: sorted.length,
+	};
+}
+
+/** Silverman's rule of thumb: a bandwidth that suits most unimodal data. */
+export function silvermanBandwidth(values: ReadonlyArray<number>): number {
+	const count = values.length;
+	if (count < 2) {
+		return 1;
+	}
+	const mean = values.reduce((sum, value) => sum + value, 0) / count;
+	const deviation = Math.sqrt(
+		values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / (count - 1),
+	);
+	const sorted = [...values].sort((left, right) => left - right);
+	const spread = Math.min(
+		deviation,
+		(quantile(sorted, 0.75) - quantile(sorted, 0.25)) / 1.34,
+	);
+	return 0.9 * (spread || deviation || 1) * count ** -0.2;
+}
+
+const GAUSSIAN = 1 / Math.sqrt(2 * Math.PI);
+
+/** Gaussian kernel density of `values`, sampled at `at`. */
+export function kernelDensity(
+	values: ReadonlyArray<number>,
+	at: ReadonlyArray<number>,
+	bandwidth = silvermanBandwidth(values),
+): ReadonlyArray<number> {
+	const count = values.length;
+	return at.map((x) => {
+		let sum = 0;
+		for (const value of values) {
+			const u = (x - value) / bandwidth;
+			sum += GAUSSIAN * Math.exp(-0.5 * u * u);
+		}
+		return count === 0 ? 0 : sum / (count * bandwidth);
+	});
+}
+
+/** `count` evenly spaced samples over `[low, high]`. */
+export function samples(low: number, high: number, count: number): number[] {
+	if (count < 2 || low === high) {
+		return [low];
+	}
+	return Array.from(
+		{ length: count },
+		(_unused, index) => low + ((high - low) * index) / (count - 1),
+	);
+}
+
+export interface LinearFit {
+	readonly slope: number;
+	readonly intercept: number;
+	/** Half-width of the 95 % confidence band of the mean at `x`. */
+	readonly margin: (x: number) => number;
+}
+
+/** 1.96: a normal approximation of Student's t, fine past a dozen points. */
+const Z_95 = 1.96;
+
+export function linearFit(
+	xs: ReadonlyArray<number>,
+	ys: ReadonlyArray<number>,
+): LinearFit | undefined {
+	const count = xs.length;
+	if (count < 2) {
+		return undefined;
+	}
+	const meanX = xs.reduce((sum, x) => sum + x, 0) / count;
+	const meanY = ys.reduce((sum, y) => sum + y, 0) / count;
+	let sxx = 0;
+	let sxy = 0;
+	for (let index = 0; index < count; index += 1) {
+		sxx += (xs[index] - meanX) ** 2;
+		sxy += (xs[index] - meanX) * (ys[index] - meanY);
+	}
+	if (sxx === 0) {
+		return undefined;
+	}
+	const slope = sxy / sxx;
+	const intercept = meanY - slope * meanX;
+	let residuals = 0;
+	for (let index = 0; index < count; index += 1) {
+		residuals += (ys[index] - (intercept + slope * xs[index])) ** 2;
+	}
+	const standardError = count > 2 ? Math.sqrt(residuals / (count - 2)) : 0;
+	return {
+		slope,
+		intercept,
+		margin: (x) =>
+			Z_95 * standardError * Math.sqrt(1 / count + (x - meanX) ** 2 / sxx),
+	};
+}

package/src/core/marks/stats/waffle.ts

@@ -0,0 +1,141 @@
+import {
+	channelLabel,
+	isPlaceable,
+	numericValue,
+	readChannel,
+} from "#/core/channel.ts";
+import {
+	type ChartMarkOptions,
+	colorChannel,
+	markId,
+	paint,
+	seriesResolver,
+} from "#/core/marks/shared.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartPoint,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface WaffleOptions<TDatum> extends ChartMarkOptions<TDatum> {
+	readonly x: ChartAccessor<TDatum, ChartValue>;
+	readonly y: ChartAccessor<TDatum, ChartValue>;
+	/** What one cell stands for. */
+	readonly unit?: number;
+	/** Cells across a band. */
+	readonly columns?: number;
+	readonly fill?: string;
+}
+
+const DEFAULT_COLUMNS = 10;
+const CELL_GAP = 1.5;
+
+/**
+ * Bars made of countable cells: "12 missions" reads as twelve squares. A
+ * row of `columns` cells is `columns × unit` on the y axis, so the waffle
+ * still reads against it; series continue one another inside a column.
+ */
+export function waffleY<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: WaffleOptions<TDatum>,
+): ChartMark {
+	const xs = readChannel(data, options.x);
+	const values = readChannel(data, options.y).map(numericValue);
+	const colors = colorChannel(data, options);
+	const unit = options.unit ?? 1;
+	const columns = options.columns ?? DEFAULT_COLUMNS;
+	const totals = new Map<string, number>();
+	const offsets = xs.map((x, index) => {
+		if (!isPlaceable(x)) return 0;
+		const key = categoryKey(x);
+		const before = totals.get(key) ?? 0;
+		totals.set(
+			key,
+			before + Math.max(0, Math.round((values[index] ?? 0) / unit)),
+		);
+		return before;
+	});
+	const tallest = Math.max(0, ...totals.values());
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		focusOrder: "x",
+		channels: {
+			x: {
+				values: xs.filter(isPlaceable),
+				discrete: "band",
+				label: channelLabel(options.x),
+			},
+			y: {
+				values: [0, Math.ceil(tallest / columns) * columns * unit],
+				includeZero: true,
+				label: channelLabel(options.y) ?? options.label,
+			},
+			color: colors.channel,
+		},
+		render(context) {
+			const id = markId(options.id, "waffleY", context);
+			const { x: xScale, y: yScale } = context.scales;
+			if (xScale === undefined || yScale === undefined) {
+				return { nodes: [] };
+			}
+			const seriesOf = seriesResolver(
+				colors.values,
+				{ ...options, fixedColor: options.fill },
+				id,
+				context,
+			);
+			const cellWidth = xScale.bandwidth / columns;
+			const rowHeight = Math.abs(yScale.map(columns * unit) - yScale.map(0));
+			const nodes: SceneNode[] = [];
+			const points: ChartPoint[] = [];
+			for (const [index, x] of xs.entries()) {
+				const value = values[index];
+				if (!isPlaceable(x) || value === undefined) continue;
+				const series = seriesOf(index);
+				const cells = Math.max(0, Math.round(value / unit));
+				let top = Number.POSITIVE_INFINITY;
+				for (let cell = 0; cell < cells; cell += 1) {
+					const position = offsets[index] + cell;
+					const column = position % columns;
+					const row = Math.floor(position / columns);
+					const y = yScale.map((row + 1) * columns * unit);
+					top = Math.min(top, y);
+					nodes.push({
+						kind: "rect",
+						key: `${id}:${index}:${cell}`,
+						series: series.key,
+						role: "mark",
+						x: xScale.map(x) + column * cellWidth + CELL_GAP / 2,
+						y: y + CELL_GAP / 2,
+						width: Math.max(0, cellWidth - CELL_GAP),
+						height: Math.max(0, rowHeight - CELL_GAP),
+						corners: [1.5, 1.5, 1.5, 1.5],
+						paint: paint({ fill: series.color, opacity: options.opacity }),
+					});
+				}
+				if (options.tip !== false) {
+					points.push({
+						key: `${id}:${index}`,
+						markId: id,
+						index,
+						datum: data[index],
+						x: xScale.center(x),
+						y: Number.isFinite(top) ? top : yScale.map(0),
+						xValue: x,
+						yValue: value,
+						series: series.key,
+						seriesLabel: series.label,
+						color: series.color,
+						title: context.formatX(x),
+						value: context.formatY(value),
+					});
+				}
+			}
+			return { nodes, points };
+		},
+	};
+}

package/src/core/marks/text.ts

@@ -0,0 +1,97 @@
+import { channelLabel, isPlaceable, readChannel } from "#/core/channel.ts";
+import { markId, paint, valueOn } from "#/core/marks/shared.ts";
+import type {
+	ChartAccessor,
+	ChartMark,
+	ChartTextPaint,
+	ChartValue,
+	SceneNode,
+} from "#/core/types.ts";
+
+export interface TextOptions<TDatum> {
+	readonly id?: string;
+	readonly x?: ChartAccessor<TDatum, ChartValue>;
+	readonly y?: ChartAccessor<TDatum, ChartValue>;
+	readonly text: ChartAccessor<TDatum, unknown>;
+	/** Pixel offsets from the anchor. */
+	readonly dx?: number;
+	readonly dy?: number;
+	readonly fill?: string;
+	readonly fontSize?: number;
+	readonly fontWeight?: number;
+	readonly textAnchor?: ChartTextPaint["textAnchor"];
+	readonly baseline?: ChartTextPaint["baseline"];
+	readonly opacity?: number;
+}
+
+/** A label per datum: values on bars, names on points, annotations. */
+export function text<TDatum>(
+	data: ReadonlyArray<TDatum>,
+	options: TextOptions<TDatum>,
+): ChartMark {
+	const xs = readChannel(data, options.x);
+	const ys = readChannel(data, options.y);
+	const texts = readChannel(data, options.text);
+	return {
+		id: options.id,
+		coordinate: "cartesian",
+		channels: {
+			...(options.x === undefined
+				? {}
+				: {
+						x: {
+							values: xs.filter(isPlaceable),
+							label: channelLabel(options.x),
+						},
+					}),
+			...(options.y === undefined
+				? {}
+				: {
+						y: {
+							values: ys.filter(isPlaceable),
+							label: channelLabel(options.y),
+						},
+					}),
+		},
+		render(context) {
+			const id = markId(options.id, "text", context);
+			const { scales, plot, theme } = context;
+			const nodes: SceneNode[] = [];
+			for (const [index, content] of texts.entries()) {
+				const xValue = scales.x && valueOn(scales.x, xs[index]);
+				const yValue = scales.y && valueOn(scales.y, ys[index]);
+				const x =
+					scales.x && xValue !== undefined
+						? scales.x.center(xValue)
+						: plot.x + plot.width / 2;
+				const y =
+					scales.y && yValue !== undefined
+						? scales.y.center(yValue)
+						: plot.y + plot.height / 2;
+				if (content === undefined || content === null || content === "") {
+					continue;
+				}
+				nodes.push({
+					kind: "text",
+					key: `${id}:${index}`,
+					role: "label",
+					x: x + (options.dx ?? 0),
+					y: y + (options.dy ?? 0),
+					text:
+						typeof content === "number"
+							? context.formatY(content)
+							: String(content),
+					paint: paint({
+						fill: options.fill ?? theme.foreground,
+						opacity: options.opacity,
+						fontSize: options.fontSize ?? theme.fontSize,
+						fontWeight: options.fontWeight,
+						textAnchor: options.textAnchor ?? "middle",
+						baseline: options.baseline ?? "middle",
+					}),
+				});
+			}
+			return { nodes };
+		},
+	};
+}