@genome-spy/core 0.36.0 → 0.37.0

package/dist/src/view/flowBuilder.js

@@ -0,0 +1,383 @@
+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 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 { group } from "d3-array";
+import IdentifierTransform from "../data/transforms/identifier";
+import { invalidate } from "../utils/propertyCacher";
+import NamedSource, { isNamedData } from "../data/sources/namedSource";
+import { nodesToTreesWithAccessor, visitTree } from "../utils/trees";
+
+/**
+ * @param {View} root
+ * @param {DataFlow<View>} [existingFlow] Add data flow
+ *      graphs to an existing DataFlow object.
+ */
+export function buildDataFlow(root, existingFlow) {
+    /**
+     * @typedef {import("./view").default} View
+     * @typedef {import("../data/flowNode").default} FlowNode
+     */
+
+    /** @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 = isNamedData(view.spec.data)
+                ? new NamedSource(
+                      view.spec.data,
+                      view,
+                      view.context.getNamedDataFromProvider
+                  )
+                : createDataSource(view.spec.data, view);
+
+            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 (${view.getPathString()}) 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()) {
+                appendTransform(new 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);
+        }
+    };
+
+    // Views only keep track of their children based on the layout hierachy.
+    // Thus, let's get traversable hierarchies using dataParents.
+    const dataTrees = nodesToTreesWithAccessor(
+        root.getDescendants(),
+        (view) => view.dataParent
+    );
+
+    for (const dataTree of dataTrees) {
+        visitTree(dataTree, {
+            preOrder: (node) => processView(node.ref),
+            // eslint-disable-next-line no-loop-func
+            postOrder: () => {
+                currentNode = nodeStack.pop();
+            },
+        });
+    }
+
+    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) {
+    /**
+     * @typedef {import("./view").default} View
+     * @typedef {import("../data/flowNode").default} FlowNode
+     * @typedef {import("../spec/channel").Channel} Channel
+     * @typedef {import("../spec/channel").Encoding} Encoding
+     */
+
+    /** @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 CloneTransform());
+            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...
+                  // @ts-ignore
+                  invalidate(view.mark, "encoding");
+              },
+          }
+        : undefined;
+}
+
+/**
+ * @param {import("./view").default} view
+ * @param {import("../spec/channel").Encoding} [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) {
+    /**
+     * @typedef {import("../data/flowNode").default} FlowNode
+     */
+    /** @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/dist/src/view/flowBuilder.test.js

@@ -0,0 +1,125 @@
+import { expect, test } from "vitest";
+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/dist/src/view/gridView.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @param {import("../spec/view").ViewBackground} viewBackground
+ * @returns {import("../spec/view").UnitSpec}
+ */
+export function createBackground(viewBackground: import("../spec/view").ViewBackground): import("../spec/view").UnitSpec;
+/**
+ * @param {import("../spec/view").ViewBackground} viewBackground
+ * @returns {import("../spec/view").UnitSpec}
+ */
+export function createBackgroundStroke(viewBackground: import("../spec/view").ViewBackground): import("../spec/view").UnitSpec;
+/**
+ * @param {View} view
+ */
+export function isClippedChildren(view: import("./view").default): boolean;
+/**
+ *
+ * @param {import("../utils/layout/rectangle").default} coords
+ * @param {import("../spec/axis").AxisOrient} orient
+ * @param {AxisView} axisView
+ */
+export function translateAxisCoords(coords: import("../utils/layout/rectangle").default, orient: import("../spec/axis").AxisOrient, axisView: AxisView): Rectangle;
+/**
+ * Modeled after: https://vega.github.io/vega/docs/layout/
+ *
+ * This should take care of the following:
+ * - Composition: [hv]concat / facet / repeat
+ * - Views
+ * - Axes
+ * - Grid lines
+ * - View background
+ * - View titles
+ * - Facet (column / row) titles
+ * - Header / footer
+ * - Zoom / pan
+ * - And later on, brushing, legend(?)
+ */
+export default class GridView extends ContainerView {
+    /**
+     *
+     * @param {import("../spec/view").AnyConcatSpec} spec
+     * @param {import("../types/viewContext").default} context
+     * @param {ContainerView} layoutParent
+     * @param {View} dataParent
+     * @param {string} name
+     * @param {number} columns
+     */
+    constructor(spec: import("../spec/view").AnyConcatSpec, context: import("../types/viewContext").default, layoutParent: ContainerView, dataParent: import("./view").default, name: string, columns: number);
+    spec: import("../spec/view").AnyConcatSpec;
+    wrappingFacet: boolean;
+    /**
+     * @protected
+     */
+    protected _createChildren(): void;
+    /**
+     * @param {View} view
+     */
+    appendChild(view: import("./view").default): void;
+    /**
+     * @param {View[]} views
+     */
+    setChildren(views: import("./view").default[]): void;
+    /**
+     * Read-only view to children
+     */
+    get children(): import("./view").default[];
+    get childCount(): number;
+    /**
+     * @param {import("./renderingContext/viewRenderingContext").default} context
+     * @param {import("../utils/layout/rectangle").default} coords
+     * @param {import("../types/rendering").RenderingOptions} [options]
+     */
+    render(context: import("./renderingContext/viewRenderingContext").default, coords: import("../utils/layout/rectangle").default, options?: import("../types/rendering").RenderingOptions): void;
+    #private;
+}
+export class GridChild {
+    /**
+     * @param {View} view
+     * @param {ContainerView} layoutParent
+     * @param {number} serial
+     */
+    constructor(view: import("./view").default, layoutParent: ContainerView, serial: number);
+    layoutParent: ContainerView;
+    view: import("./view").default;
+    serial: number;
+    /** @type {UnitView} */
+    background: UnitView;
+    /** @type {UnitView} */
+    backgroundStroke: UnitView;
+    /** @type {Partial<Record<import("../spec/axis").AxisOrient, AxisView>>} axes */
+    axes: Partial<Record<import("../spec/axis").AxisOrient, AxisView>>;
+    /** @type {Partial<Record<import("../spec/axis").AxisOrient, AxisGridView>>} gridLines */
+    gridLines: Partial<Record<import("../spec/axis").AxisOrient, AxisGridView>>;
+    /** @type {UnitView} */
+    title: UnitView;
+    /** @type {Rectangle} */
+    coords: Rectangle;
+    getChildren(): Generator<import("./view").default, void, undefined>;
+    /**
+     * Create view decorations, grid lines, axes, etc.
+     */
+    createAxes(): void;
+    getOverhang(): Padding;
+    getOverhangAndPadding(): Padding;
+}
+import AxisView from "./axisView";
+import Rectangle from "../utils/layout/rectangle";
+import ContainerView from "./containerView";
+import UnitView from "./unitView";
+import AxisGridView from "./axisGridView";
+import Padding from "../utils/layout/padding";
+//# sourceMappingURL=gridView.d.ts.map

package/dist/src/view/gridView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gridView.d.ts","sourceRoot":"","sources":["../../../src/view/gridView.js"],"names":[],"mappings":"AAwpBA;;;GAGG;AACH,iDAHW,OAAO,cAAc,EAAE,cAAc,GACnC,OAAO,cAAc,EAAE,QAAQ,CAwB3C;AAED;;;GAGG;AACH,uDAHW,OAAO,cAAc,EAAE,cAAc,GACnC,OAAO,cAAc,EAAE,QAAQ,CA6C3C;AA2BD;;GAEG;AACH,2EAUC;AAED;;;;;GAKG;AACH,4CAJW,OAAO,2BAA2B,EAAE,OAAO,UAC3C,OAAO,cAAc,EAAE,UAAU,YACjC,QAAQ,aAmBlB;AAhxBD;;;;;;;;;;;;;;GAcG;AACH;IA4BI;;;;;;;;OAQG;IACH,kBAPW,OAAO,cAAc,EAAE,aAAa,WACpC,OAAO,sBAAsB,EAAE,OAAO,gBACtC,aAAa,8CAEb,MAAM,WACN,MAAM,EAchB;IAVG,2CAAgB;IAOhB,uBAA0B;IAK9B;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,kDAIC;IAeD;;OAEG;IACH,qDAKC;IAqBD;;OAEG;IACH,2CAEC;IAED,yBAEC;IAyRD;;;;OAIG;IAEH,gBALW,OAAO,yCAAyC,EAAE,OAAO,UACzD,OAAO,2BAA2B,EAAE,OAAO,YAC3C,OAAO,oBAAoB,EAAE,gBAAgB,QAwIvD;;CAyFJ;AAgJD;IACI;;;;OAIG;IACH,0DAHW,aAAa,UACb,MAAM,EAqEhB;IAlEG,4BAAgC;IAChC,+BAAgB;IAChB,eAAoB;IAEpB,uBAAuB;IACvB,YADW,QAAQ,CACQ;IAE3B,uBAAuB;IACvB,kBADW,QAAQ,CACc;IAEjC,gFAAgF;IAChF,MADW,QAAQ,OAAO,OAAO,cAAc,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CACzD;IAEd,yFAAyF;IACzF,WADW,QAAQ,OAAO,OAAO,cAAc,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CACxD;IAEnB,uBAAuB;IACvB,OADW,QAAQ,CACG;IAEtB,wBAAwB;IACxB,QADW,SAAS,CACQ;IAgDhC,oEAaC;IAED;;OAEG;IACH,mBA8JC;IAED,uBAqBC;IAED,iCAEC;CACJ;qBAhjC0D,YAAY;sBAFjD,2BAA2B;0BAGvB,iBAAiB;qBAGtB,YAAY;yBALR,gBAAgB;oBAFrB,yBAAyB"}