@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/signals/SpectrumChart.js

@@ -0,0 +1,160 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SignalDsp } from "./SignalDsp.js";
+import { SignalAmplitude, SignalFrequencyScale, SignalWindow } from "./SignalEnums.js";
+import { SignalSamples } from "./SignalSamples.js";
+import { SignalScales } from "./SignalScales.js";
+import { SpectralChart } from "./SpectralChart.js";
+import { area, max, scaleLinear } from "d3";
+// src/charts/signals/SpectrumChart.ts
+var SpectrumMark = /* @__PURE__ */ function(SpectrumMark) {
+	SpectrumMark["Line"] = "line";
+	SpectrumMark["Area"] = "area";
+	SpectrumMark["Bands"] = "third-octave-bands";
+	return SpectrumMark;
+}({});
+/** Finds which frequencies a signal contains, with the windowing and scale choices of a bench analyser. */
+var SpectrumChart = class extends SpectralChart {
+	static meta = {
+		id: "signal-spectrum",
+		name: "Frequency spectrum",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Transforms time samples with an FFT to show how much of each frequency a signal contains.",
+		tags: [
+			"fft",
+			"analyser",
+			"rta",
+			"dbfs"
+		],
+		sample: (seed) => SignalSamples.notes(seed),
+		variants: {
+			window: [
+				SignalWindow.Hann,
+				SignalWindow.Blackman,
+				SignalWindow.Rectangular
+			],
+			amplitude: Object.values(SignalAmplitude),
+			frequency: Object.values(SignalFrequencyScale),
+			mark: Object.values(SpectrumMark)
+		}
+	};
+	constructor(options) {
+		super({
+			yLabel: options.amplitude === SignalAmplitude.Linear ? "Amplitude" : "Level (dB)",
+			...options
+		});
+	}
+	defaults() {
+		return {
+			...super.defaults(),
+			window: SignalWindow.Hann,
+			amplitude: SignalAmplitude.Decibel,
+			mark: "line",
+			floor: -90
+		};
+	}
+	get decibel() {
+		return this.options.amplitude === SignalAmplitude.Decibel;
+	}
+	traces(ctx) {
+		return this.channels.map((channel) => {
+			const spectrum = SignalDsp.spectrum(channel.v, channel.rate, this.options.window);
+			return {
+				name: channel.name,
+				color: ctx.palette.color(channel.name),
+				spectrum,
+				level: spectrum.mag.map((mag) => this.decibel ? SignalDsp.decibel(mag, 1, this.options.floor) : mag)
+			};
+		});
+	}
+	scales(ctx) {
+		const traces = this.traces(ctx), { width, height } = ctx.plot;
+		const x = this.frequencyAxis(traces.find((trace) => trace.spectrum.freq.length)?.spectrum.freq ?? [], width);
+		const top = (this.options.mark === "third-octave-bands" ? max(this.bands(traces, x.domain()[1]), (band) => band.level) : void 0) ?? max(traces, (trace) => max(trace.level)) ?? 1;
+		return {
+			x,
+			y: scaleLinear(this.decibel ? [this.options.floor, Math.max(top, this.options.floor + 10)] : [0, top || 1], [height, 0]).nice(5)
+		};
+	}
+	/** Third-octave bands: energy summed per band, as a real-time analyser shows it. */
+	bands(traces, top) {
+		return traces.flatMap((trace, slot) => {
+			const out = [];
+			for (let band = -20; band < 44; band++) {
+				const centre = 1e3 * 2 ** (band / 3), lo = centre * 2 ** (-1 / 6), hi = centre * 2 ** (1 / 6);
+				if (hi > top) break;
+				const energy = trace.spectrum.mag.reduce((sum, mag, i) => trace.spectrum.freq[i] >= lo && trace.spectrum.freq[i] < hi ? sum + mag * mag : sum, 0);
+				if (energy > 0) out.push({
+					key: `${trace.name}${band}`,
+					name: trace.name,
+					color: trace.color,
+					lo,
+					hi,
+					slot,
+					level: this.decibel ? SignalDsp.decibel(Math.sqrt(energy), 1, this.options.floor) : Math.sqrt(energy)
+				});
+			}
+			return out;
+		});
+	}
+	plotMarks(ctx, { x, y }) {
+		const traces = this.traces(ctx), { mark } = this.options, baseline = y.range()[0];
+		const points = (trace) => trace.level.map((level, i) => [trace.spectrum.freq[i], level]).filter(([freq]) => freq >= x.domain()[0]);
+		if (mark === "third-octave-bands") {
+			const top = x.domain()[1];
+			const bands = this.bands(traces, top), slots = traces.length || 1, left = (band) => x(Math.max(band.lo, x.domain()[0] || .001));
+			const wide = (band) => Math.max(2, (x(band.hi) - left(band)) / slots - 2);
+			const bars = ctx.marks("bands", "rect", bands, (band) => band.key).attr("fill", (band) => band.color).attr("rx", (band) => Math.min(4, wide(band) / 2));
+			ctx.set(bars, {
+				x: (band) => left(band) + band.slot * (x(band.hi) - left(band)) / slots,
+				width: wide,
+				y: (band) => y(band.level),
+				height: (band) => Math.max(0, baseline - y(band.level))
+			}, {
+				y: baseline,
+				height: 0
+			}, 6);
+			ctx.hover(bars, (band) => ({
+				title: `${SignalScales.hertz(Math.sqrt(band.lo * band.hi))} Hz band`,
+				color: band.color,
+				rows: [[band.name, SignalScales.number(band.level)]]
+			}));
+			return;
+		}
+		if (mark === "area") {
+			const shape = area().x((point) => x(point[0])).y0(baseline).y1((point) => y(point[1]));
+			this.fill(ctx, "fill", traces, (trace) => trace.name, (trace) => shape(points(trace)) ?? "", (trace) => trace.color, .28);
+		}
+		this.stroke(ctx, "trace", traces, (trace) => trace.name, (trace) => this.path(points(trace), x, y), (trace) => trace.color, 1.5);
+		this.mark(ctx, traces, x, y);
+		this.probe(ctx, (px) => {
+			const freq = x.invert(px);
+			if (!traces[0]?.spectrum.freq.length) return null;
+			const rows = traces.map((trace) => [trace.name, SignalScales.number(SignalDsp.interpolate(trace.spectrum.freq, trace.level, freq))]);
+			return {
+				x: px,
+				tip: {
+					title: `${SignalScales.hertz(freq)} Hz`,
+					rows
+				},
+				datum: { frequency: freq }
+			};
+		});
+	}
+	/** Labels the strongest peak of the first channel. */
+	mark(ctx, traces, x, y) {
+		const trace = traces[0];
+		if (!trace?.level.length) return;
+		const index = trace.level.indexOf(Math.max(...trace.level)), freq = trace.spectrum.freq[index], px = x(freq), py = y(trace.level[index]);
+		const dots = ctx.marks("peak", "circle", [0]).attr("fill", trace.color).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: px,
+			cy: py,
+			r: 4
+		}, { r: 0 });
+		const flip = px > ctx.plot.width - 70;
+		ctx.text(ctx.marks("peak-label", "text", [0]).attr("x", px + (flip ? -8 : 8)).attr("y", Math.max(11, py + 3)).attr("text-anchor", flip ? "end" : "start").text(`${SignalScales.hertz(freq)} Hz`), 11, "ink");
+	}
+};
+export { SpectrumChart, SpectrumMark };

