@genome-spy/core 0.14.0

package/src/view/flowBuilder.js

@@ -0,0 +1,362 @@
+import Collector from "../data/collector";
+import createTransform from "../data/transforms/transformFactory";
+import createDataSource from "../data/sources/dataSourceFactory";
+import UnitView from "./unitView";
+import { BEHAVIOR_MODIFIES } from "../data/flowNode";
+import CloneTransform from "../data/transforms/clone";
+import { isDynamicCallbackData } from "../data/sources/dynamicCallbackSource";
+import DataFlow from "../data/dataFlow";
+import DataSource from "../data/sources/dataSource";
+import {
+    isChannelDefWithScale,
+    isChromPosDef,
+    isDatumDef,
+    isFieldDef,
+    isPositionalChannel,
+    getPrimaryChannel,
+} from "../encoder/encoder";
+import LinearizeGenomicCoordinate from "../data/transforms/linearizeGenomicCoordinate";
+import { isAggregateSamplesSpec } from "./viewFactory";
+import { group } from "d3-array";
+import IdentifierTransform from "../data/transforms/identifier";
+import { invalidate } from "../utils/propertyCacher";
+import NamedSource, { isNamedData } from "../data/sources/namedSource";
+
+/**
+ * @typedef {import("./view").default} View
+ * @typedef {import("../data/flowNode").default} FlowNode
+ * @typedef {import("../spec/channel").Channel} Channel
+ * @typedef {import("../spec/channel").Encoding} Encoding
+ *
+ * @param {View} root
+ * @param {DataFlow<View>} [existingFlow] Add data flow
+ *      graphs to an existing DataFlow object.
+ */
+export function buildDataFlow(root, existingFlow) {
+    /** @type {FlowNode[]} "Current nodes" on the path from view root to the current view */
+    const nodeStack = [];
+
+    /** @type {FlowNode} */
+    let currentNode;
+
+    /** @type {DataFlow<View>} */
+    const dataFlow = existingFlow ?? new DataFlow();
+
+    /** @type {(function():void)[]} */
+    const postProcessOps = [];
+
+    /**
+     * @param {FlowNode} node
+     * @param {function():Error} [onMissingParent]
+     * @returns {FlowNode} The appended node
+     */
+    function appendNode(node, onMissingParent = () => undefined) {
+        if (!currentNode) {
+            throw (
+                onMissingParent() ||
+                new Error("Cannot append data flow node, no parent exist!")
+            );
+        }
+        currentNode.addChild(node);
+        currentNode = node;
+        return node;
+    }
+
+    /**
+     * @param {FlowNode} transform
+     * @param {any} [params]
+     * @returns {FlowNode} The appended node
+     */
+    function appendTransform(transform, params) {
+        return appendNode(
+            transform,
+            () =>
+                new Error(
+                    `Cannot append a transform because no (inherited) data are available! ${
+                        params ? JSON.stringify(params) : ""
+                    }`
+                )
+        );
+    }
+
+    /**
+     *
+     * @param {import("../spec/transform").TransformParams[]} transforms
+     * @param {View} view
+     */
+    function createTransforms(transforms, view) {
+        for (const params of transforms) {
+            /** @type {FlowNode} */
+            let transform;
+            try {
+                transform = createTransform(params, view);
+            } catch (e) {
+                console.warn(e);
+                throw new Error(
+                    `Cannot initialize "${params.type}" transform: ${e}`
+                );
+            }
+
+            if (transform.behavior & BEHAVIOR_MODIFIES) {
+                // Make defensive copies before every modifying transform to
+                // ensure that modifications don't inadvertently become visible
+                // in other branches of the flow.
+                // These can be later optimized away where possible.
+                appendTransform(new CloneTransform());
+            }
+            appendTransform(transform);
+        }
+    }
+
+    /** @param {View} view */
+    const processView = (view) => {
+        nodeStack.push(currentNode);
+
+        if (view.spec.data) {
+            const dataSource = isDynamicCallbackData(view.spec.data)
+                ? view.getDynamicDataSource()
+                : isNamedData(view.spec.data)
+                ? new NamedSource(view.spec.data, view.context.getNamedData)
+                : createDataSource(view.spec.data, view.getBaseUrl());
+
+            currentNode = dataSource;
+            dataFlow.addDataSource(dataSource, view);
+        }
+
+        if (view.spec.transform) {
+            createTransforms(view.spec.transform, view);
+        }
+
+        if (view instanceof UnitView) {
+            if (!currentNode) {
+                throw new Error("A unit view has no (inherited) data source");
+            }
+
+            // Support chrom/pos channelDefs
+            const linearize = linearizeLocusAccess(view);
+            if (linearize) {
+                postProcessOps.push(linearize.rewrite);
+                for (const transform of linearize.transforms) {
+                    // TODO: Transforms should not be added if they already exist in the flow.
+                    // Alternatively they should be optimized away.
+                    // TODO: Add CloneTransform
+                    appendTransform(transform);
+                }
+            }
+
+            if (view.mark.isPickingParticipant()) {
+                // TODO: Add CloneTransform
+                appendTransform(
+                    new IdentifierTransform({ type: "identifier" })
+                );
+            }
+
+            const collector = new Collector({
+                type: "collect",
+                groupby: view.getFacetFields(),
+                sort: getCompareParamsForView(
+                    view,
+                    linearize?.rewrittenEncoding
+                ),
+            });
+
+            appendNode(collector);
+            dataFlow.addCollector(collector, view);
+        }
+
+        if (isAggregateSamplesSpec(view.spec)) {
+            // TODO: implement summarization of layer views
+        }
+    };
+
+    /** @param {View} view */
+    processView.postOrder = (view) => {
+        currentNode = nodeStack.pop();
+    };
+
+    root.visit(processView);
+
+    postProcessOps.forEach((op) => op());
+
+    return dataFlow;
+}
+
+/**
+ * Changes the ChromPos channelDefs into FieldDefs and returns
+ * LinearizeGenomicCoordinate transform(s) that should be inserted into
+ * the data flow.
+ *
+ * @param {View} view
+ */
+export function linearizeLocusAccess(view) {
+    /** @type {FlowNode[]} */
+    const transforms = [];
+
+    /** @type {Encoding} */
+    const rewrittenEncoding = {};
+
+    /** @type {{ channel: Channel, chromPosDef: import("../spec/channel").ChromPosDef}[]} */
+    const channelsAndChromPosDefs = [];
+
+    // Optimize the number of transforms. Use only a single transform for positions
+    // that share the chromosome field and channel.
+    for (const [c, channelDef] of Object.entries(view.getEncoding())) {
+        const channel = /** @type {Channel} */ (c);
+        if (isPositionalChannel(channel) && isChromPosDef(channelDef)) {
+            channelsAndChromPosDefs.push({ channel, chromPosDef: channelDef });
+        }
+    }
+
+    // Nngh. group uses InternMap but doesn't have a way to define an interning function.
+    // Have to use multi-level grouping.
+    const grouped = group(
+        channelsAndChromPosDefs,
+        (d) => /** @type {"x" | "y"} */ (getPrimaryChannel(d.channel)),
+        (d) => d.chromPosDef.chrom
+    );
+
+    for (const [primaryChan, chromAndStuff] of grouped.entries()) {
+        for (const [chrom, chanChromPos] of chromAndStuff.entries()) {
+            /** @type {string[]} */
+            const pos = [];
+            /** @type {string[]} */
+            const as = [];
+            /** @type {number[]} */
+            const offset = [];
+
+            for (const { channel, chromPosDef } of chanChromPos) {
+                /** @param {string} str */
+                const strip = (str) => str.replace(/[^A-Za-z0-9_]/g, "");
+                const linearizedField = [
+                    "_linearized_",
+                    strip(chromPosDef.chrom),
+                    "_",
+                    strip(chromPosDef.pos),
+                ].join("");
+
+                // Prefer using the spec directly because getEncoding() returns inherited props too.
+                // TODO: I think this is not robust enough. Needs more work...
+                /** @type {any} */
+                const newFieldDef = {
+                    ...(view.spec.encoding?.[channel] ??
+                        view.getEncoding()[channel] ??
+                        {}),
+                    field: linearizedField,
+                };
+                delete newFieldDef.chrom;
+                delete newFieldDef.pos;
+                if (!newFieldDef.type && chromPosDef.type) {
+                    newFieldDef.type = chromPosDef.type;
+                }
+
+                rewrittenEncoding[channel] = newFieldDef;
+
+                pos.push(chromPosDef.pos);
+                offset.push(chromPosDef.offset ?? 0);
+                as.push(linearizedField);
+            }
+
+            transforms.push(
+                new LinearizeGenomicCoordinate(
+                    {
+                        type: "linearizeGenomicCoordinate",
+                        channel: primaryChan,
+                        chrom: chrom,
+                        pos,
+                        offset,
+                        as,
+                    },
+                    view
+                )
+            );
+        }
+    }
+
+    return transforms.length
+        ? {
+              transforms,
+              rewrittenEncoding,
+              /**
+               * Should be called after the whole flow has been created in order to
+               * not disrupt inheritance of encodings
+               */
+              rewrite: () => {
+                  view.spec.encoding = {
+                      ...view.spec.encoding,
+                      ...rewrittenEncoding,
+                  };
+                  // This is so ugly...
+                  invalidate(view.mark, "encoding");
+              },
+          }
+        : undefined;
+}
+
+/**
+ * @param {View} view
+ * @param {Record<string, import("../spec/channel").ChannelDef>} [encoding]
+ * @returns {import("../spec/transform").CompareParams}
+ */
+function getCompareParamsForView(view, encoding) {
+    // TODO: Should sort by min(x, x2).
+    const e = { ...view.getEncoding(), ...encoding }.x;
+    if (isChannelDefWithScale(e)) {
+        if (view.getScaleResolution("x")?.isZoomable()) {
+            if (isFieldDef(e)) {
+                return { field: e.field };
+            } else if (isDatumDef(e)) {
+                // Nop
+            } else {
+                // TODO: Support expr by inserting a Formula transform
+                throw new Error(
+                    "A zoomable x channel must be mapped to a field."
+                );
+            }
+        }
+    }
+}
+
+/**
+ * A helper function for creating linear data flows programmatically.
+ *
+ * @param {H} dataSource A data source or any other initial FlowNode.
+ * @param  {...FlowNode} transforms
+ * @template {FlowNode} H
+ */
+export function createChain(dataSource, ...transforms) {
+    /** @type {FlowNode} */
+    let node = dataSource;
+    for (const transform of transforms) {
+        node.addChild(transform);
+        node = transform;
+    }
+
+    /** @type {Collector} */
+    let collector;
+
+    if (node instanceof Collector) {
+        collector = node;
+    } else {
+        collector = new Collector();
+        node.addChild(collector);
+    }
+
+    /** @type {function():Promise<Iterable<import("../data/flowNode").Datum>>} */
+    let loadAndCollect;
+    if (dataSource instanceof DataSource) {
+        loadAndCollect = async () => {
+            await dataSource.load();
+            return collector.getData();
+        };
+    } else {
+        loadAndCollect = async () => {
+            throw new Error("The root node is not derived from DataSource!");
+        };
+    }
+
+    return {
+        dataSource,
+        collector,
+        loadAndCollect,
+    };
+}

