@genome-spy/core 0.14.0

package/src/utils/cloner.js

@@ -0,0 +1,32 @@
+/**
+ * Creates a shallow-cloner function that ensures (hopefully) that the properties
+ * end up into the in-object storage. Offers better performance than Object.assign
+ * and saves memory.
+ *
+ * Read more at:
+ * https://mrale.ph/blog/2014/07/30/constructor-vs-objectcreate.html
+ *
+ * @param {T} template The template object that
+ * @returns {function(T):T}
+ * @template T
+ */
+export default function createCloner(template) {
+    // TODO: Check that only properties, not methods get cloned
+    const properties = Object.keys(template);
+
+    const cloner = /** @type {function(T):T} */ (
+        new Function(
+            "source",
+            "return { " +
+                properties
+                    .map((prop) => JSON.stringify(prop))
+                    .map((prop) => `${prop}: source[${prop}]`)
+                    .join(",\n") +
+                " };"
+        )
+    );
+
+    cloner.properties = properties;
+
+    return cloner;
+}

package/src/utils/cloner.test.js

@@ -0,0 +1,23 @@
+import createCloner from "./cloner";
+
+const template = {
+    a: 1,
+    b: "xyzzy",
+    3: "iddqd",
+};
+
+test("Cloner clones object properly", () => {
+    const makeClone = createCloner(template);
+
+    expect(makeClone(template)).toEqual(template);
+    expect(makeClone(template)).not.toBe(template);
+
+    const another = {
+        a: 2,
+        b: "idkfa",
+        3: "hello",
+    };
+
+    expect(makeClone(another)).toEqual(another);
+    expect(makeClone(another)).not.toBe(another);
+});

package/src/utils/coalesce.js

@@ -0,0 +1,11 @@
+/**
+ *
+ * @param {any[]} candidates
+ */
+export default function coalesce(...candidates) {
+    for (const candidate of candidates) {
+        if (candidate !== undefined) {
+            return candidate;
+        }
+    }
+}

package/src/utils/coalesce.test.js

@@ -0,0 +1,15 @@
+import coalesce from "./coalesce";
+
+test("Coalesce returns first defined value", () => {
+    expect(coalesce(0, 1, 2, 3)).toEqual(0);
+    expect(coalesce(undefined, 1, 2, 3)).toEqual(1);
+    expect(coalesce(undefined, undefined, 2, 3)).toEqual(2);
+});
+
+test("Coalesce returns undefined if input is all-undefined", () => {
+    expect(coalesce(undefined, undefined)).toBeUndefined();
+});
+
+test("Coalesce returns undefined on empty input", () => {
+    expect(coalesce()).toBeUndefined();
+});

package/src/utils/concatIterables.js

@@ -0,0 +1,26 @@
+/**
+ *
+ * @param  {...Iterable} iterables
+ */
+export default function concatIterables(...iterables) {
+    if (iterables.length <= 0) {
+        return {
+            *[Symbol.iterator]() {
+                //
+            },
+        };
+    }
+
+    let currentIterable = iterables.shift();
+
+    return {
+        *[Symbol.iterator]() {
+            do {
+                for (const value of currentIterable) {
+                    yield value;
+                }
+                currentIterable = iterables.shift();
+            } while (currentIterable);
+        },
+    };
+}

package/src/utils/concatIterables.test.js

@@ -0,0 +1,7 @@
+import concatIterables from "./concatIterables";
+
+test("ConcatIterables yields all elements in the correct order", () => {
+    expect([...concatIterables([1, 2], [3, 4], [5, 6, 7], [-1000])]).toEqual([
+        1, 2, 3, 4, 5, 6, 7, -1000,
+    ]);
+});

package/src/utils/debounce.js

