@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/genomics/GenomeIdeogram.js

@@ -0,0 +1,422 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { GenomeAssembly } from "./GenomeAssembly.js";
+import { GenomeSamples } from "./GenomeSamples.js";
+import { GenomeStainScale } from "./GenomeStainScale.js";
+import { GenomeAlign, GenomeAnnotationMark, GenomeBandLevel, GenomeIdeogramLayout, GenomeOutline } from "./genomicsEnums.js";
+import { max, scaleLinear, ticks } from "d3";
+// src/charts/genomics/GenomeIdeogram.ts
+var CHAR = 6.2;
+var WAIST = .32;
+var STALK = .45;
+var NAME_ROOM = 14;
+/** ISCN karyogram rows. */
+var KARYOGRAM_ROWS = [
+	[
+		"1",
+		"2",
+		"3",
+		"4",
+		"5"
+	],
+	[
+		"6",
+		"7",
+		"8",
+		"9",
+		"10",
+		"11",
+		"12"
+	],
+	[
+		"13",
+		"14",
+		"15",
+		"16",
+		"17",
+		"18"
+	],
+	[
+		"19",
+		"20",
+		"21",
+		"22",
+		"X",
+		"Y"
+	]
+];
+/** Show a genome's chromosomes as stained bands around their centromeres, and where features fall on them. */
+var GenomeIdeogram = class GenomeIdeogram extends Chart2D {
+	static meta = {
+		id: "genome-ideogram",
+		name: "Genome ideogram",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Two,
+		shape: DataShape.Genome,
+		description: "Draws chromosomes as Giemsa bands around their centromeres and maps annotated loci onto genomic position.",
+		tags: [
+			"genomics",
+			"chromosome",
+			"cytoband",
+			"karyotype",
+			"iscn"
+		],
+		sample: (seed) => GenomeSamples.cancerGenome(seed),
+		variants: {
+			layout: [
+				GenomeIdeogramLayout.Columns,
+				GenomeIdeogramLayout.Rows,
+				GenomeIdeogramLayout.Karyogram,
+				GenomeIdeogramLayout.Single
+			],
+			align: [GenomeAlign.Centromere, GenomeAlign.Telomere],
+			level: [
+				GenomeBandLevel.Published,
+				GenomeBandLevel.SubBand,
+				GenomeBandLevel.Band
+			],
+			annotationMark: [
+				GenomeAnnotationMark.Triangle,
+				GenomeAnnotationMark.Tick,
+				GenomeAnnotationMark.Lollipop,
+				GenomeAnnotationMark.None
+			],
+			outline: [GenomeOutline.Constricted, GenomeOutline.Block]
+		},
+		valid: (v) => {
+			return (v.layout === GenomeIdeogramLayout.Columns || v.layout === GenomeIdeogramLayout.Rows || v.outline === GenomeOutline.Constricted) && (v.layout !== GenomeIdeogramLayout.Single || v.align === GenomeAlign.Centromere);
+		}
+	};
+	defaults() {
+		return {
+			layout: GenomeIdeogramLayout.Columns,
+			align: GenomeAlign.Centromere,
+			level: GenomeBandLevel.Published,
+			annotationMark: GenomeAnnotationMark.Triangle,
+			outline: GenomeOutline.Constricted
+		};
+	}
+	plotMargin() {
+		return {
+			top: 10,
+			right: 12,
+			bottom: 8,
+			left: 12
+		};
+	}
+	#assembly() {
+		return new GenomeAssembly(this.options.data, this.options.bandFields, this.options.level);
+	}
+	table() {
+		return this.#assembly().table(["annotations", "bands"]);
+	}
+	/** Bp above and below the shared alignment line, so one bp is the same length on every chromosome. */
+	static #extent(list, align) {
+		const above = (c) => align === GenomeAlign.Centromere ? c.centromere ?? c.length / 2 : 0;
+		return [max(list, above) ?? 0, max(list, (c) => c.length - above(c)) ?? 1];
+	}
+	#placeLine(list, box, horizontal, scale, slotCap) {
+		const align = this.options.align;
+		const [before, after] = GenomeIdeogram.#extent(list, align);
+		const bp = scale ?? (horizontal ? box.width : box.height) / (before + after || 1);
+		const slot = Math.min(slotCap ?? Infinity, (horizontal ? box.height : box.width) / (list.length || 1));
+		const half = Math.max(1.5, Math.min(horizontal ? 5 : 7, slot * (horizontal ? .27 : .21)));
+		return list.map((chromosome, i) => {
+			const anchor = align === GenomeAlign.Centromere ? chromosome.centromere ?? chromosome.length / 2 : 0;
+			const base = (horizontal ? box.x : box.y) + (before - anchor) * bp;
+			const middle = (horizontal ? box.y : box.x) + slot * i + (horizontal ? slot / 2 : half + 2);
+			return {
+				chromosome,
+				half,
+				horizontal,
+				room: slot - half * 2 - 3,
+				along: (position) => base + position * bp,
+				point: (along, across) => horizontal ? [along, middle + across] : [middle + across, along],
+				name: horizontal ? {
+					x: box.x - 4,
+					y: middle,
+					anchor: "end"
+				} : {
+					x: middle,
+					y: box.y + box.height + 11,
+					anchor: "middle"
+				}
+			};
+		});
+	}
+	#placements(list, focus, width, height) {
+		const { layout } = this.options;
+		if (layout === GenomeIdeogramLayout.Rows) return this.#placeLine(list, {
+			x: 20,
+			y: 0,
+			width: width - 20,
+			height
+		}, true);
+		if (layout === GenomeIdeogramLayout.Columns) return this.#placeLine(list, {
+			x: 0,
+			y: 0,
+			width,
+			height: height - NAME_ROOM
+		}, false);
+		if (layout === GenomeIdeogramLayout.Single) return focus ? this.#placeSingle(focus, width, height) : [];
+		const known = KARYOGRAM_ROWS.flat();
+		const rows = KARYOGRAM_ROWS.map((names) => list.filter((c) => names.includes(c.name)));
+		rows.at(-1).push(...list.filter((c) => !known.includes(c.name)));
+		const live = rows.filter((row) => row.length);
+		const spans = live.map((row) => GenomeIdeogram.#extent(row, this.options.align));
+		const bp = (height - live.length * 18) / (spans.reduce((sum, [a, b]) => sum + a + b, 0) || 1);
+		const widest = Math.max(...live.map((row) => row.length), 1);
+		let y = 0;
+		return live.flatMap((row, i) => {
+			const rise = (spans[i][0] + spans[i][1]) * bp;
+			const placed = this.#placeLine(row, {
+				x: 0,
+				y,
+				width,
+				height: rise
+			}, false, bp, Math.max(width / widest, width / row.length * .8));
+			y += rise + NAME_ROOM + 4;
+			return placed;
+		});
+	}
+	#placeSingle(chromosome, width, height) {
+		const half = Math.min(14, Math.max(8, width * .025)), middle = width * .36;
+		const bp = (height - NAME_ROOM) / chromosome.length;
+		return [{
+			chromosome,
+			half,
+			horizontal: false,
+			room: width - middle - half - 2,
+			along: (position) => position * bp,
+			point: (along, across) => [middle + across, along],
+			name: {
+				x: middle,
+				y: height - 1,
+				anchor: "middle"
+			}
+		}];
+	}
+	#profile(band, chromosome, place) {
+		const from = place.along(band.start), to = place.along(band.end);
+		if (this.options.outline === GenomeOutline.Block) return {
+			from,
+			to,
+			h0: 1,
+			h1: 1
+		};
+		if (band.stain === "stalk") return {
+			from,
+			to,
+			h0: STALK,
+			h1: STALK
+		};
+		if (band.stain !== "acen" || chromosome.bands.filter((item) => item.stain === "acen").length < 2) return {
+			from,
+			to,
+			h0: 1,
+			h1: 1
+		};
+		return band.end === chromosome.centromere ? {
+			from,
+			to,
+			h0: 1,
+			h1: WAIST
+		} : {
+			from,
+			to,
+			h0: WAIST,
+			h1: 1
+		};
+	}
+	/** Closed shape over runs of varying half-width, with an optional rounded telomere at each end. */
+	#silhouette(runs, place, capStart, capEnd) {
+		const rounded = this.options.outline !== GenomeOutline.Block;
+		const first = runs[0], last = runs.at(-1), width = place.half;
+		const start = rounded && capStart ? Math.min(width, first.to - first.from) : 0;
+		const end = rounded && capEnd ? Math.min(width, last.to - last.from) : 0;
+		const at = (along, h) => place.point(along, h * width).map((n) => +n.toFixed(2)).join(" ");
+		const side = (sign) => runs.flatMap((run) => [[run.from, run.h0 * sign], [run.to, run.h1 * sign]]);
+		const left = side(-1), right = side(1).reverse();
+		if (start) left[0] = [first.from + start, -first.h0];
+		if (end) left[left.length - 1] = [last.to - end, -last.h1];
+		if (end) right[0] = [last.to - end, last.h1];
+		if (start) right[right.length - 1] = [first.from + start, first.h0];
+		const line = (list) => list.map(([along, h]) => `L${at(along, h)}`).join("");
+		const capEndPath = end ? `Q${at(last.to, -last.h1)} ${at(last.to, 0)}Q${at(last.to, last.h1)} ${at(last.to - end, last.h1)}` : "";
+		const capStartPath = start ? `Q${at(first.from, first.h0)} ${at(first.from, 0)}Q${at(first.from, -first.h0)} ${at(first.from + start, -first.h0)}` : "";
+		return `M${at(left[0][0], left[0][1])}${line(left.slice(1))}${capEndPath}${line(right)}${capStartPath}Z`;
+	}
+	#drawChromosomes(ctx, places) {
+		const stain = new GenomeStainScale(ctx.theme);
+		const items = places.flatMap((place) => place.chromosome.bands.map((band, i, all) => {
+			const run = this.#profile(band, place.chromosome, place);
+			return {
+				band,
+				d: this.#silhouette([run], place, i === 0, i === all.length - 1)
+			};
+		}));
+		const bands = ctx.marks("bands", "path", items, (d) => d.band.key).attr("fill", (d) => stain.fill(d.band));
+		ctx.set(bands, {
+			d: (d) => d.d,
+			"fill-opacity": 1
+		}, { "fill-opacity": 0 });
+		ctx.hover(bands, ({ band }) => ({
+			title: `${band.chrom}${band.name}`,
+			rows: [["Stain", band.stain], ["Position", GenomeAssembly.span(band.start, band.end)]]
+		}));
+		const shells = ctx.marks("outlines", "path", places, (d) => d.chromosome.name).attr("fill", "none").attr("stroke", ctx.theme.inkMuted).attr("stroke-width", .75).attr("pointer-events", "none");
+		ctx.set(shells, { d: (place) => this.#silhouette(place.chromosome.bands.map((band) => this.#profile(band, place.chromosome, place)), place, true, true) });
+		const legible = places.filter((_, i) => places.length < 3 || i % this.#nameStride(places) === 0);
+		const names = ctx.marks("chromosome-names", "text", legible, (d) => d.chromosome.name);
+		ctx.text(names, 9.5).attr("text-anchor", (d) => d.name.anchor).attr("dy", (d) => d.horizontal ? "0.33em" : null).attr("pointer-events", "none").attr("x", (d) => d.name.x).attr("y", (d) => d.name.y).text((d) => d.chromosome.name);
+	}
+	/** Every name fits at 11px of slot; below that, every other one is shown. */
+	#nameStride(places) {
+		const [a, b] = places;
+		if (!a || !b) return 1;
+		return (a.horizontal ? Math.abs(a.point(0, 0)[1] - b.point(0, 0)[1]) : Math.abs(a.point(0, 0)[0] - b.point(0, 0)[0])) >= 10.5 ? 1 : 2;
+	}
+	static #markerSize(d) {
+		return Math.max(3, Math.min(8, d.place.room));
+	}
+	/** Lollipop height, from the chromosome's edge: value over the tallest one, within the slot. */
+	#stem(d, marks) {
+		const peak = max(marks, (mark) => mark.item.value ?? 0) || 1;
+		return d.place.half + 3 + (d.item.value ?? 0) / peak * Math.max(0, Math.min(26, d.place.room) - GenomeIdeogram.#markerSize(d));
+	}
+	/** Distance from the axis to clear space past a mark. */
+	#clearance(d, marks) {
+		const size = GenomeIdeogram.#markerSize(d);
+		if (this.options.annotationMark === GenomeAnnotationMark.Lollipop) return this.#stem(d, marks) + size / 2 + 3;
+		return d.place.half + (this.options.annotationMark === GenomeAnnotationMark.Tick ? 6 : size + 3);
+	}
+	#drawAnnotations(ctx, marks, assembly) {
+		const mode = this.options.annotationMark;
+		const edge = (d) => d.place.half + 1;
+		const size = GenomeIdeogram.#markerSize;
+		const stem = (d) => this.#stem(d, marks);
+		const tip = (d) => ({
+			title: d.item.label || "Annotation",
+			color: d.color,
+			rows: [
+				["Locus", assembly.locus(d.item.chrom, d.item.start)],
+				["Position", GenomeAssembly.span(d.item.start, d.item.end)],
+				...d.item.value == null ? [] : [["Value", d.item.value]]
+			]
+		});
+		const paintColor = (d) => d.color;
+		if (mode === GenomeAnnotationMark.Triangle) {
+			const triangle = (d) => {
+				const near = d.place.point(d.at, edge(d)), s = size(d);
+				const a = d.place.point(d.at - s / 2, edge(d) + s), b = d.place.point(d.at + s / 2, edge(d) + s);
+				return `M${near.join(" ")}L${a.join(" ")}L${b.join(" ")}Z`;
+			};
+			const marksSel = ctx.marks("triangles", "path", marks, (d) => d.key).attr("fill", paintColor);
+			ctx.set(marksSel, {
+				d: triangle,
+				"fill-opacity": 1
+			}, { "fill-opacity": 0 });
+			ctx.hover(marksSel, tip);
+		}
+		if (mode === GenomeAnnotationMark.Tick) {
+			const ticksSel = ctx.marks("ticks", "line", marks, (d) => d.key).attr("stroke", paintColor).attr("stroke-width", 2);
+			ctx.set(ticksSel, {
+				x1: (d) => d.place.point(d.at, -d.place.half - 1)[0],
+				y1: (d) => d.place.point(d.at, -d.place.half - 1)[1],
+				x2: (d) => d.place.point(d.at, d.place.half + 3)[0],
+				y2: (d) => d.place.point(d.at, d.place.half + 3)[1]
+			});
+			ctx.hover(ticksSel, tip);
+		}
+		if (mode === GenomeAnnotationMark.Lollipop) {
+			const stems = ctx.marks("stems", "line", marks, (d) => d.key).attr("stroke", paintColor).attr("stroke-width", 1.5);
+			ctx.set(stems, {
+				x1: (d) => d.place.point(d.at, edge(d))[0],
+				y1: (d) => d.place.point(d.at, edge(d))[1],
+				x2: (d) => d.place.point(d.at, stem(d))[0],
+				y2: (d) => d.place.point(d.at, stem(d))[1]
+			});
+			const heads = ctx.marks("heads", "circle", marks, (d) => d.key).attr("fill", paintColor).attr("stroke", ctx.theme.surface).attr("stroke-width", (d) => size(d) >= 8 ? 2 : 1);
+			ctx.set(heads, {
+				cx: (d) => d.place.point(d.at, stem(d))[0],
+				cy: (d) => d.place.point(d.at, stem(d))[1],
+				r: (d) => size(d) / 2
+			}, { r: 0 });
+			ctx.hover(heads, tip);
+		}
+	}
+	/** Greedy by value: a label needs room beside its chromosome and clear space along it. */
+	#labels(ctx, marks) {
+		const taken = /* @__PURE__ */ new Map();
+		const kept = [...marks].sort((a, b) => (b.item.value ?? 0) - (a.item.value ?? 0)).filter((mark) => {
+			const wide = mark.item.label.length * CHAR;
+			const need = this.#clearance(mark, marks) - mark.place.half + (mark.place.horizontal ? 12 : wide);
+			const clear = mark.place.horizontal ? wide + 6 : 11;
+			const used = taken.get(mark.place.chromosome.name) ?? [];
+			if (need > mark.place.room || used.some((at) => Math.abs(at - mark.at) < clear)) return false;
+			taken.set(mark.place.chromosome.name, [...used, mark.at]);
+			return true;
+		});
+		const point = (d) => d.place.point(d.at, this.#clearance(d, marks) + (d.place.horizontal ? 4 : 0));
+		const labels = ctx.marks("labels", "text", kept, (d) => d.key);
+		ctx.text(labels, 9.5).attr("pointer-events", "none").attr("text-anchor", (d) => d.place.horizontal ? "middle" : "start").attr("dy", "0.33em").attr("x", (d) => point(d)[0]).attr("y", (d) => point(d)[1]).text((d) => d.item.label);
+	}
+	/** Band names on the left, as ISCN ideograms carry them, and a Mb ruler beyond. */
+	#drawSingleAxis(ctx, place) {
+		const { chromosome } = place;
+		let last = -Infinity;
+		const named = chromosome.bands.filter((band) => {
+			if (place.along(band.end) - place.along(band.start) < 2) return false;
+			const at = place.along((band.start + band.end) / 2);
+			if (at - last < 11) return false;
+			last = at;
+			return true;
+		});
+		const textAt = (band) => place.point(place.along((band.start + band.end) / 2), -place.half - 6);
+		const names = ctx.marks("band-names", "text", named, (d) => d.key);
+		ctx.text(names, 9.5).attr("text-anchor", "end").attr("dy", "0.33em").attr("pointer-events", "none").attr("x", (d) => textAt(d)[0]).attr("y", (d) => textAt(d)[1]).text((d) => d.name);
+		const axisAcross = place.point(0, 0)[0] - place.half - 60;
+		const scale = scaleLinear([0, chromosome.length / 1e6], [place.along(0), place.along(chromosome.length)]);
+		const rule = ctx.marks("ruler-ticks", "line", ticks(0, chromosome.length / 1e6, 6), (d) => d).attr("stroke", ctx.theme.axis);
+		ctx.set(rule, {
+			x1: axisAcross - 4,
+			x2: axisAcross,
+			y1: (d) => scale(d),
+			y2: (d) => scale(d)
+		});
+		const line = ctx.marks("ruler", "line", [0]).attr("stroke", ctx.theme.axis);
+		ctx.set(line, {
+			x1: axisAcross,
+			x2: axisAcross,
+			y1: scale(0),
+			y2: scale(chromosome.length / 1e6)
+		});
+		const labels = ctx.marks("ruler-labels", "text", ticks(0, chromosome.length / 1e6, 6), (d) => d);
+		ctx.text(labels, 9.5, "muted").attr("text-anchor", "end").attr("dy", "0.33em").attr("x", axisAcross - 6).attr("y", (d) => scale(d)).text((d) => `${d}${d ? "" : " Mb"}`);
+	}
+	draw(ctx) {
+		const { layout, annotationMark, annotationFields, focus } = this.options;
+		const assembly = this.#assembly();
+		const notes = assembly.annotations(annotationFields);
+		const single = layout === GenomeIdeogramLayout.Single;
+		const target = single ? assembly.busiest(notes.map((note) => note.chrom), focus) : void 0;
+		const places = this.#placements(assembly.chromosomes, target, ctx.plot.width, ctx.plot.height);
+		this.#drawChromosomes(ctx, places);
+		const byName = new Map(places.map((place) => [place.chromosome.name, place]));
+		if (annotationMark !== GenomeAnnotationMark.None) for (const note of notes) ctx.palette.color(note.group);
+		const marks = annotationMark === GenomeAnnotationMark.None ? [] : notes.flatMap((item) => {
+			const place = byName.get(item.chrom);
+			return place ? [{
+				key: item.key,
+				item,
+				place,
+				at: place.along((item.start + item.end) / 2),
+				color: ctx.palette.color(item.group)
+			}] : [];
+		});
+		this.#drawAnnotations(ctx, marks, assembly);
+		this.#labels(ctx, marks);
+		if (single && places[0]) this.#drawSingleAxis(ctx, places[0]);
+	}
+};
+export { GenomeIdeogram };