@mstone6969/graph 0.1.0 → 0.2.0

package/dist/charts/lifescience/RamachandranPlot.js

@@ -0,0 +1,364 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension, LegendPosition, SymbolKind } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { RamachandranClass, RamachandranPanel, RamachandranRegionStyle, RamachandranVerdict } from "./ramachandranEnums.js";
+import { RamachandranRegions } from "./RamachandranRegions.js";
+import { RamachandranSamples } from "./RamachandranSamples.js";
+import { scaleLinear, symbol } from "d3";
+// src/charts/lifescience/RamachandranPlot.ts
+var FULL = 360;
+var HALF = 180;
+var MARK_AREA = 64;
+var MARK_REACH = 7;
+var LABEL_MOST = 8;
+var LEGEND_ROW = 22;
+var LEGEND_RAIL = 120;
+var LEGEND_ITEM = 32;
+var LEGEND_CHAR = 6.4;
+var LEGEND_INSET = 24;
+var CHAR = 6.2;
+var THREE_LETTER = {
+	G: "GLY",
+	P: "PRO",
+	I: "ILE",
+	V: "VAL"
+};
+var GROUPS = {
+	[RamachandranClass.Glycine]: ["Glycine", SymbolKind.Triangle],
+	[RamachandranClass.TransProline]: ["Proline", SymbolKind.Square],
+	[RamachandranClass.CisProline]: ["Proline", SymbolKind.Square]
+};
+var CLASS_NAMES = {
+	[RamachandranClass.General]: "General",
+	[RamachandranClass.Glycine]: "Glycine",
+	[RamachandranClass.TransProline]: "trans-Proline",
+	[RamachandranClass.CisProline]: "cis-Proline",
+	[RamachandranClass.PreProline]: "Pre-proline",
+	[RamachandranClass.IleVal]: "Ile/Val"
+};
+var PANEL_CLASS = {
+	[RamachandranPanel.All]: RamachandranClass.General,
+	[RamachandranPanel.General]: RamachandranClass.General,
+	[RamachandranPanel.Glycine]: RamachandranClass.Glycine,
+	[RamachandranPanel.TransProline]: RamachandranClass.TransProline,
+	[RamachandranPanel.CisProline]: RamachandranClass.CisProline,
+	[RamachandranPanel.PreProline]: RamachandranClass.PreProline,
+	[RamachandranPanel.IleVal]: RamachandranClass.IleVal
+};
+var clips = 0;
+/**
+* Check a protein's backbone: phi against psi per residue, after Ramachandran, Ramakrishnan and
+* Sasisekharan (1963), on the reference regions MolProbity validates with. Residues are classed and
+* judged as MolProbity's `ramalyze` does: Gly, then cis or trans Pro by omega, then pre-Pro, then
+* Ile/Val, then general. Both angles are periodic, so input wraps and a mark on an edge carries over
+* to the opposite one. Regions are the Top8000 contours; see `RamachandranRegions` for provenance.
+*/
+var RamachandranPlot = class RamachandranPlot extends CartesianChart {
+	static meta = {
+		id: "ramachandran-plot",
+		name: "Ramachandran plot",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots backbone phi against psi per residue over the Top8000 favoured and allowed regions, marking glycine, proline and outliers.",
+		tags: [
+			"protein",
+			"structure",
+			"backbone",
+			"torsion",
+			"validation",
+			"molprobity"
+		],
+		sample: (seed) => RamachandranSamples.protein(seed),
+		variants: {
+			panel: Object.values(RamachandranPanel),
+			regions: Object.values(RamachandranRegionStyle),
+			labelOutliers: [true, false]
+		}
+	};
+	#clipId = `ramachandran-clip-${++clips}`;
+	#outliers = false;
+	defaults() {
+		return {
+			phi: "phi",
+			psi: "psi",
+			residue: "residue",
+			nextResidue: "nextResidue",
+			omega: "omega",
+			label: "label",
+			xLabel: "φ (degrees)",
+			yLabel: "ψ (degrees)",
+			subtitle: RamachandranRegions.source,
+			panel: RamachandranPanel.All,
+			regions: RamachandranRegionStyle.Filled,
+			labelOutliers: true
+		};
+	}
+	/** Both axes span the same 360 degrees, so the plot stays square and one degree is one length. */
+	plotMargin() {
+		const base = super.plotMargin(), { width, height } = this.size, { title, subtitle } = this.options, side = this.legendPosition;
+		const wide = width - base.left - base.right - (side === LegendPosition.Right ? LEGEND_RAIL : 0);
+		const legend = side === LegendPosition.Top || side === LegendPosition.Bottom ? LEGEND_ROW * this.#legendRows(width) : 0;
+		const spare = wide - (height - base.top - base.bottom - (title ? 24 : 0) - (subtitle ? 18 : 0) - legend);
+		return spare >= 0 ? {
+			...base,
+			left: base.left + spare / 2,
+			right: base.right + spare / 2
+		} : {
+			...base,
+			bottom: base.bottom - spare
+		};
+	}
+	/** The same greedy fill the legend uses, so a wrapped legend does not cost the plot its shape. */
+	#legendRows(width) {
+		let rows = 1, at = 0;
+		for (const { key, label } of this.legendItems()) {
+			const cost = LEGEND_ITEM + (label ?? key).length * LEGEND_CHAR;
+			if (at && at + cost > width - LEGEND_INSET) {
+				rows++;
+				at = 0;
+			}
+			at += cost;
+		}
+		return rows;
+	}
+	/** Wraps to -180..180. An exact -180 stays put, since it is the same angle as 180. */
+	static wrap(angle) {
+		return angle >= -180 && angle <= HALF ? angle : angle - FULL * Math.ceil((angle - HALF) / FULL);
+	}
+	/** `ramalyze`'s precedence. `next` matters only for residues that are neither glycine nor proline. */
+	static classOf(residue, next, omega) {
+		const name = RamachandranPlot.#code(residue);
+		if (name === "GLY") return RamachandranClass.Glycine;
+		if (name === "PRO") return omega !== null && Math.abs(RamachandranPlot.wrap(omega)) < 90 ? RamachandranClass.CisProline : RamachandranClass.TransProline;
+		if (RamachandranPlot.#code(next) === "PRO") return RamachandranClass.PreProline;
+		return name === "ILE" || name === "VAL" ? RamachandranClass.IleVal : RamachandranClass.General;
+	}
+	static #code(name) {
+		const code = name.trim().toUpperCase();
+		return THREE_LETTER[code] ?? code.slice(0, 3);
+	}
+	static #number(cell) {
+		if (cell === "" || cell === null || cell === void 0 || cell instanceof Date) return null;
+		const value = Number(cell);
+		return Number.isFinite(value) ? value : null;
+	}
+	#residues() {
+		const { data, phi: phiKey, psi: psiKey, residue, nextResidue, omega, label, panel } = this.options;
+		const shown = panel === RamachandranPanel.All ? null : PANEL_CLASS[panel];
+		return (Array.isArray(data) ? data : []).flatMap((row, i) => {
+			const phiRaw = RamachandranPlot.#number(row?.[phiKey]), psiRaw = RamachandranPlot.#number(row?.[psiKey]);
+			if (phiRaw === null || psiRaw === null) return [];
+			const phi = RamachandranPlot.wrap(phiRaw), psi = RamachandranPlot.wrap(psiRaw);
+			const name = String(row[residue] ?? "").trim();
+			const kind = RamachandranPlot.classOf(name, String(row[nextResidue] ?? ""), RamachandranPlot.#number(row[omega]));
+			if (shown && kind !== shown) return [];
+			const [group, glyph] = GROUPS[kind] ?? ["General", SymbolKind.Circle];
+			return [{
+				key: `${i}`,
+				row,
+				name,
+				label: String(row[label] ?? name),
+				phi,
+				psi,
+				kind,
+				group,
+				glyph,
+				verdict: RamachandranRegions.classify(kind, phi, psi)
+			}];
+		});
+	}
+	scales(ctx) {
+		const x = scaleLinear([-180, HALF], [0, ctx.plot.width]), y = scaleLinear([-180, HALF], [ctx.plot.height, 0]);
+		const step = ctx.plot.width >= 196 ? 60 : 90;
+		const ticks = Array.from({ length: FULL / step + 1 }, (_, i) => -180 + i * step);
+		Object.assign(x, { ticks: () => ticks });
+		Object.assign(y, { ticks: () => ticks });
+		return {
+			x,
+			y
+		};
+	}
+	legendItems() {
+		const { panel } = this.options, kind = PANEL_CLASS[panel];
+		return [
+			{
+				key: "favoured",
+				label: RamachandranRegions.favouredLabel(),
+				color: this.#tone(RamachandranVerdict.Favoured)
+			},
+			{
+				key: "allowed",
+				label: RamachandranRegions.allowedLabel(kind),
+				color: this.#tone(RamachandranVerdict.Allowed)
+			},
+			...panel === RamachandranPanel.All ? this.palette.items() : [],
+			...this.#outliers ? [{
+				key: "outlier",
+				label: "Outlier",
+				color: this.theme.critical
+			}] : []
+		];
+	}
+	#tone(verdict) {
+		return this.palette.sequential(verdict === RamachandranVerdict.Favoured ? .3 : .03);
+	}
+	/** Filled regions close along the plot's edge, but that is where the map wraps, so a contour leaves those runs out. */
+	#regionPath(rings, x, y) {
+		const at = ([phi, psi]) => `${(x(phi) ?? 0).toFixed(1)},${(y(psi) ?? 0).toFixed(1)}`;
+		if (this.options.regions === RamachandranRegionStyle.Filled) return rings.map((ring) => `M${ring.map(at).join("L")}Z`).join("");
+		const edge = (a, b) => Math.abs(a[0]) === HALF && a[0] === b[0] || Math.abs(a[1]) === HALF && a[1] === b[1];
+		return rings.map((ring) => ring.map((point, i) => {
+			const before = ring[(i + ring.length - 1) % ring.length];
+			return `${i && !edge(before, point) ? "L" : "M"}${at(point)}`;
+		}).join("")).join("");
+	}
+	#drawRegions(ctx, { x, y }) {
+		const kind = PANEL_CLASS[this.options.panel], filled = this.options.regions === RamachandranRegionStyle.Filled;
+		const levels = [RamachandranVerdict.Allowed, RamachandranVerdict.Favoured].map((verdict) => ({
+			verdict,
+			d: this.#regionPath(RamachandranRegions.rings(kind, verdict === RamachandranVerdict.Favoured ? "favoured" : "allowed"), x, y)
+		}));
+		const shapes = ctx.marks("regions", "path", levels, (d) => d.verdict).attr("pointer-events", "none").attr("fill-rule", "evenodd").attr("fill", (d) => filled ? this.#tone(d.verdict) : "none").attr("stroke", (d) => filled ? "none" : ctx.palette.sequential(d.verdict === RamachandranVerdict.Favoured ? .75 : .4)).attr("stroke-width", filled ? null : 2);
+		ctx.set(shapes, {
+			d: (d) => d.d,
+			"fill-opacity": 1
+		}, { "fill-opacity": 0 });
+	}
+	#drawRules(ctx, { x, y }) {
+		const { width, height } = ctx.plot;
+		const verticals = x.ticks().filter((tick) => tick !== 0);
+		const lines = ctx.marks("phi-grid", "line", this.options.grid === false ? [] : verticals, (tick) => tick).attr("stroke", ctx.theme.grid).attr("stroke-width", 1);
+		ctx.set(lines, {
+			x1: (tick) => x(tick) ?? 0,
+			x2: (tick) => x(tick) ?? 0,
+			y1: 0,
+			y2: height
+		});
+		const zero = [{
+			key: "phi",
+			x1: x(0) ?? 0,
+			x2: x(0) ?? 0,
+			y1: 0,
+			y2: height
+		}, {
+			key: "psi",
+			x1: 0,
+			x2: width,
+			y1: y(0) ?? 0,
+			y2: y(0) ?? 0
+		}];
+		const axes = ctx.marks("zero-lines", "line", zero, (d) => d.key).attr("stroke", ctx.theme.axis).attr("stroke-width", 1).attr("pointer-events", "none");
+		ctx.set(axes, {
+			x1: (d) => d.x1,
+			x2: (d) => d.x2,
+			y1: (d) => d.y1,
+			y2: (d) => d.y2
+		});
+	}
+	/** The torus repeats at the edges: a mark that crosses one is drawn again, unhovered, where it comes back in. */
+	#copies(marks, { x, y }) {
+		const across = (at, low, high) => at < low + MARK_REACH ? high - low : at > high - MARK_REACH ? low - high : 0;
+		const left = x(-180) ?? 0, right = x(HALF) ?? 0, top = y(HALF) ?? 0, bottom = y(-180) ?? 0;
+		return marks.flatMap((mark) => {
+			const dx = across(mark.px, left, right), dy = across(mark.py, top, bottom);
+			return (dx && dy ? [
+				[dx, 0],
+				[0, dy],
+				[dx, dy]
+			] : dx || dy ? [[dx, dy]] : []).map(([sideways, upward]) => ({
+				...mark,
+				key: `${mark.key}:${sideways}:${upward}`,
+				px: mark.px + sideways,
+				py: mark.py + upward
+			}));
+		});
+	}
+	#drawMarks(ctx, marks, axes) {
+		const { width, height } = ctx.plot;
+		const holder = ctx.group("residues");
+		ctx.marks("residue-clip", "clipPath", [0], void 0, holder).attr("id", this.#clipId).selectAll("rect").data([0]).join("rect").attr("width", width).attr("height", height);
+		const inner = ctx.group("residue-marks", holder).attr("clip-path", `url(#${this.#clipId})`);
+		const paint = (d) => d.verdict === RamachandranVerdict.Outlier ? ctx.theme.critical : ctx.palette.color(d.group);
+		const glyph = (d) => symbol(Scales.symbol(d.glyph), MARK_AREA)() ?? "";
+		const place = (d) => `translate(${d.px.toFixed(1)},${d.py.toFixed(1)})`;
+		for (const mark of marks) if (mark.verdict !== RamachandranVerdict.Outlier) paint(mark);
+		const draw = (name, list) => ctx.marks(name, "path", list, (d) => d.key, inner).attr("fill", paint).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		const copies = draw("residue-copies", this.#copies(marks, axes)).attr("pointer-events", "none");
+		ctx.set(copies, {
+			d: glyph,
+			transform: place
+		});
+		const shown = draw("residue-points", [...marks].sort((a, b) => +(a.verdict === RamachandranVerdict.Outlier) - +(b.verdict === RamachandranVerdict.Outlier)));
+		ctx.set(shown, {
+			d: glyph,
+			transform: place,
+			"fill-opacity": 1
+		}, { "fill-opacity": 0 }, Math.min(2, 300 / (marks.length || 1)));
+		ctx.hover(shown, (d) => ({
+			title: d.label || CLASS_NAMES[d.kind],
+			color: paint(d),
+			rows: [
+				["φ", `${d.phi}°`],
+				["ψ", `${d.psi}°`],
+				["Reference map", CLASS_NAMES[d.kind]],
+				["Region", d.verdict]
+			]
+		}));
+	}
+	/** Greedy, on whichever side has room. A label that would touch another label or an outlier is dropped. */
+	#drawLabels(ctx, marks) {
+		const { width } = ctx.plot;
+		const boxes = marks.filter((d) => d.verdict === RamachandranVerdict.Outlier).map((d) => [
+			d.px - 5,
+			d.py - 5,
+			10,
+			10
+		]);
+		const free = (box) => box[0] >= 0 && box[0] + box[2] <= width && !boxes.some((b) => b[0] < box[0] + box[2] && box[0] < b[0] + b[2] && b[1] < box[1] + box[3] && box[1] < b[1] + b[3]);
+		let placed = 0;
+		const inPlot = (d) => d.px >= 0 && d.px <= width && d.py >= 0 && d.py <= ctx.plot.height;
+		const kept = (this.options.labelOutliers ? marks.filter((d) => d.verdict === RamachandranVerdict.Outlier && d.label && inPlot(d)) : []).flatMap((d) => {
+			const room = Math.floor(width / 3 / CHAR);
+			const text = d.label.length > room ? `${d.label.slice(0, Math.max(1, room - 1))}…` : d.label;
+			const wide = text.length * CHAR, base = Math.max(11, d.py + 4);
+			const right = [
+				d.px + 7,
+				base - 10,
+				wide,
+				12
+			], left = [
+				d.px - 7 - wide,
+				base - 10,
+				wide,
+				12
+			];
+			const box = placed >= LABEL_MOST ? null : free(right) ? right : free(left) ? left : null;
+			if (!box) return [];
+			boxes.push(box);
+			placed++;
+			return [{
+				key: d.key,
+				text,
+				x: box === right ? d.px + 7 : d.px - 7,
+				y: base,
+				anchor: box === right ? "start" : "end"
+			}];
+		});
+		ctx.text(ctx.marks("outlier-labels", "text", kept, (d) => d.key), 10, "ink").attr("pointer-events", "none").attr("text-anchor", (d) => d.anchor).attr("x", (d) => d.x).attr("y", (d) => d.y).text((d) => d.text);
+	}
+	plotMarks(ctx, axes) {
+		const { x, y } = axes;
+		const marks = this.#residues().map((residue) => ({
+			...residue,
+			px: x(residue.phi) ?? 0,
+			py: y(residue.psi) ?? 0
+		}));
+		this.#outliers = marks.some((mark) => mark.verdict === RamachandranVerdict.Outlier);
+		this.#drawRegions(ctx, axes);
+		this.#drawRules(ctx, axes);
+		this.#drawMarks(ctx, marks, axes);
+		this.#drawLabels(ctx, marks);
+	}
+};
+export { RamachandranPlot };