@genome-spy/core 0.14.0

package/src/genome/genome.js

@@ -0,0 +1,305 @@
+import { bisect } from "d3-array";
+import { tsvParseRows } from "d3-dsv";
+import { loader } from "vega-loader";
+import { isObject } from "vega-util";
+import { formatRange } from "./locusFormat";
+
+const defaultBaseUrl = "https://genomespy.app/data/genomes/";
+
+/**
+ * @typedef {import("../spec/genome").GenomeConfig} GenomeConfig
+ * @typedef {import("../spec/genome").ChromosomalLocus} ChromosomalLocus
+ *
+ * @typedef {object} Chromosome
+ * @prop {string} name
+ * @prop {number} size
+ *
+ * @typedef {object} ChromosomeAnnotation
+ * @prop {number} index 0-based index
+ * @prop {number} number 1-based index
+ * @prop {number} continuousStart zero-based start, inclusive
+ * @prop {number} continuousEnd zero-based end, exclusive
+ * @prop {number[]} continuousInterval
+ * @prop {boolean} odd true if odd chrom number
+ */
+
+export default class Genome {
+    /**
+     * @param {GenomeConfig} config
+     */
+    constructor(config) {
+        this.config = config;
+
+        if (!this.config.contigs && typeof this.config.name !== "string") {
+            throw new Error(
+                "No name has been defined for the genome assembly!"
+            );
+        }
+
+        /** @type {(Chromosome & ChromosomeAnnotation)[]} */
+        this.chromosomes = [];
+
+        /** @type {Map<string | number, number>} */
+        this.cumulativeChromPositions = new Map();
+
+        /** @type {Map<string | number, Chromosome & ChromosomeAnnotation>} */
+        this.chromosomesByName = new Map();
+
+        /** @type {number[]} */
+        this.startByIndex = [];
+
+        this.totalSize = 0;
+
+        if (this.config.contigs) {
+            this.setChromSizes(this.config.contigs);
+        }
+    }
+
+    get name() {
+        return this.config.name;
+    }
+
+    /**
+     * @param {string} baseUrl
+     */
+    async load(baseUrl) {
+        if (this.config.contigs) {
+            return;
+        }
+
+        if (this.config.baseUrl) {
+            this.baseUrl = /^http(s)?/.test(this.config.baseUrl)
+                ? this.config.baseUrl
+                : baseUrl + "/" + this.config.baseUrl;
+        } else {
+            this.baseUrl = defaultBaseUrl;
+        }
+
+        try {
+            this.setChromSizes(
+                parseChromSizes(
+                    await loader({ baseURL: this.baseUrl }).load(
+                        `${this.config.name}/${this.name}.chrom.sizes`
+                    )
+                )
+            );
+        } catch (e) {
+            throw new Error(`Could not load chrom sizes: ${e.message}`);
+        }
+    }
+
+    /**
+     *
+     * @param {Chromosome[]} chromSizes
+     */
+    setChromSizes(chromSizes) {
+        let pos = 0;
+        this.startByIndex = [0];
+
+        for (let i = 0; i < chromSizes.length; i++) {
+            this.startByIndex.push(pos);
+            const size = chromSizes[i].size;
+
+            const chrom = {
+                ...chromSizes[i],
+                continuousStart: pos,
+                continuousEnd: pos + size,
+                continuousInterval: [pos, pos + size],
+                index: i,
+                number: i + 1,
+                // eslint-disable-next-line no-bitwise
+                odd: !(i & 1),
+            };
+
+            this.chromosomes.push(chrom);
+
+            const plain = chrom.name.replace(/^chr/i, "");
+            for (const name of [
+                "chr" + plain,
+                "CHR" + plain,
+                "Chr" + plain,
+                // The number is a bit fragile because it depends on the order of the chromosomes.
+                // It probably works for autosomes, but X, Y, M, etc., not necessarily.
+                chrom.number,
+                "" + chrom.number,
+                plain,
+                chrom.name,
+            ]) {
+                this.cumulativeChromPositions.set(name, pos);
+                this.chromosomesByName.set(name, chrom);
+            }
+
+            pos += chrom.size;
+        }
+
+        this.totalSize = pos;
+    }
+
+    getExtent() {
+        return [0, this.totalSize];
+    }
+
+    /**
+     * Returns a chromosomal locus in the continuous domain
+     *
+     * @param {string | number} chrom A number or name with or without a "chr" prefix. Examples: 23, chrX, X
+     * @param {number} pos zero-based coordinate
+     */
+    toContinuous(chrom, pos) {
+        let offset = this.cumulativeChromPositions.get(chrom);
+        if (offset === undefined) {
+            throw new Error("Unknown chromosome/contig: " + chrom);
+        }
+
+        return offset + +pos;
+    }
+
+    /**
+     *
+     * @param {number} continuousPos
+     */
+    toChromosome(continuousPos) {
+        if (continuousPos >= this.totalSize) {
+            return; // TODO: Consider displaying a warning
+        }
+
+        continuousPos = Math.floor(continuousPos);
+
+        // TODO: Fix the offset by one
+        const i = bisect(this.startByIndex, continuousPos) - 1;
+        if (i > 0 && i <= this.chromosomes.length) {
+            return this.chromosomes[i - 1];
+        }
+    }
+
+    /**
+     *
+     * @param {number} continuousPos
+     * @returns {ChromosomalLocus}
+     */
+    toChromosomal(continuousPos) {
+        const chrom = this.toChromosome(continuousPos);
+        if (!chrom) {
+            return undefined;
+        }
+
+        return {
+            chrom: chrom.name,
+            pos: Math.floor(continuousPos) - chrom.continuousStart,
+        };
+    }
+
+    /**
+     *
+     * @param {string} name
+     */
+    getChromosome(name) {
+        return this.chromosomesByName.get(name);
+    }
+
+    /**
+     * Returns a UCSC Genome Browser -style string presentation of the interval.
+     * However, the interval may span multiple chromosomes, which is incompatible
+     * with UCSC.
+     *
+     * The inteval is shown as one-based closed-open range.
+     * See https://genome.ucsc.edu/FAQ/FAQtracks#tracks1
+     *
+     * @param {number[]} interval
+     * @returns {string}
+     */
+    formatInterval(interval) {
+        return formatRange(...this.toChromosomalInterval(interval));
+    }
+
+    /**
+     * @param {number[]} interval
+     * @returns {[ChromosomalLocus, ChromosomalLocus]}
+     */
+    toChromosomalInterval(interval) {
+        // Round the lower end
+        const begin = this.toChromosomal(interval[0] + 0.5);
+        // Because of the open upper bound, one is first subtracted from the upper bound and later added back.
+        const end = this.toChromosomal(interval[1] - 0.5);
+        end.pos += 1;
+
+        return [begin, end];
+    }
+
+    /**
+     * Returns a continuous interval. The optional position of the left end defaults to zero,
+     * the right end defaults to the size of the chromosome. Thus, the chromosome is inclusive
+     * when positions are omitted.
+     *
+     * @param {ChromosomalLocus[]} chromosomal
+     */
+    toContinuousInterval(chromosomal) {
+        let [a, b] = chromosomal;
+        if (!b) {
+            // A shortcut for a single chromosome. { domain: [{ chrom: "chr3" }] }
+            b = a;
+        }
+
+        return [
+            this.toContinuous(a.chrom, a.pos ?? 0),
+            this.toContinuous(
+                b.chrom,
+                b.pos ?? this.chromosomesByName.get(b.chrom)?.size
+            ),
+        ];
+    }
+
+    /**
+     *
+     * @param {string} str
+     * @returns {[number, number]}
+     */
+    parseInterval(str) {
+        // TODO: consider changing [0-9XY] to support other species besides humans
+        const matches = str.match(
+            /^(chr[0-9A-Z]+):([0-9,]+)-(?:(chr[0-9A-Z]+):)?([0-9,]+)$/
+        );
+
+        if (matches) {
+            const startChr = matches[1];
+            const endChr = matches[3] || startChr;
+
+            const startIndex = parseInt(matches[2].replace(/,/g, ""));
+            const endIndex = parseInt(matches[4].replace(/,/g, ""));
+
+            return [
+                this.toContinuous(startChr, startIndex - 1),
+                this.toContinuous(endChr, endIndex),
+            ];
+        }
+    }
+}
+
+/**
+ *
+ * @param {string} chromSizesData
+ */
+export function parseChromSizes(chromSizesData) {
+    // TODO: Support other organisms too
+    return tsvParseRows(chromSizesData)
+        .filter((row) => /^chr[0-9A-Z]+$/.test(row[0]))
+        .map(([name, size]) => ({ name, size: parseInt(size) }));
+}
+
+/**
+ *
+ * @param {any} value
+ * @return {value is ChromosomalLocus}
+ */
+export function isChromosomalLocus(value) {
+    return isObject(value) && "chrom" in value;
+}
+
+/**
+ *
+ * @param {any[]} value
+ * @return {value is ChromosomalLocus[]}
+ */
+export function isChromosomalLocusInterval(value) {
+    return value.every(isChromosomalLocus);
+}