@@ -0,0 +1,37 @@
+/**
+ * @param {(...args:T) => R} func
+ * @param {number} wait
+ * @template {any[]} T
+ * @template R
+ */
+export function debounce(func, wait, rejectOnDebounce = true) {
+    /** @type {number} */
+    let timeout;
+
+    /** @type {(reason?: any) => void} */
+    let rejectPrevious = (_) => undefined;
+
+    /**
+     * @param {T} args
+     * @return {Promise<R>} */
+    const debouncer = function debouncer(...args) {
+        return new Promise((resolve, reject) => {
+            const later = () => {
+                clearTimeout(timeout);
+                rejectPrevious = (_) => undefined;
+
+                resolve(func(...args));
+            };
+
+            if (rejectOnDebounce) {
+                rejectPrevious("debounced");
+            }
+            clearTimeout(timeout);
+
+            rejectPrevious = reject;
+            timeout = setTimeout(later, wait);
+        });
+    };
+
+    return debouncer;
+}

package/src/utils/domainArray.js

@@ -0,0 +1,224 @@
+/**
+ * @typedef {boolean | number | string} scalar
+ */
+
+export class DomainArray /** @type {Array<scalar>} */ extends Array {
+    constructor() {
+        super();
+        /** @type {string} */
+        this.type = undefined;
+    }
+
+    /**
+     *
+     * @param {scalar} value
+     * @returns {DomainArray}
+     */
+    extend(value) {
+        return this;
+    }
+
+    /**
+     *
+     * @param {Iterable<scalar>} values
+     * @returns {DomainArray}
+     */
+    extendAll(values) {
+        if (values instanceof DomainArray && values.type != this.type) {
+            throw new Error(
+                `Cannot combine different types of domains: ${this.type} and ${values.type}`
+            );
+        }
+
+        for (const value of values) {
+            this.extend(value);
+        }
+
+        return this;
+    }
+
+    /**
+     * @param {Iterable<T>} values
+     * @param {function(T):scalar} [accessor]
+     * @returns {DomainArray}
+     * @template T
+     */
+    extendAllWithAccessor(values, accessor) {
+        for (const value of values) {
+            this.extend(accessor(value));
+        }
+
+        return this;
+    }
+}
+
+export class QuantitativeDomain extends DomainArray {
+    constructor() {
+        super();
+        this.type = "quantitative";
+    }
+
+    /**
+     *
+     * @param {scalar} value
+     * @returns {DomainArray}
+     */
+    extend(value) {
+        if (value === null || value === undefined || Number.isNaN(value)) {
+            return this;
+        }
+
+        value = +value;
+
+        if (this.length) {
+            if (value < this[0]) {
+                this[0] = value;
+            } else if (value > this[1]) {
+                this[1] = value;
+            }
+        } else {
+            this.push(value);
+            this.push(value);
+        }
+
+        return this;
+    }
+}
+
+/**
+ * Builder that tries to preserve the order
+ */
+export class OrdinalDomain extends DomainArray {
+    constructor() {
+        super();
+        this.type = "ordinal";
+
+        /** @type {Set<scalar>} */
+        this.uniqueValues = new Set();
+    }
+
+    /**
+     *
+     * @param {scalar} value
+     * @returns {DomainArray}
+     */
+    extend(value) {
+        if (value === null || value === undefined || Number.isNaN(value)) {
+            return this;
+        }
+
+        if (!this.uniqueValues.has(value)) {
+            this.uniqueValues.add(value);
+            this.push(value);
+        }
+
+        return this;
+    }
+}
+
+export class NominalDomain extends OrdinalDomain {
+    constructor() {
+        super();
+        this.type = "nominal";
+    }
+}
+
+export class PiecewiseDomain extends DomainArray {
+    /**
+     *
+     * @param {number[]} initialDomain
+     */
+    constructor(initialDomain) {
+        super();
+
+        let sum = 0;
+        for (let i = 1; i < initialDomain.length; i++) {
+            sum += Math.sign(initialDomain[i] - initialDomain[i - 1]);
+        }
+        if (Math.abs(sum) != initialDomain.length - 1) {
+            throw new Error(
+                "Piecewise domain must be strictly increasing or decreasing: " +
+                    JSON.stringify(initialDomain)
+            );
+        }
+
+        initialDomain.forEach((x) => this.push(x));
+    }
+
+    /**
+     *
+     * @param {scalar} value
+     * @returns {DomainArray}
+     */
+    extend(value) {
+        if (this.includes(value)) {
+            return this;
+        }
+
+        throw new Error(
+            "Piecewise domains are immutable and cannot be unioned!"
+        );
+    }
+}
+
+/**
+ * @type Object.<string, typeof DomainArray>
+ */
+const domainTypes = {
+    quantitative: QuantitativeDomain,
+    index: QuantitativeDomain,
+    locus: QuantitativeDomain,
+    nominal: NominalDomain,
+    ordinal: OrdinalDomain,
+};
+
+/**
+ *
+ * @param {string} type
+ * @param {scalar[]} [initialDomain]
+ */
+export default function createDomain(type, initialDomain) {
+    if (type == "quantitative" && isPiecewiseArray(initialDomain)) {
+        const b = new PiecewiseDomain(/** @type {number[]} */ (initialDomain));
+        b.type = type;
+        return b;
+    } else if (domainTypes[type]) {
+        const b = new domainTypes[type]();
+        b.type = type;
+        if (initialDomain) {
+            b.extendAll(initialDomain);
+        }
+        return b;
+    }
+
+    throw new Error("Unknown type: " + type);
+}
+
+/**
+ *
+ * @param {array} array
+ */
+export function isDomainArray(array) {
+    return array instanceof DomainArray;
+}
+
+/**
+ * For unit tests
+ *
+ * @param {DomainArray | any[]} domainArray
+ */
+export function toRegularArray(domainArray) {
+    return [...domainArray];
+}
+
+/**
+ * @param {scalar[]} array
+ */
+function isPiecewiseArray(array) {
+    return (
+        array &&
+        array.length > 0 &&
+        array.length != 2 &&
+        array.every((x) => typeof x === "number")
+    );
+}