package/dist/charts/signals/StemSignalChart.js

@@ -0,0 +1,172 @@
+import { ChartFamily, DataShape, Dimension, Orientation, SymbolKind } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SignalChart } from "./SignalChart.js";
+import { SignalLayout } from "./SignalEnums.js";
+import { SignalSamples } from "./SignalSamples.js";
+import { SignalScales } from "./SignalScales.js";
+import { scaleLinear, symbol } from "d3";
+// src/charts/signals/StemSignalChart.ts
+var StemReconstruction = /* @__PURE__ */ function(StemReconstruction) {
+	StemReconstruction["None"] = "none";
+	StemReconstruction["Hold"] = "zero-order-hold";
+	StemReconstruction["Sinc"] = "sinc";
+	return StemReconstruction;
+}({});
+var sinc = (x) => Math.abs(x) < 1e-9 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);
+/** Discrete-time samples drawn as stems, the textbook view of a sequence x[n]. */
+var StemSignalChart = class extends SignalChart {
+	static meta = {
+		id: "signal-stem",
+		name: "Stem plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Draws each sample of a discrete-time signal as a stem from zero, optionally with its reconstruction.",
+		tags: [
+			"discrete",
+			"lollipop",
+			"sequence",
+			"sampling"
+		],
+		sample: (seed) => SignalSamples.noise(seed, 32, 2).flatMap(({ name, noise }, channel) => noise.map((step, i) => ({
+			t: i,
+			series: name,
+			value: +((Math.sin(i / 2.6 + channel) * .8 + .35 * Math.sin(i / 1.1)) * Math.exp(-i / 40) + step * .04).toFixed(4)
+		}))),
+		variants: {
+			orientation: Object.values(Orientation),
+			marker: [
+				SymbolKind.Circle,
+				SymbolKind.Square,
+				SymbolKind.Diamond
+			],
+			layout: Object.values(SignalLayout),
+			reconstruction: Object.values(StemReconstruction)
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			xLabel: "Sample n",
+			yLabel: "x[n]",
+			orientation: Orientation.Vertical,
+			marker: SymbolKind.Circle,
+			layout: SignalLayout.Lanes,
+			reconstruction: "none",
+			limit: 64
+		};
+	}
+	constructor(options) {
+		super(options.orientation === Orientation.Horizontal ? {
+			xLabel: "x[n]",
+			yLabel: "Sample n",
+			...options
+		} : options);
+	}
+	along = 300;
+	get vertical() {
+		return this.options.orientation === Orientation.Vertical;
+	}
+	get laned() {
+		return this.options.layout === SignalLayout.Lanes && this.channels.length > 1;
+	}
+	/** Stems kept so that each has 10px of room along the time axis. */
+	thinned(channel) {
+		const room = Math.max(4, Math.floor(this.along / 10)), stride = Math.max(1, Math.ceil(channel.t.length / Math.min(this.options.limit, room)));
+		return {
+			t: channel.t.filter((_, i) => i % stride === 0),
+			v: channel.v.filter((_, i) => i % stride === 0)
+		};
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot, along = this.along = this.vertical ? width : height, across = this.vertical ? height : width;
+		const [lo, hi] = this.span, pad = (hi - lo) * .03, time = scaleLinear([lo - pad, hi + pad], [0, along]), peak = this.peak;
+		const level = this.laned ? this.lanes(across) : scaleLinear([-peak * 1.15, peak * 1.15], this.vertical ? [across, 0] : [0, across]).nice(4);
+		return this.vertical ? {
+			x: time,
+			y: level
+		} : {
+			x: level,
+			y: time
+		};
+	}
+	origin(channel, level) {
+		if (!this.laned) return level;
+		const band = level, top = band(channel.name), size = band.bandwidth();
+		const peak = this.peak * 1.1;
+		return this.vertical ? scaleLinear([-peak, peak], [top + size, top]) : scaleLinear([-peak, peak], [top, top + size]);
+	}
+	plotMarks(ctx, { x, y }) {
+		const vertical = this.vertical, time = vertical ? x : y, level = vertical ? y : x, count = this.channels.length, marker = this.options.marker;
+		const step = (this.channels[0] ? this.thinned(this.channels[0]) : { t: [0, 1] }).t;
+		const pitch = step.length > 1 ? Math.abs(time(step[1]) - time(step[0])) : 12;
+		const stems = this.channels.flatMap((channel, c) => {
+			const { t, v } = this.thinned(channel), origin = this.origin(channel, level);
+			const shift = this.laned ? 0 : (c - (count - 1) / 2) * Math.min(6, pitch / count);
+			return t.map((at, i) => ({
+				key: `${channel.name}${i}`,
+				channel,
+				t: at,
+				value: v[i],
+				origin,
+				shift
+			}));
+		});
+		const along = (stem) => time(stem.t) + stem.shift;
+		const reach = this.channels.map((channel) => this.origin(channel, level));
+		if (this.laned) ctx.marks("zero", "line", this.channels, (channel) => channel.name).attr(vertical ? "x1" : "y1", 0).attr(vertical ? "x2" : "y2", vertical ? ctx.plot.width : ctx.plot.height).attr(vertical ? "y1" : "x1", (_, i) => reach[i](0)).attr(vertical ? "y2" : "x2", (_, i) => reach[i](0)).attr("stroke", ctx.theme.axis);
+		else this.axisLine(ctx, level(0));
+		this.rebuild(ctx, time, reach);
+		const rods = ctx.marks("stems", "line", stems, (stem) => stem.key).attr("stroke", (stem) => ctx.palette.color(stem.channel.name)).attr("stroke-width", 2);
+		const from = (stem) => stem.origin(0), to = (stem) => stem.origin(stem.value);
+		ctx.set(rods, vertical ? {
+			x1: along,
+			x2: along,
+			y1: from,
+			y2: to
+		} : {
+			y1: along,
+			y2: along,
+			x1: from,
+			x2: to
+		}, vertical ? { y2: from } : { x2: from }, 6);
+		const shape = symbol(Scales.symbol(marker), 64)();
+		const heads = ctx.marks("heads", "path", stems, (stem) => stem.key).attr("d", shape).attr("fill", (stem) => ctx.palette.color(stem.channel.name)).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		const place = (stem) => vertical ? `translate(${along(stem)},${to(stem)})` : `translate(${to(stem)},${along(stem)})`;
+		ctx.set(heads, {
+			transform: place,
+			opacity: 1
+		}, {
+			transform: (stem) => vertical ? `translate(${along(stem)},${from(stem)})` : `translate(${from(stem)},${along(stem)})`,
+			opacity: 0
+		}, 6);
+		ctx.hover(heads, (stem) => ({
+			title: `${SignalScales.number(stem.t)} s`,
+			color: ctx.palette.color(stem.channel.name),
+			rows: [[stem.channel.name, SignalScales.number(stem.value)]]
+		}));
+	}
+	axisLine(ctx, at) {
+		const vertical = this.vertical;
+		ctx.marks("zero", "line", [0]).attr("x1", vertical ? 0 : at).attr("x2", vertical ? ctx.plot.width : at).attr("y1", vertical ? at : 0).attr("y2", vertical ? at : ctx.plot.height).attr("stroke", ctx.theme.axis);
+	}
+	rebuild(ctx, time, origins) {
+		const { reconstruction } = this.options;
+		if (reconstruction === "none") return;
+		const curves = this.channels.map((channel, c) => {
+			const { t, v } = this.thinned(channel), origin = origins[c], dt = t[1] - t[0] || 1;
+			const points = reconstruction === "zero-order-hold" ? t.flatMap((at, i) => [[at, v[i]], [Math.min(at + dt, t[t.length - 1]), v[i]]]) : Array.from({ length: Math.max(1, (t.length - 1) * 5) + 1 }, (_, i) => {
+				const at = t[0] + i / 5 * dt;
+				return [at, v.reduce((sum, value, n) => sum + value * sinc((at - t[n]) / dt), 0)];
+			});
+			return {
+				name: channel.name,
+				points,
+				origin
+			};
+		});
+		const d = (curve) => this.vertical ? this.path(curve.points, time, curve.origin) : this.path(curve.points.map(([a, b]) => [b, a]), curve.origin, time);
+		this.stroke(ctx, "rebuilt", curves, (curve) => curve.name, d, (curve) => ctx.palette.color(curve.name), 1.5).attr("opacity", .55);
+	}
+};
+export { StemReconstruction, StemSignalChart };

