@genome-spy/core 0.14.0

package/src/styles/genome-spy.scss

@@ -0,0 +1,153 @@
+@use "sass:math";
+
+$basic-spacing: 10px;
+
+$font-family: system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif,
+    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+
+.genome-spy {
+    font-family: $font-family;
+
+    position: relative;
+
+    canvas {
+        transform: scale(1, 1);
+        opacity: 1;
+        transition: transform 0.6s, opacity 0.6s;
+    }
+
+    .loading-message {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        display: flex;
+
+        align-items: center;
+        justify-content: center;
+
+        .message {
+            color: #666;
+            opacity: 0;
+            transition: opacity 0.7s;
+        }
+    }
+
+    &.loading {
+        canvas {
+            transform: scale(0.95, 0.95);
+            opacity: 0;
+        }
+
+        .loading-message .message {
+            opacity: 1;
+        }
+
+        .ellipsis {
+            animation: blinker 1s linear infinite;
+        }
+
+        @keyframes blinker {
+            50% {
+                opacity: 0;
+            }
+        }
+    }
+
+    .tooltip {
+        position: absolute;
+
+        max-width: 450px;
+        overflow: hidden;
+
+        $background-color: #f6f6f6;
+        background: $background-color;
+        padding: $basic-spacing;
+        font-size: 13px;
+
+        box-shadow: 0px 3px 15px 0px rgba(0, 0, 0, 0.21);
+
+        pointer-events: none;
+        z-index: 100;
+
+        > :last-child {
+            margin-bottom: 0;
+        }
+
+        > .title {
+            padding-bottom: math.div($basic-spacing, 2);
+            margin-bottom: math.div($basic-spacing, 2);
+            border-bottom: 1px dashed darken($background-color, 25%);
+        }
+
+        .summary {
+            font-size: 12px;
+        }
+
+        table {
+            &:first-child {
+                margin-top: 0;
+            }
+
+            border-collapse: collapse;
+
+            th,
+            td {
+                padding: 2px 0.4em;
+                vertical-align: top;
+
+                &:first-child {
+                    padding-left: 0;
+                }
+            }
+
+            th {
+                text-align: left;
+                font-weight: bold;
+            }
+        }
+
+        .color-legend {
+            display: inline-block;
+            width: 0.8em;
+            height: 0.8em;
+            margin-left: 0.4em;
+            box-shadow: 0px 0px 3px 1px white;
+        }
+
+        .attributes {
+            .hovered {
+                background-color: #e0e0e0;
+            }
+        }
+
+        .na {
+            color: #aaa;
+            font-style: italic;
+            font-size: 80%;
+        }
+    }
+
+    .gene-track-tooltip {
+        .summary {
+            font-size: 90%;
+        }
+    }
+
+    .message-box {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        position: absolute;
+        top: 0;
+        height: 100%;
+        width: 100%;
+
+        > div {
+            border: 1px solid red;
+            padding: 10px;
+            background: #fff0f0;
+        }
+    }
+}

package/src/tooltip/dataTooltipHandler.js

@@ -0,0 +1,59 @@
+import { html } from "lit-html";
+import formatObject from "../utils/formatObject";
+
+/**
+ * @type {import("./tooltipHandler").TooltipHandler}
+ */
+export default async function dataTooltipHandler(datum, mark, params) {
+    /**
+     * @param {string} key
+     * @param {object} datum
+     */
+    const legend = (key, datum) => {
+        for (const [channel, encoder] of Object.entries(mark.encoders)) {
+            if (encoder?.accessor?.fields.includes(key)) {
+                switch (channel) {
+                    case "color":
+                    case "fill":
+                    case "stroke":
+                        return html`
+                            <span
+                                class="color-legend"
+                                style=${`background-color: ${encoder(datum)}`}
+                            ></span>
+                        `;
+                    default:
+                }
+            }
+        }
+
+        return "";
+    };
+
+    const table = html`
+        <table class="attributes">
+            ${Object.entries(datum)
+                .filter(([key, value]) => !key.startsWith("_"))
+                .map(
+                    ([key, value]) => html`
+                        <tr>
+                            <th>${key}</th>
+                            <td>
+                                ${formatObject(value)} ${legend(key, datum)}
+                            </td>
+                        </tr>
+                    `
+                )}
+        </table>
+    `;
+
+    const title = mark.unitView.spec.title
+        ? html`
+              <div class="title">
+                  <strong>${mark.unitView.spec.title}</strong>
+              </div>
+          `
+        : "";
+
+    return html`${title}${table}`;
+}