package/src/utils/domainArray.test.js

@@ -0,0 +1,129 @@
+import createDomain, {
+    toRegularArray as r,
+    PiecewiseDomain,
+} from "./domainArray";
+
+describe("Build quantitative domains", () => {
+    test("Empty domain", () => {
+        const b = createDomain("quantitative");
+        expect(r(b)).toEqual([]);
+    });
+
+    test("Extends by one value at a time", () => {
+        const b = createDomain("quantitative");
+        b.extend(2);
+        b.extend(1);
+        b.extend(null);
+        b.extend(undefined);
+        b.extend(NaN);
+        b.extend(5);
+        b.extend(4);
+        expect(r(b)).toEqual([1, 5]);
+    });
+
+    test("Extends with an iterable", () => {
+        const b = createDomain("quantitative");
+        b.extendAll([2, 1, null, undefined, NaN, 5, 4]);
+        expect(r(b)).toEqual([1, 5]);
+    });
+
+    test("Extends with an iterable and an accessor", () => {
+        const b = createDomain("quantitative");
+        b.extendAllWithAccessor(
+            [
+                { x: 2 },
+                { x: 1 },
+                { x: null },
+                { x: undefined },
+                { x: NaN },
+                { x: 5 },
+                { x: 4 },
+            ],
+            (d) => d.x
+        );
+        expect(r(b)).toEqual([1, 5]);
+    });
+
+    test("Coerces to number", () => {
+        const b = createDomain("quantitative");
+        expect(r(b.extend("123"))).toEqual([123, 123]);
+    });
+});
+
+describe("Build ordinal domains", () => {
+    // Note: nominal is an unordered abstraction of ordinal. Testing just ordinal is enough.
+
+    test("Empty domain", () => {
+        const b = createDomain("ordinal");
+        expect(r(b)).toEqual([]);
+    });
+
+    test("Extends by one value at a time, preserves order", () => {
+        const b = createDomain("ordinal");
+        b.extend("a");
+        b.extend("b");
+        b.extend("c");
+        b.extend("b");
+        b.extend(null);
+        b.extend(undefined);
+        b.extend(NaN);
+        b.extend("d");
+        expect(r(b)).toEqual(["a", "b", "c", "d"]);
+    });
+});
+
+describe("Build piecewise domains", () => {
+    test("Creates a piecewise domain", () => {
+        expect(createDomain("quantitative", [1])).toBeInstanceOf(
+            PiecewiseDomain
+        );
+        expect(createDomain("quantitative", [1, 2, 3])).toBeInstanceOf(
+            PiecewiseDomain
+        );
+        expect(createDomain("quantitative", [1, 2, 3, 4])).toBeInstanceOf(
+            PiecewiseDomain
+        );
+        expect(createDomain("quantitative", [3, 2, 1])).toBeInstanceOf(
+            PiecewiseDomain
+        );
+        expect(r(createDomain("quantitative", [3, 2, 1]))).toEqual([3, 2, 1]);
+    });
+
+    test("Throws on domain that is not stricly increasing or decreasing", () => {
+        expect(() => createDomain("quantitative", [2, 1, 3])).toThrow();
+        expect(() => createDomain("quantitative", [2, 3, 1])).toThrow();
+        expect(() => createDomain("quantitative", [3, 0, 2])).toThrow();
+        expect(() => createDomain("quantitative", [0, 3, 2])).toThrow();
+        expect(() => createDomain("quantitative", [1, 2, 2, 3])).toThrow();
+    });
+
+    test("Throws on mutation attempts", () => {
+        expect(() =>
+            createDomain("quantitative", [1, 2, 3]).extend(4)
+        ).toThrow();
+    });
+
+    test("Does not throw when extending with existing value", () => {
+        expect(r(createDomain("quantitative", [1, 2, 3]).extend(2))).toEqual([
+            1, 2, 3,
+        ]);
+    });
+});
+
+describe("Annotations", () => {
+    test("Quantitative domain is annotated", () =>
+        expect(createDomain("quantitative").type).toEqual("quantitative"));
+
+    test("Ordinal domain is annotated", () =>
+        expect(createDomain("ordinal").type).toEqual("ordinal"));
+
+    test("Nominal domain is annotated", () =>
+        expect(createDomain("nominal").type).toEqual("nominal"));
+});
+
+describe("Other stuff", () => {
+    test("Throws on extending by other type of domain array", () =>
+        expect(() =>
+            createDomain("quantitative").extendAll(createDomain("nominal"))
+        ).toThrow());
+});