package/src/view/flowBuilder.test.js

@@ -0,0 +1,124 @@
+import Collector from "../data/collector";
+import FlowNode from "../data/flowNode";
+import FilterTransform from "../data/transforms/filter";
+import FormulaTransform from "../data/transforms/formula";
+import InlineSource from "../data/sources/inlineSource";
+import SequenceSource from "../data/sources/sequenceSource";
+import { buildDataFlow } from "./flowBuilder";
+import { create } from "./testUtils";
+import CloneTransform from "../data/transforms/clone";
+import LayerView from "./layerView";
+import UnitView from "./unitView";
+
+/**
+ *
+ * @param {FlowNode} root
+ * @param {number[]} path
+ */
+function byPath(root, path) {
+    for (const elem of path) {
+        root = root.children[elem];
+    }
+    return root;
+}
+
+/** @type {import("../spec/mark").MarkConfigAndType} */
+const mark = {
+    type: "rect",
+    tooltip: null,
+};
+
+test("Trivial flow", () => {
+    const root = create(
+        {
+            data: { values: [3.141] },
+            transform: [
+                {
+                    type: "formula",
+                    expr: "datum.data * 2",
+                    as: "x",
+                },
+            ],
+            mark,
+        },
+        UnitView
+    );
+
+    const flow = buildDataFlow(root);
+    const dataSource = flow.dataSources[0];
+
+    expect(dataSource).toBeInstanceOf(InlineSource);
+    expect(byPath(dataSource, [0])).toBeInstanceOf(CloneTransform);
+    expect(byPath(dataSource, [0, 0])).toBeInstanceOf(FormulaTransform);
+    expect(byPath(dataSource, [0, 0, 0])).toBeInstanceOf(Collector);
+
+    expect(flow.collectors[0]).toBe(byPath(dataSource, [0, 0, 0]));
+});
+
+test("Branching flow", () => {
+    const root = create(
+        {
+            data: { values: [3.141] },
+            layer: [
+                {
+                    transform: [
+                        {
+                            type: "formula",
+                            expr: "datum.data * 2",
+                            as: "x",
+                        },
+                    ],
+                    mark,
+                },
+                {
+                    transform: [
+                        {
+                            type: "filter",
+                            expr: "datum.data > 4",
+                        },
+                    ],
+                    mark,
+                },
+            ],
+        },
+        LayerView
+    );
+
+    const dataSource = buildDataFlow(root).dataSources[0];
+
+    expect(dataSource).toBeInstanceOf(InlineSource);
+    // Formula transform modifies data and it should be implicitly preceded by CloneTransform
+    expect(byPath(dataSource, [0])).toBeInstanceOf(CloneTransform);
+    expect(byPath(dataSource, [0, 0])).toBeInstanceOf(FormulaTransform);
+    expect(byPath(dataSource, [0, 0, 0])).toBeInstanceOf(Collector);
+    expect(byPath(dataSource, [1])).toBeInstanceOf(FilterTransform);
+    expect(byPath(dataSource, [1, 0])).toBeInstanceOf(Collector);
+});
+
+test("Nested data sources", () => {
+    const root = create(
+        {
+            data: { values: [1] },
+            transform: [{ type: "filter", expr: "datum.data > 0" }],
+            layer: [
+                {
+                    data: { sequence: { start: 0, stop: 5 } },
+                    transform: [{ type: "formula", expr: "3", as: "foo" }],
+                    mark,
+                },
+            ],
+        },
+        LayerView
+    );
+
+    const dataSources = buildDataFlow(root).dataSources;
+
+    expect(dataSources[0]).toBeInstanceOf(InlineSource);
+    expect(dataSources[0].children[0]).toBeInstanceOf(FilterTransform);
+    expect(dataSources[0].children[0].children.length).toEqual(0);
+
+    expect(byPath(dataSources[1], [])).toBeInstanceOf(SequenceSource);
+    expect(byPath(dataSources[1], [0])).toBeInstanceOf(CloneTransform);
+    expect(byPath(dataSources[1], [0, 0])).toBeInstanceOf(FormulaTransform);
+    expect(byPath(dataSources[1], [0, 0, 0])).toBeInstanceOf(Collector);
+});