package/src/tooltip/refseqGeneTooltipHandler.js

@@ -0,0 +1,77 @@
+import { debounce } from "../utils/debounce";
+import { html } from "lit-html";
+
+/*
+ * https://www.ncbi.nlm.nih.gov/books/NBK25500/
+ *
+ * TODO: Implement tool & email parameters: https://www.ncbi.nlm.nih.gov/books/NBK25497/
+ */
+
+// TODO: Replace with an LRU-cache
+const symbolSummaryCache = new Map();
+
+/**
+ * @type {import("./tooltipHandler").TooltipHandler}
+ */
+export default async function refseqGeneTooltipHandler(datum, mark, params) {
+    const symbol = datum.symbol;
+
+    let summary =
+        symbolSummaryCache.get(symbol) ??
+        (await debouncedFetchGeneSummary(datum.symbol));
+
+    if (summary) {
+        symbolSummaryCache.set(symbol, summary);
+        return html`
+            <div class="title">
+                <strong>${summary.name}</strong>
+                ${summary.description}
+            </div>
+            <p class="summary">${summary.summary}</p>
+            <p class="source">Source: NCBI RefSeq Gene</p>
+        `;
+    } else {
+        return null;
+    }
+}
+
+/**
+ * @param {string} symbol
+ */
+async function fetchGeneSummary(symbol) {
+    // TODO: Add more search terms to ensure that we really find genes specific to the current genome
+
+    console.log("Searching: " + symbol);
+
+    const opts = { mode: "cors" };
+
+    const searchResult = await fetch(
+        `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gene&term=${symbol}[GENE]&sort=relevance&retmode=json`,
+        opts
+    ).then((res) => res.json());
+
+    // TODO: Handle failed searchs
+    const id = searchResult.esearchresult.idlist[0];
+
+    if (id) {
+        const summaryResult = await fetch(
+            `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=gene&id=${id}&retmode=json`,
+            opts
+        ).then((res) => res.json());
+
+        const summary = summaryResult.result[id];
+        return summary;
+    } else {
+        return null;
+    }
+}
+
+const debounced = debounce(fetchGeneSummary, 500);
+
+/**
+ *
+ * @param {string} symbol
+ */
+function debouncedFetchGeneSummary(symbol) {
+    return debounced(symbol);
+}

package/src/tooltip/tooltipHandler.ts

@@ -0,0 +1,12 @@
+import { TemplateResult } from "lit-html";
+import Mark from "../marks/mark";
+
+/**
+ * Converts a datum to tooltip (HTMLElement or lit's TemplateResult).
+ */
+export type TooltipHandler = (
+    datum: Record<string, any>,
+    mark: Mark,
+    /** Optional parameters from the view specification */
+    params?: Record<string, any>
+) => Promise<string | TemplateResult | HTMLElement>;

package/src/types/filetypes.d.ts

@@ -0,0 +1,4 @@
+declare module "*.svg" {
+    const content: string;
+    export default content;
+}

package/src/types/flatqueue.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Adapted from: https://github.com/mourner/flatqueue/blob/master/index.d.ts
+ *
+ * A version with typings is yet be released...
+ */
+declare module "flatqueue" {
+    export default class FlatQueue<T> {
+        /**
+         * Number of items in the queue.
+         */
+        readonly length: number;
+
+        constructor();
+
+        /**
+         * Removes all items from the queue.
+         */
+        clear(): void;
+
+        /**
+         * Adds `item` to the queue with the specified `priority`.
+         *
+         * `priority` must be a number. Items are sorted and returned from low to
+         * high priority. Multiple items with the same priority value can be added
+         * to the queue, but there is no guaranteed order between these items.
+         */
+        push(item: T, priority: number): void;
+
+        /**
+         * Removes and returns the item from the head of this queue, which is one of
+         * the items with the lowest priority. If this queue is empty, returns
+         * `undefined`.
+         */
+        pop(): T | undefined;
+
+        /**
+         * Returns the item from the head of this queue without removing it. If this
+         * queue is empty, returns `undefined`.
+         */
+        peek(): T | undefined;
+
+        /**
+         * Returns the priority value of the item at the head of this queue without
+         * removing it. If this queue is empty, returns `undefined`.
+         */
+        peekValue(): number | undefined;
+
+        /**
+         * Shrinks the internal arrays to `this.length`.
+         */
+        shrink(): void;
+    }
+}

package/src/types/glsl.d.ts

@@ -0,0 +1,4 @@
+declare module "*.glsl" {
+    const glsl: string;
+    export default glsl;
+}