package/src/utils/eerp.js

@@ -0,0 +1,13 @@
+/**
+ * Exponential interpolation
+ *
+ * https://twitter.com/FreyaHolmer/status/1068293398073929728
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} t
+ * @returns
+ */
+export default function (a, b, t) {
+    return a * Math.pow(b / a, t);
+}

package/src/utils/expression.js

@@ -0,0 +1,32 @@
+import { parseExpression, codegenExpression } from "vega-expression";
+
+/**
+ *
+ * @param {string} expr
+ */
+export default function createFunction(expr, global = {}) {
+    const cg = codegenExpression({
+        forbidden: [],
+        allowed: ["datum"],
+        globalvar: "global",
+        fieldvar: "datum",
+    });
+
+    try {
+        const parsed = parseExpression(expr);
+        const generatedCode = cg(parsed);
+
+        // eslint-disable-next-line no-new-func
+        const fn = Function(
+            "datum",
+            "global",
+            `"use strict"; return (${generatedCode.code});`
+        );
+
+        const exprFunction = /** @param {object} x */ (x) => fn(x, global);
+        exprFunction.fields = generatedCode.fields;
+        return exprFunction;
+    } catch (e) {
+        throw new Error(`Invalid expression: ${expr}, ${e.message}`);
+    }
+}