package/dist/charts/signals/TimeDomainDiffChart.js

@@ -0,0 +1,202 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { ZoomAxis } from "../../core/ChartViewport.js";
+import { SignalChart } from "./SignalChart.js";
+import { SignalDsp } from "./SignalDsp.js";
+import { SignalSamples } from "./SignalSamples.js";
+import { SignalScales } from "./SignalScales.js";
+import { area, scaleLinear } from "d3";
+// src/charts/signals/TimeDomainDiffChart.ts
+var DiffView = /* @__PURE__ */ function(DiffView) {
+	DiffView["Panels"] = "traces-and-residual";
+	DiffView["Residual"] = "residual";
+	DiffView["Band"] = "difference-band";
+	return DiffView;
+}({});
+var DiffMetric = /* @__PURE__ */ function(DiffMetric) {
+	DiffMetric["Difference"] = "difference";
+	DiffMetric["Percent"] = "percent";
+	DiffMetric["Cumulative"] = "cumulative-error";
+	return DiffMetric;
+}({});
+var COLUMNS = 360;
+/** Compares a measured trace with a reference: where they part, by how much and in which direction. */
+var TimeDomainDiffChart = class extends SignalChart {
+	static meta = {
+		id: "signal-time-domain-diff",
+		name: "Time domain diff",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Overlays two time series and plots their residual, to show where a measured trace departs from a reference.",
+		tags: [
+			"residual",
+			"error",
+			"golden trace",
+			"regression",
+			"comparison"
+		],
+		sample: (seed) => SignalSamples.noise(seed, 1024, 2).flatMap(({ noise }, channel) => noise.map((step, i) => {
+			const t = i / 256, shape = Math.sin(2 * Math.PI * 1.1 * t) * Math.exp(-t * .25) + .4 * Math.sin(2 * Math.PI * 3.1 * t);
+			const drift = channel ? .22 * Math.sin(2 * Math.PI * .45 * (t - .035)) * Math.min(1, t / 2) + .018 * step : 0;
+			const lagged = channel ? Math.sin(2 * Math.PI * 1.1 * (t - .035)) * Math.exp(-t * .25) + .4 * Math.sin(2 * Math.PI * 3.1 * (t - .035)) : shape;
+			return {
+				t: +t.toFixed(5),
+				series: channel ? "Measured" : "Reference",
+				value: +(lagged + drift).toFixed(5)
+			};
+		})),
+		variants: {
+			view: Object.values(DiffView),
+			metric: Object.values(DiffMetric),
+			align: [true, false],
+			tolerance: [true, false]
+		},
+		valid: (values) => !(values.view === "difference-band" && (values.metric !== "difference" || values.tolerance === false)) && !(values.metric === "cumulative-error" && values.tolerance === true)
+	};
+	constructor(options) {
+		const metric = options.metric ?? "difference", view = options.view ?? "traces-and-residual";
+		super({
+			yLabel: view === "residual" ? metric === "percent" ? "Error (%)" : metric === "cumulative-error" ? "Cumulative error" : "Residual" : "Amplitude",
+			...options
+		});
+	}
+	zoomAxes() {
+		return ZoomAxis.X;
+	}
+	defaults() {
+		return {
+			...super.defaults(),
+			view: "traces-and-residual",
+			metric: "difference",
+			align: true,
+			tolerance: true
+		};
+	}
+	/** Lag of the second channel, in seconds, that best matches the first. */
+	get lag() {
+		const [a, b] = this.channels;
+		if (!this.options.align || !a || !b) return 0;
+		return SignalDsp.correlate(a.v, b.v, Math.min(64, a.v.length >> 2)).reduce((top, point) => point.value > top.value ? point : top, {
+			lag: 0,
+			value: -Infinity
+		}).lag / a.rate;
+	}
+	get samples() {
+		const [a, b] = this.channels, { metric } = this.options, lag = this.lag;
+		if (!a) return [];
+		const peak = this.peak, stride = Math.max(1, Math.floor(a.t.length / COLUMNS)), other = b ?? a;
+		let sum = 0;
+		return a.t.filter((_, i) => i % stride === 0).flatMap((t, n) => {
+			const reference = a.v[n * stride], probe = t + lag;
+			if (b && (probe < b.t[0] || probe > b.t[b.t.length - 1])) return [];
+			const measured = SignalDsp.interpolate(other.t, other.v, probe), raw = measured - reference;
+			sum += Math.abs(raw) / a.rate * stride;
+			return [{
+				t,
+				a: reference,
+				b: measured,
+				delta: metric === "percent" ? raw / peak * 100 : metric === "cumulative-error" ? sum : raw
+			}];
+		});
+	}
+	yTicks() {
+		return this.options.view === "traces-and-residual" ? 3 : 6;
+	}
+	get legended() {
+		return this.options.view !== "residual" && super.legended;
+	}
+	deltaScale(top, bottom) {
+		const reach = Math.max(1e-9, ...this.samples.map((sample) => Math.abs(sample.delta)));
+		const floor = this.options.metric === "cumulative-error" ? 0 : -reach * 1.1;
+		return scaleLinear([floor, reach * 1.1], [bottom, top]).nice(3);
+	}
+	split(height) {
+		return Math.round(height * .62);
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot, { view } = this.options, x = scaleLinear(this.span, [0, width]);
+		if (view === "residual") return {
+			x,
+			y: this.deltaScale(0, height)
+		};
+		const peak = this.peak * 1.1, bottom = view === "traces-and-residual" ? this.split(height) - 8 : height;
+		return {
+			x,
+			y: scaleLinear([-peak, peak], [bottom, 0]).nice(4)
+		};
+	}
+	residual(ctx, samples, x, y) {
+		const zero = y(0), high = ctx.palette.diverging(.85), low = ctx.palette.diverging(-.85);
+		const lobes = [{
+			key: "over",
+			keep: (value) => Math.max(0, value),
+			color: high
+		}, {
+			key: "under",
+			keep: (value) => Math.min(0, value),
+			color: low
+		}];
+		const shape = area().x((sample) => x(sample.t)).y0(zero);
+		this.fill(ctx, "residual", lobes, (lobe) => lobe.key, (lobe) => shape.y1((sample) => y(lobe.keep(sample.delta)))(samples) ?? "", (lobe) => lobe.color, .9);
+		this.rule(ctx, "zero", [0], y);
+		if (this.options.tolerance) {
+			const rms = Math.sqrt(samples.reduce((sum, sample) => sum + sample.delta ** 2, 0) / (samples.length || 1));
+			const [lo, hi] = y.domain();
+			this.rule(ctx, "tolerance", [rms, -rms].filter((value) => value >= lo && value <= hi), y, true);
+		}
+	}
+	plotMarks(ctx, { x, y }) {
+		const { view } = this.options, { width, height } = ctx.plot, samples = this.samples;
+		const names = this.channels.map((channel) => channel.name);
+		const curves = [{
+			key: "a",
+			read: (s) => s.a,
+			name: names[0]
+		}, {
+			key: "b",
+			read: (s) => s.b,
+			name: names[1] ?? names[0]
+		}];
+		const draw = () => this.stroke(ctx, "traces", curves, (curve) => curve.key, (curve) => this.path(samples.map((sample) => [sample.t, curve.read(sample)]), x, y), (curve) => ctx.palette.color(curve.name ?? "Signal"), 1.5);
+		if (view === "residual") this.residual(ctx, samples, x, y);
+		if (view === "difference-band") {
+			const lobes = [{
+				key: "over",
+				pick: Math.max,
+				color: ctx.palette.diverging(.8)
+			}, {
+				key: "under",
+				pick: Math.min,
+				color: ctx.palette.diverging(-.8)
+			}];
+			const shape = area().x((sample) => x(sample.t)).y0((sample) => y(sample.a));
+			this.fill(ctx, "between", lobes, (lobe) => lobe.key, (lobe) => shape.y1((sample) => y(lobe.pick(sample.a, sample.b)))(samples) ?? "", (lobe) => lobe.color, .75);
+			draw();
+		}
+		if (view === "traces-and-residual") {
+			draw();
+			const start = this.split(height) + 8, delta = this.deltaScale(start, height);
+			this.panelAxis(ctx, "delta-axis", delta);
+			ctx.marks("delta-grid", "line", delta.ticks(3), (tick) => tick).attr("x1", 0).attr("x2", width).attr("y1", (tick) => delta(tick)).attr("y2", (tick) => delta(tick)).attr("stroke", ctx.theme.grid);
+			const lower = ctx.nest("translate(0,0)", "lower");
+			this.residual(lower, samples, x, delta);
+		}
+		this.probe(ctx, (px) => {
+			const time = x.invert(px), near = samples.reduce((best, sample) => !best || Math.abs(sample.t - time) < Math.abs(best.t - time) ? sample : best, null);
+			if (!near) return null;
+			return {
+				x: x(near.t),
+				tip: {
+					title: `${SignalScales.number(near.t)} s`,
+					rows: [
+						[names[0] ?? "A", SignalScales.number(near.a)],
+						[names[1] ?? "B", SignalScales.number(near.b)],
+						["Residual", SignalScales.number(near.delta)]
+					]
+				},
+				datum: near
+			};
+		});
+	}
+};
+export { DiffMetric, DiffView, TimeDomainDiffChart };