package/src/view/importView.js

@@ -0,0 +1,19 @@
+import View from "./view";
+
+/**
+ * This is just a placeholder for custom tracks that are imported by name.
+ */
+export default class ImportView extends View {
+    /**
+     *
+     * @param {import("../spec/view").ImportSpec} spec
+     * @param {import("./viewUtils").ViewContext} context
+     * @param {import("./view").default} parent
+     * @param {string} name
+     */
+    constructor(spec, context, parent, name) {
+        super(spec, context, parent, name);
+
+        this.spec = spec; // Set here again to keep types happy
+    }
+}

package/src/view/layerView.js

@@ -0,0 +1,60 @@
+import { isLayerSpec, isUnitSpec } from "./viewFactory";
+import ContainerView from "./containerView";
+
+/**
+ * @typedef {import("./view").default} View
+ */
+export default class LayerView extends ContainerView {
+    /**
+     *
+     * @param {import("./viewUtils").LayerSpec} spec
+     * @param {import("./viewUtils").ViewContext} context
+     * @param {ContainerView} parent
+     * @param {string} name
+     */
+    constructor(spec, context, parent, name) {
+        super(spec, context, parent, name);
+
+        this.spec = spec;
+
+        /** @type {(LayerView | import("./unitView").default)[]} */
+        this.children = (spec.layer || []).map((childSpec, i) => {
+            if (isLayerSpec(childSpec) || isUnitSpec(childSpec)) {
+                return context.createView(childSpec, this, "layer" + i);
+            } else {
+                throw new Error(
+                    "LayerView accepts only unit or layer specs as children!"
+                );
+            }
+        });
+    }
+
+    /**
+     * @returns {IterableIterator<View>}
+     */
+    *[Symbol.iterator]() {
+        for (const child of this.children) {
+            yield child;
+        }
+    }
+
+    /**
+     * @param {import("./renderingContext/viewRenderingContext").default} context
+     * @param {import("../utils/layout/rectangle").default} coords
+     * @param {import("./view").RenderingOptions} [options]
+     */
+    render(context, coords, options = {}) {
+        if (!this.isVisible()) {
+            return;
+        }
+
+        coords = coords.shrink(this.getPadding());
+        context.pushView(this, coords);
+
+        for (const child of this.children) {
+            child.render(context, coords, options);
+        }
+
+        context.popView(this);
+    }
+}