package/src/utils/field.js

@@ -0,0 +1,28 @@
+import { field as vegaField, accessor } from "vega-util";
+
+/**
+ * Creates an accessor function based on the field expression.
+ * This is equivalent to vega-util's field function but generates optimized
+ * accessors for trivial cases.
+ *
+ * Function calls with polymorphic objects spoil the inline caching that
+ * virtually all JavaScript engines use. Thus, we generate code and compile
+ * always a new function to "guarantee" homomorphims, given that only same
+ * type of objects are even passed to the accessor.
+ *
+ * Read more at: https://mrale.ph/blog/2015/01/11/whats-up-with-monomorphism.html
+ *
+ * @param {string} fieldExpr
+ * @param {string} [name]
+ */
+export function field(fieldExpr, name = fieldExpr) {
+    if (/^[A-Za-z0-9_]+$/.test(fieldExpr)) {
+        // eslint-disable-next-line no-new-func
+        const fn = /** @type {import("vega-util").AccessorFn} */ (
+            new Function("datum", `return datum[${JSON.stringify(fieldExpr)}]`)
+        );
+        return accessor(fn, [fieldExpr], name);
+    } else {
+        return vegaField(fieldExpr);
+    }
+}

package/src/utils/fisheye.js

@@ -0,0 +1,60 @@
+/**
+ * Based on:
+ * fisheye d3-plugin (c) Mike Bostock
+ * https://github.com/d3/d3-plugins/blob/master/fisheye/
+ */
+export default function () {
+    let radius = 200;
+    let distortion = 2;
+    let k0 = 1,
+        k1 = 1;
+    let focus = 0;
+
+    /**
+     *
+     * @param {number} x
+     */
+    function fisheye(x) {
+        const dx = x - focus;
+        const dd = Math.abs(dx);
+        if (!dd || dd >= radius) return x;
+        const k = ((k0 * (1 - Math.exp(-dd * k1))) / dd) * 0.75 + 0.25;
+        return focus + dx * k;
+    }
+
+    function rescale() {
+        k0 = Math.exp(distortion);
+        k0 = (k0 / (k0 - 1)) * radius;
+        k1 = distortion / radius;
+        return fisheye;
+    }
+
+    /**
+     * @param {number} _
+     */
+    fisheye.radius = function (_) {
+        if (!arguments.length) return radius;
+        radius = +_;
+        return rescale();
+    };
+
+    /**
+     * @param {number} _
+     */
+    fisheye.distortion = function (_) {
+        if (!arguments.length) return distortion;
+        distortion = +_;
+        return rescale();
+    };
+
+    /**
+     * @param {number} _
+     */
+    fisheye.focus = function (_) {
+        if (!arguments.length) return focus;
+        focus = _;
+        return fisheye;
+    };
+
+    return rescale();
+}

package/src/utils/formatObject.js

@@ -0,0 +1,31 @@
+import { isNumber, isString, isBoolean } from "vega-util";
+import { format as d3format } from "d3-format";
+import { html } from "lit-html";
+
+const numberFormat = d3format(".4~r");
+const exponentNumberFormat = d3format(".4~e");
+
+/**
+ *
+ * @param {any} object Object to format
+ */
+export default function formatObject(object) {
+    if (object === null) {
+        return html` <span class="na">NA</span> `;
+    }
+
+    if (isString(object)) {
+        return object.substring(0, 30);
+    } else if (Number.isInteger(object)) {
+        return "" + object;
+    } else if (isNumber(object)) {
+        return Math.abs(object) > Math.pow(10, 8) ||
+            Math.abs(object) < Math.pow(10, -8)
+            ? exponentNumberFormat(object)
+            : numberFormat(object);
+    } else if (isBoolean(object)) {
+        return object ? "True" : "False";
+    } else {
+        return "?" + typeof object + " " + object;
+    }
+}