@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/signals/PhaseSpace3DChart.js

@@ -0,0 +1,190 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SignalParser } from "./SignalChart.js";
+import { SignalSamples } from "./SignalSamples.js";
+import { SignalScales } from "./SignalScales.js";
+import { scaleLinear } from "d3";
+import { BufferAttribute, BufferGeometry, CatmullRomCurve3, Color, Float32BufferAttribute, Group, InstancedMesh, Line, LineBasicMaterial, Mesh, MeshStandardMaterial, Object3D, PlaneGeometry, SphereGeometry, TubeGeometry, Vector3 } from "three";
+// src/charts/signals/PhaseSpace3DChart.ts
+var Phase3DCoordinates = /* @__PURE__ */ function(Phase3DCoordinates) {
+	Phase3DCoordinates["Channels"] = "channels";
+	Phase3DCoordinates["Delay"] = "delay";
+	Phase3DCoordinates["Derivative"] = "derivative";
+	return Phase3DCoordinates;
+}({});
+var Phase3DStyle = /* @__PURE__ */ function(Phase3DStyle) {
+	Phase3DStyle["Tube"] = "tube";
+	Phase3DStyle["Line"] = "line";
+	Phase3DStyle["Points"] = "points";
+	return Phase3DStyle;
+}({});
+var MAX_STEPS = 900;
+var FLOOR = -.82;
+/** A trajectory through three state variables: the shape of an attractor, seen from any angle. */
+var PhaseSpace3DChart = class extends Chart3D {
+	static meta = {
+		id: "signal-phase-space-3d",
+		name: "3D phase space",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Traces a system through three state dimensions as a tube, line or point cloud, to expose an attractor.",
+		tags: [
+			"attractor",
+			"rossler",
+			"lorenz",
+			"trajectory",
+			"delay embedding"
+		],
+		sample: (seed) => SignalSamples.attractor(seed, 1600, 3),
+		variants: {
+			coordinates: Object.values(Phase3DCoordinates),
+			style: Object.values(Phase3DStyle),
+			shadow: [true, false],
+			delay: [40, 16]
+		},
+		valid: (values) => values.coordinates === "delay" || values.delay === 40
+	};
+	defaults() {
+		return {
+			x: "t",
+			y: "value",
+			series: "series",
+			coordinates: "channels",
+			style: "tube",
+			shadow: true,
+			delay: 40,
+			elevation: 22,
+			distance: 4.9
+		};
+	}
+	/** Trajectory scaled into the cube, keeping the three axes' own proportions out of the picture. */
+	trajectory() {
+		const { data, x, y, series, sampleRate, coordinates, delay } = this.options;
+		const list = SignalParser.channels(data, x, y, series, sampleRate), first = list[0];
+		if (!first || first.v.length < 8) return [];
+		const v = first.v;
+		let triples;
+		if (coordinates === "channels" && list.length >= 3) triples = v.slice(0, Math.min(list[1].v.length, list[2].v.length)).map((value, i) => [
+			value,
+			list[1].v[i],
+			list[2].v[i]
+		]);
+		else if (coordinates === "derivative") triples = v.slice(2, -2).map((value, i) => [
+			value,
+			v[i + 3] - v[i + 1],
+			v[i + 4] - 2 * v[i + 2] + v[i]
+		]);
+		else triples = v.slice(0, Math.max(0, v.length - 2 * delay)).map((value, i) => [
+			value,
+			v[i + delay],
+			v[i + 2 * delay]
+		]);
+		if (!triples.length) return [];
+		const stride = Math.max(1, Math.floor(triples.length / MAX_STEPS));
+		const kept = triples.filter((_, i) => i % stride === 0);
+		const axes = [
+			0,
+			1,
+			2
+		].map((axis) => {
+			const values = kept.map((point) => point[axis]), lo = Math.min(...values), hi = Math.max(...values);
+			return scaleLinear([lo, hi > lo ? hi : lo + 1], [-.9, .9]);
+		});
+		return kept.map(([a, b, c]) => new Vector3(axes[0](a), axes[2](c), axes[1](b)));
+	}
+	tint(ctx, count) {
+		const out = new Float32Array(count * 3), color = new Color();
+		for (let i = 0; i < count; i++) {
+			color.set(ctx.palette.sequential(.25 + .75 * i / count));
+			out.set([
+				color.r,
+				color.g,
+				color.b
+			], i * 3);
+		}
+		return out;
+	}
+	build(ctx) {
+		const points = this.trajectory(), { style, shadow } = this.options;
+		const floor = new Mesh(new PlaneGeometry(2.2, 2.2), new MeshStandardMaterial({ color: ctx.theme.grid }));
+		floor.rotation.x = -Math.PI / 2;
+		floor.position.y = FLOOR;
+		floor.receiveShadow = true;
+		ctx.root.add(floor);
+		if (!points.length) return;
+		const holder = new Group();
+		ctx.root.add(holder);
+		if (style === "tube") {
+			const geometry = new TubeGeometry(new CatmullRomCurve3(points), Math.min(1400, points.length * 2), .018, 7, false);
+			const count = geometry.getAttribute("position").count, rings = count / 8, ramp = new Float32Array(count * 3), color = new Color();
+			for (let i = 0; i < count; i++) {
+				color.set(ctx.palette.sequential(.25 + .75 * (Math.floor(i / 8) / rings)));
+				ramp.set([
+					color.r,
+					color.g,
+					color.b
+				], i * 3);
+			}
+			geometry.setAttribute("color", new BufferAttribute(ramp, 3));
+			const mesh = new Mesh(geometry, new MeshStandardMaterial({
+				vertexColors: true,
+				roughness: .42
+			}));
+			mesh.castShadow = true;
+			const total = geometry.getIndex().count;
+			ctx.reveal((progress) => geometry.setDrawRange(0, Math.floor(total * progress)), 1.8);
+			holder.add(mesh);
+			ctx.pick(mesh, () => ({
+				title: "Trajectory",
+				rows: [["Steps", points.length]]
+			}));
+		}
+		if (style === "line") {
+			const geometry = new BufferGeometry().setFromPoints(points);
+			geometry.setAttribute("color", new BufferAttribute(this.tint(ctx, points.length), 3));
+			ctx.reveal((progress) => geometry.setDrawRange(0, Math.floor(points.length * progress)), 1.8);
+			holder.add(new Line(geometry, new LineBasicMaterial({ vertexColors: true })));
+		}
+		if (style === "points") {
+			const kept = points.filter((_, i) => i % 3 === 0), mesh = new InstancedMesh(new SphereGeometry(.02, 8, 6), new MeshStandardMaterial({ roughness: .4 }), kept.length), dummy = new Object3D();
+			mesh.castShadow = true;
+			const place = (progress) => {
+				kept.forEach((point, i) => {
+					dummy.position.copy(point);
+					dummy.scale.setScalar(i / kept.length <= progress ? 1 : .001);
+					dummy.updateMatrix();
+					mesh.setMatrixAt(i, dummy.matrix);
+				});
+				mesh.instanceMatrix.needsUpdate = true;
+			};
+			kept.forEach((_, i) => mesh.setColorAt(i, ctx.color(ctx.palette.sequential(.25 + .75 * i / kept.length))));
+			ctx.reveal(place, 1.8);
+			holder.add(mesh);
+			ctx.pick(mesh, (i) => ({
+				title: `Step ${i * 3}`,
+				rows: [
+					["x", SignalScales.number(kept[i].x)],
+					["y", SignalScales.number(kept[i].y)],
+					["z", SignalScales.number(kept[i].z)]
+				]
+			}));
+		}
+		if (shadow) {
+			const flat = new BufferGeometry().setAttribute("position", new Float32BufferAttribute(points.flatMap((point) => [
+				point.x,
+				-.817,
+				point.z
+			]), 3));
+			ctx.root.add(new Line(flat, new LineBasicMaterial({
+				color: ctx.theme.inkMuted,
+				transparent: true,
+				opacity: .55
+			})));
+		}
+		ctx.onFrame((seconds) => {
+			holder.rotation.y = Math.sin(seconds * .2) * .06;
+		});
+	}
+};
+export { Phase3DCoordinates, Phase3DStyle, PhaseSpace3DChart };

