@genome-spy/core 0.14.2 → 0.18.0

package/src/scale/glslScaleGenerator.js

@@ -4,7 +4,6 @@ import {
     isDiscretizing,
     isInterpolating,
 } from "vega-scale";
-import { fp64ify } from "../gl/includes/fp64-utils";
 import { isArray, isBoolean, isNumber, isString } from "vega-util";
 import { color as d3color } from "d3-color";
 
@@ -14,6 +13,7 @@ import {
     isDatumDef,
     isDiscreteChannel,
     getPrimaryChannel,
+    isValueDef,
 } from "../encoder/encoder";
 import { peek } from "../utils/arrayUtils";
 
@@ -93,11 +93,17 @@ ${vec.type} ${SCALED_FUNCTION_PREFIX}${channel}() {
 /**
  *
  * @param {Channel} channel
- * @param {any} scale
- * @param {import("../spec/channel").ChannelDef} encoding
+ * @param {any} scale TODO: typing
+ * @param {import("../spec/channel").ChannelDef} channelDef
  */
 // eslint-disable-next-line complexity
-export function generateScaleGlsl(channel, scale, encoding) {
+export function generateScaleGlsl(channel, scale, channelDef) {
+    if (isValueDef(channelDef)) {
+        throw new Error(
+            `Cannot create scale for "value": ${JSON.stringify(channelDef)}`
+        );
+    }
+
     const primary = getPrimaryChannel(channel);
     const attributeName = ATTRIBUTE_PREFIX + channel;
     const domainUniformName = DOMAIN_PREFIX + primary;
@@ -184,7 +190,8 @@ export function generateScaleGlsl(channel, scale, encoding) {
                 scale.paddingInner(),
                 scale.paddingOuter(),
                 scale.align(),
-                encoding.band ?? 0.5
+                // @ts-expect-error TODO: fix typing
+                channelDef.band ?? 0.5
             );
             break;
 
@@ -204,7 +211,7 @@ export function generateScaleGlsl(channel, scale, encoding) {
             throw new Error(
                 `Unsupported scale type: ${
                     scale.type
-                }! ${channel}: ${JSON.stringify(encoding)}`
+                }! ${channel}: ${JSON.stringify(channelDef)}`
             );
     }
 
@@ -228,20 +235,6 @@ export function generateScaleGlsl(channel, scale, encoding) {
         );
     }
 
-    /** @type {number} */
-    let datum;
-    if (isDatumDef(encoding)) {
-        if (isNumber(encoding.datum)) {
-            datum = encoding.datum;
-        } else {
-            throw new Error(
-                `Only quantitative datums are currently supported in the encoding definition: ${JSON.stringify(
-                    encoding
-                )}`
-            );
-        }
-    }
-
     const returnType = isColorChannel(channel) ? "vec3" : "float";
 
     /**
@@ -269,14 +262,8 @@ export function generateScaleGlsl(channel, scale, encoding) {
         interpolate = `getDiscreteColor(${textureUniformName}, int(transformed)).r`;
     }
 
-    // Declare the data: a variable or a constant datum (in domain).
-    if (datum !== undefined) {
-        // TODO: Datums could also be provided as uniforms, allowing for modifications
-        glsl.push(
-            `const highp ${attributeType} ${attributeName} = ${vectorize(
-                fp64 ? fp64ify(datum) : datum
-            )};`
-        );
+    if (isDatumDef(channelDef)) {
+        glsl.push(`uniform highp ${attributeType} ${attributeName};`);
     } else {
         glsl.push(`in highp ${attributeType} ${attributeName};`);
     }
@@ -329,7 +316,7 @@ export function generateScaleGlsl(channel, scale, encoding) {
     }
 
     // 3. clamp
-    if (scale.clamp && scale.clamp()) {
+    if ("clamp" in scale && scale.clamp()) {
         scaleBody.push(
             `transformed = clampToRange(transformed, ${vectorizeRange(range)});`
         );

package/src/scale/scale.js

@@ -9,6 +9,10 @@
  */
 
 /* eslint-disable */
+// @ts-nocheck
+
+// This file is a mess
+// TODO: Fix types, etc.
 
 import { tickCount } from "./ticks";
 import {
@@ -131,6 +135,12 @@ export function configureScale(_, scale, logger) {
     );
 }
 
+/**
+ *
+ * @param {import("../spec/scale").Scale} _
+ * @param {*} logger
+ * @returns {import("../encoder/encoder").VegaScale}
+ */
 export default function createScale(_, logger) {
     const key = scaleKey(_);
     const scale = getScale(key);

package/src/scale/ticks.js

@@ -9,6 +9,10 @@
  */
 
 /* eslint-disable */
+// @ts-nocheck
+
+// This file is a mess
+// TODO: Fix types, etc.
 
 import { isLogarithmic } from "vega-scale";
 import { error, isNumber, isObject, isString, peek, span } from "vega-util";
@@ -16,8 +20,9 @@ import { format as numberFormat, formatSpecifier } from "d3-format";
 
 /**
  * Determine the tick count or interval function.
- * @param {Scale} scale - The scale for which to generate tick values.
- * @param {*} count - The desired tick count or interval specifier.
+ *
+ * @param {import("../encoder/encoder").VegaScale} scale - The scale for which to generate tick values.
+ * @param {number | {step: number, interval: number}} count - The desired tick count or interval specifier.
  * @param {number} minStep - The desired minimum step between tick values.
  * @return {*} - The tick count or interval function.
  */
@@ -39,7 +44,7 @@ export function tickCount(scale, count, minStep) {
 /**
  * Filter a set of candidate tick values, ensuring that only tick values
  * that lie within the scale range are included.
- * @param {Scale} scale - The scale for which to generate tick values.
+ * @param {import("../encoder/encoder").VegaScale} scale - The scale for which to generate tick values.
  * @param {Array<*>} ticks - The candidate tick values.
  * @param {*} count - The tick count or interval function.
  * @return {Array<*>} - The filtered tick values.
@@ -80,9 +85,9 @@ export function validTicks(scale, ticks, count) {
  * interval value. If the scale has a 'ticks' method, it will be used to
  * generate the ticks, with the count argument passed as a parameter. If the
  * scale lacks a 'ticks' method, the full scale domain will be returned.
- * @param {Scale} scale - The scale for which to generate tick values.
+ * @param {import("../encoder/encoder").VegaScale} scale - The scale for which to generate tick values.
  * @param {*} [count] - The approximate number of desired ticks.
- * @return {Array<*>} - The generated tick values.
+ * @return {any[]} - The generated tick values.
  */
 export function tickValues(scale, count) {
     return scale.bins
@@ -117,7 +122,7 @@ function binValues(bins, count) {
  * If the input scale is a logarithmic scale and the format specifier does not
  * indicate a desired decimal precision, a special variable precision formatter
  * that automatically trims trailing zeroes will be generated.
- * @param {Scale} scale - The scale for which to generate the label formatter.
+ * @param {import("../encoder/encoder").VegaScale} scale - The scale for which to generate the label formatter.
  * @param {*} [count] - The approximate number of desired ticks.
  * @param {string} [specifier] - The format specifier. Must be a legal d3
  *   specifier string (see https://github.com/d3/d3-format#formatSpecifier).

package/src/spec/channel.d.ts

@@ -1,16 +1,31 @@
+/*!
+ * Partially based on
+ * https://github.com/vega/vega-lite/blob/master/src/channeldef.ts
+ *
+ * Copyright (c) 2015-2018, University of Washington Interactive Data Lab
+ * All rights reserved.
+ *
+ * BSD-3-Clause License: https://github.com/vega/vega-lite/blob/master/LICENSE
+ */
+
 import { Scale } from "./scale";
 import { Axis } from "./axis";
 
 export type Scalar = string | number | boolean;
-export type FieldName = string;
+export type Value = Scalar | null;
 
-export type PositionalChannel = "x" | "y";
+export type FieldName = string;
+export type Field = FieldName;
 
+export type PrimaryPositionalChannel = "x" | "y";
 export type SecondaryPositionalChannel = "x2" | "y2";
 
+export type PositionalChannel =
+    | PrimaryPositionalChannel
+    | SecondaryPositionalChannel;
+
 export type Channel =
     | PositionalChannel
-    | SecondaryPositionalChannel
     | "color"
     | "fill"
     | "stroke"
@@ -21,8 +36,6 @@ export type Channel =
     | "size"
     | "shape"
     | "text"
-    | "size2"
-    | "color2"
     | "angle"
     | "sample"
     | "uniqueId"
@@ -30,63 +43,198 @@ export type Channel =
     | "facetIndex"
     | "semanticScore"
     | "dx"
-    | "dy";
+    | "dy"
+    | "uniqueId";
+
+// TODO
+export type FacetFieldDef = any;
 
-export interface ChannelDefBase {
+// TODO: Belongs to "guide"
+export interface TitleMixins {
+    /**
+     * A title for the field. If `null`, the title will be removed.
+     */
     title?: string | null;
 }
 
-export interface ValueDef extends ChannelDefBase {
-    /** A constant value in the context of the range */
-    value: Scalar;
+export interface BandMixins {
+    /**
+     * Relative position on band scale. For example, the marks will be positioned at the beginning of the band if set to `0`, and at the middle of the band if set to `0.5`.
+     *
+     * @minimum 0
+     * @maximum 1
+     */
+    // TODO: rename to bandPosition: https://github.com/vega/vega-lite/pull/7190
+    // bandPosition?: number;
+    band?: number;
+}
+
+export interface FormatMixins {
+    /**
+     * When used with the default `"number"` format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.
+     *
+     * - If the format type is `"number"` (e.g., for quantitative fields), this is D3's [number format pattern](https://github.com/d3/d3-format#locale_format).
+     *
+     * See the [format documentation](https://vega.github.io/vega-lite/docs/format.html) for more examples.
+     */
+    format?: string;
 }
 
-export interface ChannelDefWithScale extends ChannelDefBase {
-    type: string;
+export type StringDatumDef = DatumDef & FormatMixins;
 
+export type Type = "quantitative" | "ordinal" | "nominal" | "index" | "locus";
+
+export type TypeForShape = "ordinal" | "nominal";
+
+export interface TypeMixins<T extends Type> {
+    type: T;
+}
+
+export interface FieldDefBase<F> {
     /**
-     * Offset within a band of a band scale, [0, 1]
+     * __Required.__ A string defining the name of the field from which to pull a data value
+     * or an object defining iterated values from the [`repeat`](https://vega.github.io/vega-lite/docs/repeat.html) operator.
+     *
+     * __See also:__ [`field`](https://vega.github.io/vega-lite/docs/field.html) documentation.
      *
-     * TODO: rename to bandPosition: https://github.com/vega/vega-lite/pull/7190
+     * __Notes:__
+     * 1)  Dots (`.`) and brackets (`[` and `]`) can be used to access nested objects (e.g., `"field": "foo.bar"` and `"field": "foo['bar']"`).
+     * If field names contain dots or brackets but are not nested, you can use `\\` to escape dots and brackets (e.g., `"a\\.b"` and `"a\\[0\\]"`).
+     * See more details about escaping in the [field documentation](https://vega.github.io/vega-lite/docs/field.html).
+     * 2) `field` is not required if `aggregate` is `count`.
      */
-    band?: number;
+    field?: F;
+}
 
-    scale?: Scale;
-    axis?: Axis | null;
+export type TypedFieldDef<
+    F extends Field,
+    T extends Type = any
+> = FieldDefBase<F> & TitleMixins & TypeMixins<T>;
 
-    format?: string;
+export type ScaleFieldDef<F extends Field, T extends Type> = TypedFieldDef<
+    F,
+    T
+> &
+    ScaleMixins;
 
+export type FieldDefWithoutScale<F extends Field> = FieldDefBase<F> &
+    TitleMixins;
+
+export interface ScaleMixins {
     /**
-     * Use emulated 64 bit floating points to increase precision of scales
-     * computed on the GPU. By default, 32 bit floats are used.
+     * An object defining properties of the channel's scale, which is the function that transforms values in the data domain (numbers, dates, strings, etc) to visual values (pixels, colors, sizes) of the encoding channels.
+     *
+     * If `null`, the scale will be [disabled and the data value will be directly encoded](https://vega.github.io/vega-lite/docs/scale.html#disable).
+     *
+     * __Default value:__ If undefined, default [scale properties](https://vega.github.io/vega-lite/docs/scale.html) are applied.
+     *
+     * __See also:__ [`scale`](https://vega.github.io/vega-lite/docs/scale.html) documentation.
      */
-    fp64?: boolean;
+    scale?: Scale | null;
 
     /**
-     * Use an alternative channel for scale resolution.
+     * An alternative channel for scale resolution.
      *
-     * This is mainly for internal use and allows using `color` channel to resolve
-     * `fill` and `stroke` channels under certain circumstances.
+     * This is mainly for internal use and allows using `color` channel to resolve `fill` and `stroke` channels under certain circumstances.
      */
     resolutionChannel?: Channel;
 }
 
-export interface FieldDef extends ChannelDefWithScale {
-    field: FieldName;
+export interface ValueDef<V extends Value = Scalar> {
+    /**
+     * A constant value in visual domain (e.g., `"red"` / `"#0099ff"`, values between `0` to `1` for opacity).
+     */
+    value: V;
 }
 
-export interface DatumDef extends ChannelDefWithScale {
-    /** A constant value on the data domain */
-    datum: Scalar;
+export interface DatumDef extends TitleMixins {
+    /**
+     * A constant value in data domain.
+     */
+    datum?: Scalar;
 }
 
-export interface ExprDef extends ChannelDefWithScale {
+export interface ExprDef {
     /** An expression. Properties of the data can be accessed through the `datum` object. */
     expr: string;
 }
-export interface ChromPosDef extends ChannelDefWithScale {
-    type: "locus";
 
+/**
+ * Field definition of a mark property, which can contain a legend.
+ */
+export type MarkPropFieldDef<
+    F extends Field,
+    T extends Type = Type
+> = ScaleFieldDef<F, T> & LegendMixins;
+
+export type MarkPropExprDef<T extends Type = Type> = ExprDef &
+    TypeMixins<T> &
+    ScaleMixins;
+
+export type MarkPropDatumDef<T extends Type> = LegendMixins &
+    ScaleDatumDef &
+    TypeMixins<T>;
+
+export type MarkPropFieldOrDatumOrExprDef<
+    F extends Field,
+    T extends Type = Type
+> = MarkPropFieldDef<F, T> | MarkPropDatumDef<T> | MarkPropExprDef;
+
+export interface LegendMixins {
+    /**
+     * An object defining properties of the legend.
+     * If `null`, the legend for the encoding channel will be removed.
+     *
+     * __Default value:__ If undefined, default [legend properties](https://vega.github.io/vega-lite/docs/legend.html) are applied.
+     *
+     * __See also:__ [`legend`](https://vega.github.io/vega-lite/docs/legend.html) documentation.
+     */
+    // TODO: legend?: Legend<ExprRef | SignalRef> | null;
+}
+
+export type MarkPropDef<
+    F extends Field,
+    V extends Value,
+    T extends Type = Type
+> = MarkPropFieldOrDatumOrExprDef<F, T> | ValueDef<V>;
+
+export type ColorDef<F extends Field> = MarkPropDef<F, string | null>;
+
+export type SecondaryFieldDef<F extends Field> = FieldDefBase<F> & TitleMixins;
+
+export type NumericValueDef = ValueDef<number>;
+
+export type ScaleDatumDef = ScaleMixins & DatumDef;
+
+export type PositionDatumDefBase = ScaleDatumDef & TypeMixins<Type>;
+
+export type PositionFieldDef<F extends Field> = PositionFieldDefBase<F> &
+    PositionMixins;
+
+export type PositionDatumDef = PositionDatumDefBase & PositionMixins;
+
+export type PositionExprDef = ExprDef &
+    PositionMixins &
+    BandMixins &
+    TypeMixins<Type>;
+
+export type PositionValueDef = NumericValueDef;
+
+export interface PositionMixins extends BandMixins {
+    /**
+     * An object defining properties of axis's gridlines, ticks and labels.
+     * If `null`, the axis for the encoding channel will be removed.
+     *
+     * __Default value:__ If undefined, default [axis properties](https://vega.github.io/vega-lite/docs/axis.html) are applied.
+     *
+     * __See also:__ [`axis`](https://vega.github.io/vega-lite/docs/axis.html) documentation.
+     */
+    axis?: Axis | null;
+}
+
+export type PositionFieldDefBase<F extends Field> = ScaleFieldDef<F, Type>;
+
+export interface ChromPosDefBase extends BandMixins {
     /**
      * The field having the chromosome or contig.
      */
@@ -111,17 +259,169 @@ export interface ChromPosDef extends ChannelDefWithScale {
     offset?: number;
 }
 
-export interface FacetFieldDef extends ChannelDefBase {
-    field: FieldName;
-    spacing?: number;
-}
+export type SecondaryChromPosDef = ChromPosDefBase &
+    TitleMixins &
+    PositionMixins;
+
+export type ChromPosDef = SecondaryChromPosDef &
+    TypeMixins<"locus"> &
+    ScaleMixins;
 
-export type ChannelDef =
-    | FieldDef
-    | DatumDef
-    | ValueDef
-    | ExprDef
+export type PositionDef<F extends Field> =
+    | PositionFieldDef<F>
     | ChromPosDef
-    | FacetFieldDef;
+    | PositionDatumDef
+    | PositionExprDef
+    | PositionValueDef;
+
+export type Position2Def<F extends Field> =
+    | (SecondaryFieldDef<F> & BandMixins)
+    | SecondaryChromPosDef
+    | (DatumDef & BandMixins)
+    | (ExprDef & BandMixins)
+    | PositionValueDef;
+
+export type NumericMarkPropDef<F extends Field> = MarkPropDef<F, number>;
+
+export type ShapeDef<F extends Field> = MarkPropDef<
+    F,
+    string | null,
+    TypeForShape
+>;
+
+export interface StringFieldDef<F extends Field>
+    extends FieldDefWithoutScale<F>,
+        FormatMixins {}
 
-export type Encoding = Partial<Record<Channel, ChannelDef | null>>;
+export type TextDef<F extends Field> = StringFieldDef<F> | StringDatumDef;
+
+export type ChannelDef<F extends Field = string> =
+    Encoding<F>[keyof Encoding<F>];
+
+// TODO: Does this make sense?
+export type ChannelDefWithScale = ScaleMixins & TypeMixins<Type>;
+
+export interface Encoding<F extends Field = string> {
+    /**
+     * X coordinates of the marks.
+     *
+     * The `value` of this channel can be a number between zero and one.
+     */
+    x?: PositionDef<F>;
+
+    /**
+     * Y coordinates of the marks.
+     *
+     * The `value` of this channel can be a number between zero and one.
+     */
+    y?: PositionDef<F>;
+
+    /**
+     * X2 coordinates of the marks.
+     *
+     * The `value` of this channel can be a number between zero and one.
+     */
+    x2?: Position2Def<F>;
+
+    /**
+     * Y2 coordinates of the marks.
+     *
+     * The `value` of this channel can be a number between zero and one.
+     */
+    y2?: Position2Def<F>;
+
+    dx?: NumericMarkPropDef<F>;
+    dy?: NumericMarkPropDef<F>;
+
+    /**
+     * Color of the marks – either fill or stroke color based on  the `filled` property of mark definition.
+     *
+     * _Note:_
+     * 1) For fine-grained control over both fill and stroke colors of the marks, please use the `fill` and `stroke` channels. The `fill` or `stroke` encodings have higher precedence than `color`, thus may override the `color` encoding if conflicting encodings are specified.
+     * 2) See the scale documentation for more information about customizing [color scheme](https://vega.github.io/vega-lite/docs/scale.html#scheme).
+     */
+    color?: ColorDef<F>;
+
+    /**
+     * Fill color of the marks.
+     *
+     * _Note:_ The `fill` encoding has higher precedence than `color`, thus may override the `color` encoding if conflicting encodings are specified.
+     */
+    fill?: ColorDef<F>;
+
+    /**
+     * Stroke color of the marks.
+     *
+     * _Note:_ The `stroke` encoding has higher precedence than `color`, thus may override the `color` encoding if conflicting encodings are specified.
+     */
+
+    stroke?: ColorDef<F>;
+
+    /**
+     * Opacity of the marks.
+     */
+    opacity?: NumericMarkPropDef<F>;
+
+    /**
+     * Fill opacity of the marks.
+     */
+    fillOpacity?: NumericMarkPropDef<F>;
+
+    /**
+     * Stroke opacity of the marks.
+     */
+    strokeOpacity?: NumericMarkPropDef<F>;
+
+    /**
+     * Stroke width of the marks.
+     */
+    strokeWidth?: NumericMarkPropDef<F>;
+
+    /**
+     * Size of the mark.
+     * - For `"point"` – the symbol size, or pixel area of the mark.
+     * - For `"text"` – the text's font size.
+     */
+    size?: NumericMarkPropDef<F>;
+
+    /**
+     * Rotation angle of point and text marks.
+     */
+    angle?: NumericMarkPropDef<F>;
+
+    /**
+     * Shape of the mark.
+     *
+     * For `point` marks the supported values include:
+     * - plotting shapes: `"circle"`, `"square"`, `"cross"`, `"diamond"`, `"triangle-up"`, `"triangle-down"`, `"triangle-right"`, or `"triangle-left"`.
+     * - centered directional shape `"triangle"`
+     */
+    shape?: ShapeDef<F>;
+
+    /**
+     * Text of the `text` mark.
+     */
+    text?: TextDef<F>;
+
+    /**
+     * Facet identifier for interactive filtering, sorting, and grouping in the App.
+     */
+    sample?: FieldDefWithoutScale<F>;
+
+    /**
+     * For internal use
+     */
+    // TODO: proper type
+    uniqueId?: FieldDefWithoutScale<F>;
+
+    // TODO: proper type
+    search?: FieldDefWithoutScale<F>;
+
+    /**
+     * For internal use
+     */
+    // TODO: proper type
+    facetIndex?: FieldDefWithoutScale<F>;
+
+    semanticScore?: FieldDefWithoutScale<F>;
+}

package/src/spec/data.d.ts

@@ -42,7 +42,7 @@ export interface DataFormatBase {
      * __Default value:__  The default format type is determined by the extension of the file URL.
      * If no extension is detected, `"json"` will be used by default.
      */
-    type?: "csv" | "tsv" | "dsv" | "json";
+    type?: DataFormatType;
 }
 
 export interface CsvDataFormat extends DataFormatBase {
@@ -73,9 +73,20 @@ export interface JsonDataFormat extends DataFormatBase {
     property?: string;
 }
 
-export type DataFormat = CsvDataFormat | DsvDataFormat | JsonDataFormat;
+/**
+ * Other data format, such as `"fasta"`
+ */
+export interface OtherDataFormat {
+    type: string;
+}
+
+export type DataFormat =
+    | CsvDataFormat
+    | DsvDataFormat
+    | JsonDataFormat
+    | OtherDataFormat;
 
-export type DataFormatType = "json" | "csv" | "tsv" | "dsv";
+export type DataFormatType = "json" | "csv" | "tsv" | "dsv" | string;
 
 export type DataSource =
     | UrlData

package/src/spec/root.d.ts

@@ -1,15 +1,10 @@
 import { GenomeConfig } from "./genome";
 import { ViewSpec } from "./view";
 
-export interface RootConfig {
-    genome?: GenomeConfig;
+interface RootConfig {
+    $schema?: string;
 
-    /**
-     * A unique identifier that is used in storing state bookmarks to browser's
-     * IndexedDB. This is needed to make distinction between visualizations that
-     * are served from the same origin, i.e., the same host and port.
-     */
-    specId?: string;
+    genome?: GenomeConfig;
 
     baseUrl?: string;