@genome-spy/core 0.14.0

package/src/encoder/encoder.js

@@ -0,0 +1,369 @@
+import { isDiscrete } from "vega-scale";
+import createIndexer from "../utils/indexer";
+
+/**
+ * @typedef {Object} EncoderMetadata
+ * @prop {boolean} constant True if the accessor returns the same value for all objects
+ * @prop {boolean} constantValue True the encoder returns a "value" without a scale
+ * @prop {function} invert
+ * @prop {VegaScale} [scale]
+ * @prop {import("./accessor").Accessor} accessor 
+ * @prop {function(any):number} [indexer] Converts ordinal values to index numbers
+ * @prop {import("../view/viewUtils").ChannelDef} channelDef
+ * @prop {function(function):void} applyMetadata Copies metadata to the target function
+ *
+ * @typedef {(function(object):(string|number)) & EncoderMetadata} Encoder
+ * @typedef {(function(object):number) & EncoderMetadata} NumberEncoder
+ *
+ * @typedef {object} ScaleMetadata
+ * @prop {string} type Scale type
+ * @prop {boolean} fp64 Whether to use emulated 64 bit floating point in WebGL
+ * 
+ * @typedef {(
+    import("d3-scale").ScaleContinuousNumeric<any, any> |
+    import("d3-scale").ScaleLinear<any, any> |
+    import("d3-scale").ScalePower<any, any> |
+    import("d3-scale").ScaleLogarithmic<any, any> |
+    import("d3-scale").ScaleSymLog<any, any> |
+    import("d3-scale").ScaleIdentity |
+    import("d3-scale").ScaleTime<any, any> |
+    import("d3-scale").ScaleSequential<any> |
+    import("d3-scale").ScaleDiverging<any> | 
+    import("d3-scale").ScaleQuantize<any> |
+    import("d3-scale").ScaleQuantile<any> |
+    import("d3-scale").ScaleThreshold<any, any> |
+    import("d3-scale").ScaleOrdinal<any, any> |
+    import("d3-scale").ScaleBand<any> |
+    import("d3-scale").ScalePoint<any>
+    )} D3Scale
+ * 
+ * @typedef {D3Scale & ScaleMetadata} VegaScale
+ * 
+ * @typedef {import("../spec/channel").Channel} Channel
+ */
+
+/**
+ * Creates an object that contains encoders for every channel of a mark
+ *
+ * TODO: This should actually receive the mark as parameter
+ *
+ * TODO: This method should have a test. But how to mock Mark...
+ *
+ * @param {import("../marks/mark").default} mark
+ * @param {import("../spec/channel").Encoding} [encoding] Taken from the mark if not provided
+ * @returns {Partial<Record<Channel, Encoder>>}
+ */
+export default function createEncoders(mark, encoding) {
+    /** @type {Partial<Record<Channel, Encoder>>} */
+    const encoders = {};
+
+    if (!encoding) {
+        encoding = mark.encoding;
+    }
+
+    for (const [channel, channelDef] of Object.entries(encoding)) {
+        if (!channelDef) {
+            continue;
+        }
+
+        const resolution = mark.unitView.getScaleResolution(
+            (isChannelDefWithScale(channelDef) &&
+                channelDef.resolutionChannel) ||
+                channel
+        );
+
+        encoders[channel] = createEncoder(
+            encoding[channel],
+            resolution?.getScale(),
+            mark.unitView.getAccessor(channel),
+            channel
+        );
+    }
+
+    return encoders;
+}
+
+/**
+ *
+ * @param {import("../view/viewUtils").ChannelDef} channelDef
+ * @param {any} scale
+ * @param {import("./accessor").Accessor} accessor
+ * @param {Channel} channel
+ * @returns {Encoder}
+ */
+export function createEncoder(channelDef, scale, accessor, channel) {
+    /** @type {Encoder} */
+    let encoder;
+
+    if (isValueDef(channelDef)) {
+        encoder = /** @type {Encoder} */ ((datum) => channelDef.value);
+        encoder.constant = true;
+        encoder.constantValue = true;
+        encoder.accessor = undefined;
+    } else if (accessor) {
+        if (channel == "text") {
+            // TODO: Define somewhere channels that don't use a scale
+            encoder = /** @type {Encoder} */ ((datum) => undefined);
+            encoder.accessor = accessor;
+            encoder.constant = accessor.constant;
+        } else {
+            if (!scale) {
+                throw new Error(
+                    `Missing scale! "${channel}": ${JSON.stringify(channelDef)}`
+                );
+            }
+
+            encoder = /** @type {Encoder} */ (
+                (datum) => scale(accessor(datum))
+            );
+
+            if (isDiscrete(scale.type)) {
+                // TODO: pass the found values back to the scale/resolution
+                const indexer = createIndexer();
+                indexer.addAll(scale.domain());
+                encoder.indexer = (d) => indexer(accessor(d));
+            }
+
+            encoder.constant = accessor.constant;
+            encoder.accessor = accessor;
+            encoder.scale = scale;
+        }
+    } else {
+        throw new Error(
+            `Missing value or accessor (field, expr, datum) on channel "${channel}": ${JSON.stringify(
+                channelDef
+            )}`
+        );
+    }
+
+    // TODO: Modifier should be inverted too
+    encoder.invert = scale
+        ? (value) => scale.invert(value)
+        : (value) => {
+              throw new Error(
+                  "No scale available, cannot invert: " +
+                      JSON.stringify(channelDef)
+              );
+          };
+
+    // Just to provide a convenient access to the config
+    encoder.channelDef = channelDef;
+
+    /** @param {Encoder} target */
+    encoder.applyMetadata = (target) => {
+        for (const prop in encoder) {
+            if (prop in encoder) {
+                target[prop] = encoder[prop];
+            }
+        }
+        return target;
+    };
+
+    return encoder;
+}
+
+/**
+ * TODO: Move to a more generic place
+ *
+ * @param {import("../spec/channel").ChannelDef} channelDef
+ * @returns {channelDef is import("../spec/channel").ValueDef}
+ */
+export function isValueDef(channelDef) {
+    return channelDef && "value" in channelDef;
+}
+
+/**
+ * @param {import("../spec/channel").ChannelDef} channelDef
+ * @returns {channelDef is import("../spec/channel").FieldDef}
+ */
+export function isFieldDef(channelDef) {
+    return channelDef && "field" in channelDef;
+}
+
+/**
+ * @param {import("../spec/channel").ChannelDef} channelDef
+ * @returns {channelDef is import("../spec/channel").DatumDef}
+ */
+export function isDatumDef(channelDef) {
+    return channelDef && "datum" in channelDef;
+}
+
+/**
+ * @param {import("../spec/channel").ChannelDef} channelDef
+ * @returns {channelDef is import("../spec/channel").ChannelDefWithScale}
+ */
+export function isChannelDefWithScale(channelDef) {
+    return (
+        isFieldDef(channelDef) ||
+        isDatumDef(channelDef) ||
+        isExprDef(channelDef) ||
+        isChromPosDef(channelDef)
+    );
+}
+
+/**
+ * @param {import("../view/unitView").default} view
+ * @param {Channel} channel
+ */
+export function getChannelDefWithScale(view, channel) {
+    const channelDef = view.mark.encoding[channel];
+    if (isChannelDefWithScale(channelDef)) {
+        return channelDef;
+    } else {
+        throw new Error("Not a channel def with scale!");
+    }
+}
+
+/**
+ * @param {import("../spec/channel").ChannelDef} channelDef
+ * @returns {channelDef is import("../spec/channel").ChromPosDef}
+ */
+export function isChromPosDef(channelDef) {
+    return channelDef && "chrom" in channelDef;
+}
+
+/**
+ * @param {import("../spec/channel").ChannelDef} channelDef
+ * @returns {channelDef is import("../spec/channel").ExprDef}
+ */
+export function isExprDef(channelDef) {
+    return channelDef && "expr" in channelDef;
+}
+
+/**
+ * @type {Channel[]}
+ */
+export const primaryPositionalChannels = ["x", "y"];
+
+/**
+ * Map primary channels to secondarys
+ *
+ * @type {Partial<Record<Channel, Channel>>}
+ */
+export const secondaryChannels = {
+    x: "x2",
+    y: "y2",
+    size: "size2",
+    color: "color2",
+};
+
+/**
+ * Map secondary channels to primaries
+ *
+ * @type {Record<Channel, Channel>}
+ */
+export const primaryChannels = Object.fromEntries(
+    Object.entries(secondaryChannels).map((entry) => [entry[1], entry[0]])
+);
+
+/**
+ *
+ * @param {string} channel
+ */
+export function isSecondaryChannel(channel) {
+    return channel in primaryChannels;
+}
+
+/**
+ * Return the matching secondary channel or throws if one does not exist.
+ *
+ * @param {Channel} primaryChannel
+ */
+export function getSecondaryChannel(primaryChannel) {
+    const secondary = secondaryChannels[primaryChannel];
+    if (secondary) {
+        return secondary;
+    } else {
+        throw new Error(`${primaryChannel} has no secondary channel!`);
+    }
+}
+
+/**
+ * Finds the primary channel for the provided channel, which may be
+ * the primary or secondary.
+ *
+ * @param {Channel} maybeSecondary
+ */
+export function getPrimaryChannel(maybeSecondary) {
+    return primaryChannels[maybeSecondary] || maybeSecondary;
+}
+
+/**
+ * Returns an array that contains the given channel and its secondary channel if one exists.
+ *
+ * @param {Channel} channel
+ */
+export function getChannelWithSecondarys(channel) {
+    return secondaryChannels[channel]
+        ? [channel, secondaryChannels[channel]]
+        : [channel];
+}
+
+/**
+ * @param {Channel} channel
+ */
+export function isPositionalChannel(channel) {
+    return primaryPositionalChannels.includes(getPrimaryChannel(channel));
+}
+
+/**
+ * @param {Channel} channel
+ */
+export function isColorChannel(channel) {
+    return ["color", "fill", "stroke"].includes(getPrimaryChannel(channel));
+}
+
+/**
+ * Returns true if the channel has a discrete range.
+ *
+ * @param {Channel} channel
+ */
+export function isDiscreteChannel(channel) {
+    return ["shape", "squeeze"].includes(channel);
+}
+
+/**
+ * Returns valid discrete values for a discrete channel.
+ *
+ * @param {Channel} channel
+ * @returns {any[]}
+ */
+export function getDiscreteRange(channel) {
+    // TODO: This is not easily extendable. Figure out a more dynamic approach.
+    switch (channel) {
+        case "shape":
+            return [
+                "circle",
+                "square",
+                "triangle-up",
+                "cross",
+                "diamond",
+                "triangle-down",
+                "triangle-right",
+                "triangle-left",
+            ];
+        default:
+    }
+}
+
+/**
+ * @param {Channel} channel
+ * @returns {function(any):number}
+ */
+export function getDiscreteRangeMapper(channel) {
+    if (!isDiscreteChannel(channel)) {
+        throw new Error("Not a discrete channel: " + channel);
+    }
+
+    const valueMap = new Map(
+        getDiscreteRange(channel).map((value, i) => [value, i])
+    );
+
+    return (value) => {
+        const mapped = valueMap.get(value);
+        if (mapped !== undefined) {
+            return mapped;
+        }
+        throw new Error(`Invalid value for "${channel}" channel: ${value}`);
+    };
+}