package/dist/charts/signals/PhaseSpaceChart.js

@@ -0,0 +1,148 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SignalChart } from "./SignalChart.js";
+import { SignalSamples } from "./SignalSamples.js";
+import { SignalScales } from "./SignalScales.js";
+import { max, scaleLinear } from "d3";
+import { hexbin } from "d3-hexbin";
+// src/charts/signals/PhaseSpaceChart.ts
+var PhaseCoordinates = /* @__PURE__ */ function(PhaseCoordinates) {
+	PhaseCoordinates["Delay"] = "delay";
+	PhaseCoordinates["Derivative"] = "derivative";
+	PhaseCoordinates["Channels"] = "channels";
+	return PhaseCoordinates;
+}({});
+var PhaseMark = /* @__PURE__ */ function(PhaseMark) {
+	PhaseMark["Trajectory"] = "trajectory";
+	PhaseMark["Points"] = "points";
+	PhaseMark["Density"] = "density";
+	return PhaseMark;
+}({});
+var SEGMENTS = 24;
+var POINTS = 180;
+/** Reconstructs a dynamical system's state space from a signal, showing limit cycles and strange attractors. */
+var PhaseSpaceChart = class extends SignalChart {
+	static meta = {
+		id: "signal-phase-space",
+		name: "Phase space plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots a signal against its delayed self, its slope or another channel to reveal cycles and attractors.",
+		tags: [
+			"attractor",
+			"delay embedding",
+			"poincare section",
+			"lissajous",
+			"dynamics"
+		],
+		sample: (seed) => SignalSamples.attractor(seed),
+		variants: {
+			coordinates: Object.values(PhaseCoordinates),
+			mark: Object.values(PhaseMark),
+			delay: [36, 12],
+			section: [false, true]
+		},
+		valid: (values) => values.coordinates === "delay" || values.delay === 36
+	};
+	constructor(options) {
+		const kind = options.coordinates ?? "delay";
+		super({
+			xLabel: kind === "channels" ? "Channel 1" : "x(t)",
+			yLabel: kind === "derivative" ? "dx/dt" : kind === "channels" ? "Channel 2" : "x(t + τ)",
+			...options
+		});
+	}
+	defaults() {
+		return {
+			...super.defaults(),
+			coordinates: "delay",
+			mark: "trajectory",
+			delay: 36,
+			section: false
+		};
+	}
+	get legended() {
+		return false;
+	}
+	get points() {
+		const { coordinates, delay } = this.options, { v, rate } = this.first, b = this.channels[1]?.v;
+		if (coordinates === "channels" && b) return v.slice(0, b.length).map((value, i) => [value, b[i]]);
+		if (coordinates === "derivative") return v.slice(1, -1).map((value, i) => [value, (v[i + 2] - v[i]) * rate / 2]);
+		return v.slice(0, Math.max(0, v.length - delay)).map((value, i) => [value, v[i + delay]]);
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot, points = this.points;
+		const fit = (axis, range) => {
+			const values = points.map((point) => point[axis]), low = Math.min(...values), high = Math.max(...values), pad = (high - low) * .06 || 1;
+			return scaleLinear([low - pad, high + pad], range);
+		};
+		return {
+			x: fit(0, [0, width]),
+			y: fit(1, [height, 0])
+		};
+	}
+	plotMarks(ctx, { x, y }) {
+		const { mark, section } = this.options, points = this.points;
+		if (!points.length) return;
+		if (mark === "trajectory") {
+			const size = Math.ceil(points.length / SEGMENTS);
+			const parts = Array.from({ length: SEGMENTS }, (_, i) => ({
+				i,
+				list: points.slice(i * size, (i + 1) * size + 1)
+			})).filter((part) => part.list.length > 1);
+			const paths = this.stroke(ctx, "path", parts, (part) => part.i, (part) => this.path(part.list, x, y), (part) => ctx.palette.sequential(.25 + .75 * part.i / SEGMENTS), 1.5);
+			ctx.hover(paths, (part) => ({
+				title: "Trajectory",
+				rows: [["Progress", `${Math.round(part.i / SEGMENTS * 100)}%`]]
+			}));
+		}
+		if (mark === "points") {
+			const stride = Math.max(1, Math.floor(points.length / POINTS)), kept = points.filter((_, i) => i % stride === 0);
+			const dots = ctx.marks("dots", "circle", kept, (_, i) => i).attr("fill", (_, i) => ctx.palette.sequential(.25 + .75 * i / kept.length)).attr("stroke", ctx.theme.surface).attr("stroke-width", 1);
+			ctx.set(dots, {
+				cx: (point) => x(point[0]),
+				cy: (point) => y(point[1]),
+				r: 4
+			}, { r: 0 }, 2);
+			ctx.hover(dots, (point, i) => ({
+				title: `Sample ${i * stride}`,
+				rows: [["x", SignalScales.number(point[0])], ["y", SignalScales.number(point[1])]]
+			}));
+		}
+		if (mark === "density") {
+			const { width, height } = ctx.plot, radius = Math.max(5, Math.min(width, height) / 22);
+			const bins = hexbin().x((point) => x(point[0])).y((point) => y(point[1])).radius(radius).extent([[0, 0], [width, height]])(points);
+			const top = max(bins, (bin) => bin.length) ?? 1, shape = hexbin().radius(radius - 1).hexagon();
+			const cells = ctx.marks("hex", "path", bins, (bin) => `${bin.x},${bin.y}`).attr("d", shape).attr("fill", (bin) => ctx.palette.sequential(.15 + .85 * Math.sqrt(bin.length / top)));
+			ctx.set(cells, {
+				transform: (bin) => `translate(${bin.x},${bin.y})`,
+				opacity: 1
+			}, { opacity: 0 }, 2);
+			ctx.hover(cells, (bin) => ({
+				title: "Density",
+				rows: [["Samples", bin.length]]
+			}));
+		}
+		if (section) this.section(ctx, points, x, y);
+	}
+	/** Poincaré section: upward crossings of the mid-line of x. */
+	section(ctx, points, x, y) {
+		const [lo, hi] = x.domain(), at = (lo + hi) / 2;
+		ctx.marks("section-line", "line", [0]).attr("x1", x(at)).attr("x2", x(at)).attr("y1", 0).attr("y2", ctx.plot.height).attr("stroke", ctx.theme.axis).attr("stroke-dasharray", "4 3");
+		const hits = points.flatMap((point, i) => i && points[i - 1][0] < at && point[0] >= at ? [{
+			i,
+			y: point[1]
+		}] : []);
+		const dots = ctx.marks("section", "circle", hits, (hit) => hit.i).attr("fill", ctx.theme.ink).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(dots, {
+			cx: x(at),
+			cy: (hit) => y(hit.y),
+			r: 4
+		}, { r: 0 }, 8);
+		ctx.hover(dots, (hit) => ({
+			title: "Section crossing",
+			rows: [["y", SignalScales.number(hit.y)]]
+		}));
+	}
+};
+export { PhaseCoordinates, PhaseMark, PhaseSpaceChart };