package/src/view/rendering.d.ts

@@ -0,0 +1,44 @@
+import { LocSize } from "../utils/layout/flexLayout";
+import Rectangle from "../utils/layout/rectangle";
+
+/**
+ * Describes the location of a sample facet. Left is the primary pos, right is for
+ * transitioning between two sets of samples.
+ */
+export interface SampleFacetRenderingOptions {
+    /**
+     * Location and height on unit scale, zero at top
+     */
+    locSize: LocSize;
+
+    /**
+     * Target (during transition)
+     */
+    targetLocSize?: LocSize;
+}
+
+export interface RenderingOptions {
+    /**
+     * Which facet to render (if faceting is being used)
+     */
+    facetId?: any;
+
+    sampleFacetRenderingOptions?: SampleFacetRenderingOptions;
+
+    /**
+     * Clip rendering using the given rectangle.
+     * Mainly intended for clipping scrollable views.
+     */
+    clipRect?: Rectangle;
+}
+
+/**
+ * Options that affect the whole rendering pass.
+ */
+export interface GlobalRenderingOptions {
+    /**
+     * Replace colors with unique ids for picking.
+     * Views that haven't enabled picking can be skipped.
+     */
+    picking?: boolean;
+}

package/src/view/renderingContext/compositeViewRenderingContext.js

@@ -0,0 +1,51 @@
+import ViewRenderingContext from "./viewRenderingContext";
+
+/**
+ * @typedef {import("../view").default} View
+ */
+export default class CompositeViewRenderingContext extends ViewRenderingContext {
+    /**
+     *
+     * @param  {...ViewRenderingContext} contexts
+     */
+    constructor(...contexts) {
+        super({});
+
+        this.contexts = contexts;
+    }
+
+    /**
+     * Must be called when a view's render() method is entered
+     *
+     * @param {View} view
+     * @param {import("../../utils/layout/rectangle").default} coords View coordinates
+     *      inside the padding.
+     */
+    pushView(view, coords) {
+        for (const context of this.contexts) {
+            context.pushView(view, coords);
+        }
+    }
+
+    /**
+     * Must be called when a view's render() method is being exited
+     *
+     * @param {View} view
+     */
+    popView(view) {
+        for (const context of this.contexts) {
+            context.popView(view);
+        }
+    }
+
+    /**
+     *
+     * @param {import("../../marks/mark").default} mark
+     * @param {import("../view").RenderingOptions} options
+     */
+    renderMark(mark, options) {
+        for (const context of this.contexts) {
+            context.renderMark(mark, options);
+        }
+    }
+}