package/src/types/object.d.ts

@@ -0,0 +1,21 @@
+type ObjectKeys<T> = T extends object
+    ? (keyof T)[]
+    : T extends number
+    ? []
+    : T extends Array<any> | string
+    ? string[]
+    : never;
+
+interface ObjectConstructor {
+    // Source: https://fettblog.eu/typescript-better-object-keys/
+    keys<T>(o: T): ObjectKeys<T>;
+
+    // Source: https://github.com/microsoft/TypeScript/issues/35101
+    entries<T>(
+        o: T
+    ): T extends ArrayLike<infer U>
+        ? [string, U][]
+        : { [K in keyof T]: [K, T[K]] }[keyof T][];
+
+    values<T>(o: T): T extends ArrayLike<infer U> ? U[] : T[keyof T][];
+}

package/src/types/vega-scale.d.ts

@@ -0,0 +1,60 @@
+type MetaDatum =
+    | "continuous"
+    | "discrete"
+    | "discretizing"
+    | "interpolating"
+    | "log"
+    | "temporal";
+
+type Color = string;
+type Interpolator<T> = (t: number) => T;
+type ColorInterpolator = Interpolator<Color>;
+
+declare module "vega-scale" {
+    // TODO: Correct return type
+    export function scale(
+        type: string,
+        scale: () => any,
+        metadata: MetaDatum | MetaDatum[]
+    ): any;
+
+    export function scheme(
+        name: string,
+        scheme: string[] | ColorInterpolator
+    ): void;
+    export function scheme(name: string): ColorInterpolator;
+
+    // TODO: Correct return type
+    export function interpolate(name: string, gamma?: number): any;
+
+    export function interpolateColors(
+        colors: Color[],
+        type?: string,
+        gamma?: number
+    ): ColorInterpolator;
+
+    export function interpolateRange<T>(
+        interpolator: Interpolator<T>,
+        range: number[]
+    ): Interpolator<T>;
+
+    export function quantizeInterpolator<T>(
+        interpolator: Interpolator<T>,
+        count: number
+    ): T[];
+
+    export function isValidScaleType(type: string): boolean;
+    export function isContinuous(key: string): boolean;
+    export function isDiscrete(key: string): boolean;
+    export function isDiscretizing(key: string): boolean;
+    export function isLogarithmic(key: string): boolean;
+    export function isTemporal(key: string): boolean;
+    export function isInterpolating(key: string): boolean;
+    export function isQuantile(key: string): boolean;
+
+    export function bandSpace(
+        count: number,
+        paddingInner: number,
+        paddingOuter: number
+    ): number;
+}

package/src/utils/animator.js

@@ -0,0 +1,83 @@
+import doTransition from "./transition";
+
+export default class Animator {
+    /**
+     *
+     * @param {function(number):void} renderCallback
+     */
+    constructor(renderCallback) {
+        this._renderCallback = renderCallback;
+        this._renderRequested = false;
+        this._warn = false;
+
+        /** @type {(function(number):void)[]} */
+        this.transitions = [];
+    }
+
+    /**
+     * Schedules a "transition" to be called before the actual rendering
+     * is preformed. The transition could adjust the layout, for example.
+     * This method also requests rendering to be performed.
+     *
+     * If the callback has already been requested (compared by identity),
+     * it is removed from the queue and added to the end.
+     *
+     * @param {function(number):void} callback
+     */
+    requestTransition(callback) {
+        this.cancelTransition(callback);
+        this.transitions.push(callback);
+        this.requestRender();
+    }
+
+    /**
+     * @param {function(number):void} callback
+     */
+    cancelTransition(callback) {
+        const existingIndex = this.transitions.indexOf(callback);
+        if (existingIndex >= 0) {
+            this.transitions.splice(existingIndex, 1);
+        }
+    }
+
+    /**
+     * Requests the request transitions and rendering callback to be called
+     * during the next animation frame. Redundant calls to this method are safe,
+     * they have no effect.
+     */
+    requestRender() {
+        if (!this._renderRequested) {
+            this._renderRequested = true;
+            window.requestAnimationFrame((timestamp) => {
+                this._renderRequested = false;
+
+                const transitions = this.transitions;
+                this.transitions = [];
+
+                /** @type {function} */
+                let transitionCallback;
+                while ((transitionCallback = transitions.shift())) {
+                    transitionCallback(timestamp);
+                }
+
+                this._renderCallback(timestamp);
+            });
+        } else if (this._warn) {
+            console.warn("Render already requested!");
+        }
+    }
+
+    /**
+     * Initiates a transition with a `requestAnimationFrame` that is synced
+     * with this Animator instance.
+     *
+     * @param {import("./transition").TransitionOptions} options
+     */
+    transition(options) {
+        return doTransition({
+            requestAnimationFrame: (callback) =>
+                this.requestTransition(callback),
+            ...options,
+        });
+    }
+}