package/src/genome/genome.test.js

@@ -0,0 +1,152 @@
+import Genome from "./genome";
+
+describe("Human genome, chromosome names prefixed with 'chr'", () => {
+    // Actually, the chromosomes are just named as in hg38, for example
+    const chromosomes = [
+        { name: "chr1", size: 10 },
+        { name: "chr2", size: 20 },
+        { name: "chr3", size: 30 },
+        { name: "chrX", size: 40 },
+    ];
+
+    const g = new Genome({ name: "random", contigs: chromosomes });
+
+    test("Maps chromosome names to continuous", () => {
+        expect(() => g.toContinuous("chr0", 2)).toThrow();
+        expect(g.toContinuous("chr1", 0)).toEqual(0);
+        expect(g.toContinuous("chr1", 2)).toEqual(2);
+        expect(g.toContinuous("chr2", 2)).toEqual(12);
+        expect(g.toContinuous("chrX", 2)).toEqual(62);
+        // TODO: Should this throw to alert about invalid data..?
+        // TODO: expect(m.toContinuous("chrX", 40)).toBeUndefined();
+    });
+
+    test("Maps chromosome numbers to continuous", () => {
+        expect(() => g.toContinuous(0, 2)).toThrow();
+        expect(g.toContinuous(1, 2)).toEqual(2);
+        expect(g.toContinuous(2, 2)).toEqual(12);
+        expect(g.toContinuous(4, 2)).toEqual(62);
+        expect(() => g.toContinuous(5, 2)).toThrow();
+    });
+
+    test("Maps unprefixed names to continuous", () => {
+        expect(() => g.toContinuous("0", 2)).toThrow();
+        expect(g.toContinuous("1", 2)).toEqual(2);
+        expect(g.toContinuous("2", 2)).toEqual(12);
+        expect(g.toContinuous("X", 2)).toEqual(62);
+        expect(() => g.toContinuous("Y", 2)).toThrow();
+    });
+
+    test("Maps string positions to continuous", () => {
+        expect(g.toContinuous("2", /** @type {any} */ ("2"))).toEqual(12);
+    });
+
+    test("Maps continuous to chromosome and locus", () => {
+        expect(g.toChromosomal(-1)).toBeUndefined();
+        expect(g.toChromosomal(0)).toEqual({ chrom: "chr1", pos: 0 });
+        expect(g.toChromosomal(12)).toEqual({ chrom: "chr2", pos: 2 });
+        expect(g.toChromosomal(29)).toEqual({ chrom: "chr2", pos: 19 });
+        expect(g.toChromosomal(30)).toEqual({ chrom: "chr3", pos: 0 });
+        expect(g.toChromosomal(62)).toEqual({ chrom: "chrX", pos: 2 });
+        expect(g.toChromosomal(99)).toEqual({ chrom: "chrX", pos: 39 });
+        expect(g.toChromosomal(100)).toBeUndefined();
+    });
+
+    // Testing half-open intervals
+    test("Maps continuous interval to chromosomal interval", () => {
+        expect(g.toChromosomalInterval([0, 10])).toEqual([
+            { chrom: "chr1", pos: 0 },
+            { chrom: "chr1", pos: 10 },
+        ]);
+        expect(g.toChromosomalInterval([10, 100])).toEqual([
+            { chrom: "chr2", pos: 0 },
+            { chrom: "chrX", pos: 40 },
+        ]);
+        expect(g.toChromosomalInterval([0, 100])).toEqual([
+            { chrom: "chr1", pos: 0 },
+            { chrom: "chrX", pos: 40 },
+        ]);
+    });
+
+    test("Maps interval with fractional parts to chromosomal interval", () => {
+        expect(g.toChromosomalInterval([0.1, 99.9])).toEqual([
+            { chrom: "chr1", pos: 0 },
+            { chrom: "chrX", pos: 40 },
+        ]);
+        expect(g.toChromosomalInterval([0.6, 99.4])).toEqual([
+            { chrom: "chr1", pos: 1 },
+            { chrom: "chrX", pos: 39 },
+        ]);
+    });
+
+    test("Maps chromosomal interval to continuous interval", () => {
+        expect(
+            g.toContinuousInterval([
+                { chrom: "chr1", pos: 0 },
+                { chrom: "chr1", pos: 10 },
+            ])
+        ).toEqual([0, 10]);
+        expect(
+            g.toContinuousInterval([
+                { chrom: "chr1", pos: 1 },
+                { chrom: "chr1", pos: 9 },
+            ])
+        ).toEqual([1, 9]);
+        expect(
+            g.toContinuousInterval([
+                { chrom: "chr2", pos: 0 },
+                { chrom: "chrX", pos: 40 },
+            ])
+        ).toEqual([10, 100]);
+        expect(
+            g.toContinuousInterval([
+                { chrom: "chr1", pos: 0 },
+                { chrom: "chrX", pos: 40 },
+            ])
+        ).toEqual([0, 100]);
+    });
+
+    test("Maps chromosomal interval without positions to continuous interval", () => {
+        expect(
+            g.toContinuousInterval([{ chrom: "chr1" }, { chrom: "chr1" }])
+        ).toEqual([0, 10]);
+        expect(
+            g.toContinuousInterval([{ chrom: "chr2" }, { chrom: "chrX" }])
+        ).toEqual([10, 100]);
+    });
+
+    test("Returns a properly annotated chromosomes array", () => {
+        expect(g.chromosomes[1]).toEqual({
+            name: "chr2",
+            size: 20,
+            index: 1,
+            number: 2,
+            continuousStart: 10,
+            continuousEnd: 30,
+            continuousInterval: [10, 30],
+            odd: false,
+        });
+    });
+});
+
+describe("C. elegans genome, chromosome names prefixed with 'chr'", () => {
+    const chromosomes = [
+        { name: "chrI", size: 15072434 },
+        { name: "chrII", size: 15279421 },
+        { name: "chrIII", size: 13783801 },
+        { name: "chrIV", size: 17493829 },
+        { name: "chrV", size: 20924180 },
+        { name: "chrX", size: 17718942 },
+        { name: "chrM", size: 13794 },
+    ];
+
+    const g = new Genome({ name: "random", contigs: chromosomes });
+
+    test("Maps chromosome names to continuous", () => {
+        expect(g.toContinuous("chrIII", 10)).toEqual(30351865);
+    });
+
+    test("Maps unprefixed names to continuous", () => {
+        expect(g.toContinuous("III", 10)).toEqual(30351865);
+    });
+});