package/dist/charts/signals/TimeFrequencyChart.js

@@ -0,0 +1,84 @@
+import { LegendPosition } from "../../core/enums.js";
+import { SignalChart } from "./SignalChart.js";
+import { SignalRaster } from "./SignalRaster.js";
+import { SignalScales } from "./SignalScales.js";
+import { scaleLinear } from "d3";
+// src/charts/signals/TimeFrequencyChart.ts
+var KEY = 40;
+var CELL = 3;
+/** Base for heatmaps of time against frequency or period: raster, colour key, ridge and probe. */
+var TimeFrequencyChart = class extends SignalChart {
+	get legended() {
+		return false;
+	}
+	get legendPosition() {
+		return LegendPosition.None;
+	}
+	defaults() {
+		return {
+			...super.defaults(),
+			grid: false,
+			ridge: false
+		};
+	}
+	get channel() {
+		return this.channels.find((channel) => channel.name === this.options.channel) ?? this.first;
+	}
+	/** Marks drawn above the raster and below the probe. */
+	overlay(_ctx, _axes) {}
+	scales(ctx) {
+		return {
+			x: scaleLinear(this.span, [0, Math.max(10, ctx.plot.width - KEY)]),
+			y: this.yAxis(ctx.plot.height)
+		};
+	}
+	plotMarks(ctx, axes) {
+		const field = this.field(), { x, y } = axes;
+		if (!field) return;
+		const { height } = ctx.plot, right = x.range()[1], columns = Math.floor(right / CELL), rows = Math.floor(height / CELL);
+		const color = (t) => field.signed ? ctx.palette.diverging(t) : ctx.palette.sequential(t);
+		const cells = [], peaks = [];
+		for (let c = 0; c < columns; c++) {
+			const time = x.invert((c + .5) * CELL);
+			let best = -Infinity, bestY = 0;
+			for (let r = 0; r < rows; r++) {
+				const at = y.invert((r + .5) * CELL), value = field.read(time, at);
+				if (value > best) {
+					best = value;
+					bestY = at;
+				}
+				cells.push({
+					x: c * CELL,
+					y: r * CELL,
+					width: CELL,
+					height: CELL,
+					level: field.shade(value)
+				});
+			}
+			peaks.push([time, bestY]);
+		}
+		SignalRaster.paint(ctx, "raster", cells, color);
+		this.overlay(ctx, axes);
+		if (this.options.ridge) {
+			this.stroke(ctx, "ridge-halo", [peaks], () => 0, (points) => this.path(points, x, y), () => ctx.theme.surface, 4);
+			this.stroke(ctx, "ridge", [peaks], () => 0, (points) => this.path(points, x, y), () => ctx.theme.ink);
+		}
+		SignalRaster.ramp(ctx, right + 14, (t) => color(field.signed ? t * 2 - 1 : t), field.low, field.high);
+		this.probe(ctx, (px, py) => {
+			if (px > right) return null;
+			const time = x.invert(px), at = y.invert(py);
+			return {
+				x: px,
+				tip: {
+					title: `${SignalScales.number(time)} s`,
+					rows: [[this.options.yLabel ?? "", SignalScales.number(at)], [field.unit, SignalScales.number(field.read(time, at))]]
+				},
+				datum: {
+					t: time,
+					y: at
+				}
+			};
+		});
+	}
+};
+export { TimeFrequencyChart };