package/src/encoder/encoder.test.js

@@ -0,0 +1,97 @@
+import AccessorFactory from "./accessor";
+import { scale as vegaScale } from "vega-scale";
+
+import { createEncoder } from "./encoder";
+
+describe("Encoder", () => {
+    /** @type {Record<string, import("../view/viewUtils").ChannelDef>} */
+    const encodingSpecs = {
+        x: { value: 0 },
+        y: { field: "a" },
+        z: { datum: 2 },
+        size: { value: 5 },
+    };
+
+    const scaleLinear = vegaScale("linear");
+
+    /** @type {Record<string, import("./encoder").VegaScale>} */
+    const scales = {
+        y: scaleLinear().domain([0, 10]),
+        z: scaleLinear().domain([0, 20]),
+    };
+
+    const accessorFactory = new AccessorFactory();
+
+    /** @param {Record<string, import("../view/viewUtils").ChannelDef>} encoding */
+    function createEncoders(encoding) {
+        /** @type {Record<string, import("./encoder").Encoder>} */
+        const encoders = {};
+        for (const [channel, channelDef] of Object.entries(encoding)) {
+            encoders[channel] = createEncoder(
+                channelDef,
+                scales[channel],
+                accessorFactory.createAccessor(encodingSpecs[channel]),
+                channel
+            );
+        }
+        return encoders;
+    }
+
+    const datum = {
+        a: 5,
+        b: 6,
+        c: "Pink Floyd",
+    };
+
+    test("Throws on a broken spec", () =>
+        expect(() => createEncoders({ x: {} })).toThrow());
+
+    const encoders = createEncoders(encodingSpecs);
+
+    test("The encoder object contains all channels", () =>
+        expect(
+            ["x", "y", "z", "size"].every(
+                (channel) => typeof encoders[channel] === "function"
+            )
+        ).toBeTruthy());
+
+    test("Returns a value", () => expect(encoders.x(datum)).toEqual(0));
+
+    test("Encodes and returns a constant using a scale", () =>
+        expect(encoders.z(datum)).toBeCloseTo(0.1));
+
+    test("Accesses a field and uses a scale", () =>
+        expect(encoders.y(datum)).toBeCloseTo(0.5));
+
+    /*
+    test("Accesses a field on a secondary channel and uses the scale from the primary", () =>
+        expect(encoders.y2(datum)).toBeCloseTo(0.6));
+        */
+
+    test("Constant encoder is annotated", () => {
+        expect(encoders.y.constant).toBeFalsy();
+        expect(encoders.z.constant).toBeTruthy();
+        expect(encoders.size.constant).toBeTruthy();
+    });
+
+    test("Constant value encoder is annotated", () => {
+        expect(encoders.y.constantValue).toBeFalsy();
+        expect(encoders.z.constantValue).toBeFalsy();
+        expect(encoders.size.constantValue).toBeTruthy();
+    });
+
+    test("Inverts a value", () => {
+        expect(encoders.y.invert(0.5)).toBeCloseTo(5);
+        expect(encoders.z.invert(0.5)).toBeCloseTo(10);
+        // A value, no scale, can't invert
+        expect(() => encoders.size.invert(123)).toThrow();
+    });
+
+    test("Accessors are provided", () => {
+        expect(encoders.y.accessor).toBeDefined();
+        expect(encoders.z.accessor).toBeDefined();
+        expect(encoders.x.accessor).toBeUndefined();
+    });
+
+    // TODO: Test indexer
+});