package/src/genome/genomeStore.js

@@ -0,0 +1,54 @@
+import Genome from "./genome";
+
+export default class GenomeStore {
+    /**
+     * @param {import("../genomeSpy").default} genomeSpy
+     */
+    constructor(genomeSpy) {
+        /** @type {Map<string, Genome>} */
+        this.genomes = new Map();
+        this.genomeSpy = genomeSpy;
+    }
+
+    /**
+     * @param {import("../spec/genome").GenomeConfig} genomeConfig
+     */
+    // eslint-disable-next-line require-await
+    async initialize(genomeConfig) {
+        const genome = new Genome(genomeConfig);
+        this.genomes.set(genome.name, genome);
+
+        return Promise.all(
+            [...this.genomes.values()].map((genome) =>
+                genome.load(this.genomeSpy.spec.baseUrl)
+            )
+        );
+    }
+
+    /**
+     * @param {string} [name] If not given, a default genome is returned.
+     * @returns {Genome}
+     */
+    getGenome(name) {
+        if (!this.genomes.size) {
+            throw new Error("No genomes have been configured!");
+        }
+
+        if (name) {
+            const genome = this.genomes.get(name);
+            if (!genome) {
+                throw new Error(
+                    `No genome with the name ${name} has been configured!`
+                );
+            }
+            return genome;
+        } else {
+            if (this.genomes.size > 1) {
+                throw new Error(
+                    "Cannot pick a default genome! More than one have been configured!"
+                );
+            }
+            return this.genomes.values().next().value;
+        }
+    }
+}

package/src/genome/locusFormat.js

@@ -0,0 +1,31 @@
+import { format as d3format } from "d3-format";
+
+const numberFormat = d3format(",d");
+
+/**
+ * @typedef {import("./genome").ChromosomalLocus} ChromosomalLocus
+ */
+
+/**
+ * @param {ChromosomalLocus} locus
+ */
+export function formatLocus(locus) {
+    return locus.chrom + ":" + numberFormat(Math.floor(locus.pos + 1));
+}
+
+/**
+ * @param {ChromosomalLocus} begin
+ * @param {ChromosomalLocus} end
+ */
+export function formatRange(begin, end) {
+    return (
+        begin.chrom +
+        ":" +
+        numberFormat(Math.floor(begin.pos + 1)) +
+        "-" +
+        (begin.chrom != end.chrom ? end.chrom + ":" : "") +
+        numberFormat(Math.ceil(end.pos))
+    );
+}
+
+// TODO: parseLocus, parseRange