package/src/utils/arrayUtils.js

@@ -0,0 +1,55 @@
+/**
+ *
+ * @param {A[]} a
+ * @param {B[]} b
+ * @param {function(A):T} [aAccessor]
+ * @param {function(B):T} [bAccessor]
+ * @template A, B, T
+ */
+export function shallowArrayEquals(a, b, aAccessor, bAccessor) {
+    aAccessor = aAccessor || ((x) => x);
+    bAccessor = bAccessor || ((x) => x);
+    return (
+        a.length == b.length &&
+        a.every((s, i) => aAccessor(a[i]) === bAccessor(b[i]))
+    );
+}
+
+/**
+ *
+ * @param {any[]} a
+ */
+export function isHomogeneous(a) {
+    if (a.length <= 1) {
+        return true;
+    }
+
+    const first = a[0];
+    return a.every((x) => x === first);
+}
+
+/**
+ * @param {T[] | T} obj
+ * @returns {T[]}
+ * @template T
+ */
+export function asArray(obj) {
+    if (Array.isArray(obj)) {
+        return obj;
+    } else if (typeof obj != "undefined") {
+        return [obj];
+    } else {
+        return [];
+    }
+}
+
+/**
+ * Returns the last element of an array.
+ * Like vega-util's peek but with stricter typings
+ *
+ * @param {T[]} arr
+ * @template T
+ */
+export function peek(arr) {
+    return arr[arr.length - 1];
+}

package/src/utils/binnedRangeIndex.js

@@ -0,0 +1,83 @@
+import clamp from "./clamp";
+
+const MAX_INTEGER = 2 ** 31 - 1;
+
+/**
+ * @callback Lookup
+ * @param {number} start
+ * @param {number} end
+ * @returns {[number, number]}
+ */
+
+/**
+ * A binned index for (overlapping) ranges that are sorted by their start position.
+ * Allows for indexing vertices of mark instances.
+ *
+ * @param {number} size Number of bins
+ * @param {[number, number]} domain
+ */
+export default function createBinningRangeIndexer(size, domain) {
+    const startIndices = new Int32Array(size);
+    startIndices.fill(MAX_INTEGER);
+
+    const endIndices = new Int32Array(size);
+
+    const start = domain[0];
+    const domainLength = domain[1] - domain[0];
+    const divisor = domainLength / size;
+
+    /** @param {number} pos */
+    const getBin = (pos) =>
+        clamp(Math.floor((pos - start) / divisor), 0, size - 1);
+
+    /**
+     *
+     * @param {number} start
+     * @param {number} end
+     * @param {number} startIndex
+     * @param {number} endIndex
+     */
+    const indexer = (start, end, startIndex, endIndex) => {
+        const startBin = getBin(start);
+        const endBin = getBin(end);
+
+        // TODO: This loop could probably be done as a more efficient post processing
+        // step.
+        for (let bin = startBin; bin <= endBin; bin++) {
+            if (startIndices[bin] > startIndex) {
+                startIndices[bin] = startIndex;
+            }
+
+            if (endIndices[bin] < endIndex) {
+                endIndices[bin] = endIndex;
+            }
+        }
+    };
+
+    /**
+     * @type {Lookup}
+     */
+    const lookup = (start, end) => [
+        startIndices[getBin(start)],
+        endIndices[getBin(end)],
+    ];
+
+    const getIndex = () => {
+        for (let i = 1; i < endIndices.length; i++) {
+            if (endIndices[i] < endIndices[i - 1]) {
+                endIndices[i] = endIndices[i - 1];
+            }
+        }
+        for (let i = endIndices.length - 1; i > 0; i--) {
+            if (endIndices[i - 1] > endIndices[i]) {
+                endIndices[i - 1] = endIndices[i];
+            }
+        }
+
+        return lookup;
+    };
+
+    indexer.getIndex = getIndex;
+
+    return indexer;
+}

package/src/utils/clamp.js

@@ -0,0 +1,8 @@
+/**
+ * @param {number} value
+ * @param {number} [min]
+ * @param {number} [max]
+ */
+export default function clamp(value, min = 0, max = 1) {
+    return Math.max(min, Math.min(max, value));
+}