package/dist/charts/signals/PoleZeroChart.js

@@ -0,0 +1,164 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { SignalChart } from "./SignalChart.js";
+import { SignalScales } from "./SignalScales.js";
+import { scaleLinear } from "d3";
+// src/charts/signals/PoleZeroChart.ts
+var PolePlane = /* @__PURE__ */ function(PolePlane) {
+	PolePlane["Z"] = "z-plane";
+	PolePlane["S"] = "s-plane";
+	return PolePlane;
+}({});
+var RADIAL = [
+	.25,
+	.5,
+	.75
+];
+var ARC = 5;
+/** Poles and zeros of a transfer function, with stability read off the unit circle or left half-plane. */
+var PoleZeroChart = class extends SignalChart {
+	static meta = {
+		id: "signal-pole-zero",
+		name: "Pole-zero plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Places a system’s poles and zeros on the complex plane, showing stability, damping and notch frequencies.",
+		tags: [
+			"z-plane",
+			"s-plane",
+			"root locus",
+			"stability",
+			"transfer function"
+		],
+		sample: (seed) => SampleData.categories(seed, 4, 2).map((row, i) => {
+			const pole = i < 4, order = i % 4, angle = pole ? .32 + order * .3 : 1.25 + order * .22 + +row.value / 100 * .1;
+			const radius = pole ? .92 - order * .1 + +row.value / 100 * .03 : 1;
+			return {
+				re: +(radius * Math.cos(angle)).toFixed(4),
+				im: +((order % 2 ? -1 : 1) * radius * Math.sin(angle)).toFixed(4),
+				kind: pole ? "pole" : "zero"
+			};
+		}).flatMap((row) => [row, {
+			...row,
+			im: -row.im
+		}]),
+		variants: {
+			plane: Object.values(PolePlane),
+			guides: [true, false],
+			stable: [true, false],
+			pairs: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			re: "re",
+			im: "im",
+			kind: "kind",
+			xLabel: "Real",
+			yLabel: "Imaginary",
+			grid: false,
+			plane: "z-plane",
+			guides: true,
+			stable: true,
+			pairs: false
+		};
+	}
+	get legended() {
+		return this.roots.length > 0;
+	}
+	get z() {
+		return this.options.plane === "z-plane";
+	}
+	/** Roots in the display plane; z maps to s by the inverse bilinear transform. */
+	get roots() {
+		const { data, re, im, kind } = this.options;
+		return (data ?? []).flatMap((row, i) => {
+			const a = +row[re], b = +row[im];
+			if (!Number.isFinite(a) || !Number.isFinite(b) || row[re] === null) return [];
+			const pole = String(row[kind] ?? "pole") === "pole";
+			if (this.z) return [{
+				key: `${i}`,
+				re: a,
+				im: b,
+				pole
+			}];
+			const bottom = (a + 1) ** 2 + b ** 2;
+			return bottom < 1e-9 ? [] : [{
+				key: `${i}`,
+				re: (a * a + b * b - 1) / bottom,
+				im: 2 * b / bottom,
+				pole
+			}];
+		});
+	}
+	scales(ctx) {
+		const { width, height } = ctx.plot, roots = this.roots, ratio = width / height;
+		const reach = Math.max(this.z ? 1.25 : 1.6, ...roots.map((root) => Math.max(Math.abs(root.re) / ratio, Math.abs(root.im)) * 1.15));
+		return {
+			x: scaleLinear([-reach * ratio, reach * ratio], [0, width]),
+			y: scaleLinear([-reach, reach], [height, 0])
+		};
+	}
+	plotMarks(ctx, { x, y }) {
+		const { guides, stable, pairs } = this.options, { width, height } = ctx.plot, roots = this.roots, scale = Math.abs(x(1) - x(0));
+		if (stable) {
+			if (this.z) ctx.marks("stable", "circle", [0]).attr("cx", x(0)).attr("cy", y(0)).attr("r", scale).attr("fill", ctx.theme.grid).attr("opacity", .55);
+			else ctx.marks("stable", "rect", [0]).attr("x", 0).attr("y", 0).attr("width", x(0)).attr("height", height).attr("fill", ctx.theme.grid).attr("opacity", .55);
+		}
+		ctx.marks("axes", "path", [0]).attr("fill", "none").attr("stroke", ctx.theme.axis).attr("d", `M${x(0)} 0V${height}M0 ${y(0)}H${width}`);
+		if (this.z) ctx.marks("unit", "circle", [0]).attr("cx", x(0)).attr("cy", y(0)).attr("r", scale).attr("fill", "none").attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1);
+		if (guides) this.guides(ctx, x, y, scale);
+		if (pairs) {
+			const conjugates = roots.filter((root) => root.im > 1e-6).map((root) => ({
+				root,
+				twin: roots.find((other) => other.pole === root.pole && Math.abs(other.re - root.re) < .001 && Math.abs(other.im + root.im) < .001)
+			})).filter((pair) => pair.twin);
+			ctx.marks("pairs", "line", conjugates, (pair) => pair.root.key).attr("stroke", ctx.theme.axis).attr("stroke-dasharray", "3 3").attr("x1", (pair) => x(pair.root.re)).attr("x2", (pair) => x(pair.twin.re)).attr("y1", (pair) => y(pair.root.im)).attr("y2", (pair) => y(pair.twin.im));
+		}
+		const color = (root) => ctx.palette.color(root.pole ? "Pole" : "Zero");
+		const r = 5, shape = (root) => root.pole ? `M-${r} -${r}L${r} ${r}M${r} -${r}L-${r} ${r}` : `M-${r} 0a${r} ${r} 0 1 0 10 0a${r} ${r} 0 1 0 -10 0`;
+		const marks = ctx.marks("roots", "path", roots, (root) => root.key).attr("d", shape).attr("fill", ctx.theme.surface).attr("fill-opacity", (root) => root.pole ? 0 : 1).attr("stroke", color).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		ctx.set(marks, {
+			transform: (root) => `translate(${x(root.re)},${y(root.im)})`,
+			opacity: 1
+		}, { opacity: 0 }, 25);
+		ctx.hover(marks, (root) => ({
+			title: root.pole ? "Pole" : "Zero",
+			color: color(root),
+			rows: [["Value", `${SignalScales.number(root.re)} ${root.im < 0 ? "−" : "+"} ${SignalScales.number(Math.abs(root.im))}j`], ["Magnitude", SignalScales.number(Math.hypot(root.re, root.im))]]
+		}));
+	}
+	guides(ctx, x, y, scale) {
+		if (this.z) {
+			ctx.marks("rings", "circle", RADIAL, (r) => r).attr("cx", x(0)).attr("cy", y(0)).attr("r", (r) => r * scale).attr("fill", "none").attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+			const spokes = Array.from({ length: 10 }, (_, i) => i * Math.PI / ARC);
+			ctx.marks("spokes", "line", spokes, (angle) => angle).attr("x1", x(0)).attr("y1", y(0)).attr("x2", (angle) => x(Math.cos(angle))).attr("y2", (angle) => y(Math.sin(angle))).attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+			return;
+		}
+		const limit = Math.min(x.domain()[1], y.domain()[1]);
+		ctx.marks("rings", "circle", [
+			.5,
+			1,
+			1.5,
+			2,
+			3,
+			4
+		].filter((r) => r <= limit), (r) => r).attr("cx", x(0)).attr("cy", y(0)).attr("r", (r) => r * scale).attr("fill", "none").attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+		const rays = [
+			.2,
+			.5,
+			.8
+		].flatMap((damping) => [1, -1].map((sign) => {
+			const angle = Math.acos(damping) * sign, reach = Math.min(-x.domain()[0] / Math.cos(angle) * Math.sign(Math.cos(angle)), y.domain()[1] / Math.abs(Math.sin(angle)));
+			return {
+				key: `${damping}${sign}`,
+				angle,
+				reach
+			};
+		}));
+		ctx.marks("spokes", "line", rays, (ray) => ray.key).attr("x1", x(0)).attr("y1", y(0)).attr("x2", (ray) => x(-Math.cos(ray.angle) * ray.reach)).attr("y2", (ray) => y(Math.sin(ray.angle) * ray.reach)).attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+	}
+};
+export { PolePlane, PoleZeroChart };