@genome-spy/core 0.14.0

package/src/spec/axis.d.ts

@@ -0,0 +1,296 @@
+import { Align, Baseline, FontStyle, FontWeight } from "./font";
+
+export interface GenomeAxis extends Axis {
+    chromTicks?: boolean;
+    chromTickSize?: number;
+    chromTickWidth?: number;
+    chromTickColor?: string;
+    chromTickDash?: number[];
+    chromTickDashOffset?: number;
+
+    chromLabels?: boolean;
+    chromLabelFont?: string;
+    chromLabelFontSize?: number;
+    chromLabelFontWeight?: FontWeight;
+    chromLabelFontStyle?: FontStyle;
+    chromLabelColor?: string;
+    chromLabelPadding?: number;
+    chromLabelAlign?: Align;
+    // TODO: chromLabelPerpendicularPadding
+}
+
+/*!
+ * Adapted from
+ * https://github.com/vega/vega/blob/master/packages/vega-typings/types/spec/axis.d.ts
+ *
+ * Copyright (c) 2015-2018, University of Washington Interactive Data Lab
+ * All rights reserved.
+ *
+ * BSD-3-Clause License: https://github.com/vega/vega/blob/master/LICENSE
+ */
+
+export type AxisOrient = "top" | "bottom" | "left" | "right";
+
+export interface Axis extends BaseAxis {
+    /**
+     * The orientation of the axis. One of `"top"`, `"bottom"`, `"left"` or `"right"`. The orientation can be used to further specialize the axis type (e.g., a y axis oriented for the right edge of the chart).
+     *
+     * __Default value:__ `"bottom"` for x-axes and `"left"` for y-axes.
+     */
+    orient?: AxisOrient;
+
+    /**
+     * The format specifier pattern for axis labels.
+     * Must be a legal [d3-format](https://github.com/d3/d3-format#locale_format) specifier.
+     */
+    format?: string;
+
+    /**
+     * A title for the axis (none by default).
+     */
+    title?: string;
+
+    /**
+     * The orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.
+     */
+    offset?: number;
+
+    /**
+     * A desired number of ticks, for axes visualizing quantitative scales. The resulting number may be different so that values are "nice" (multiples of `2`, `5`, `10`) and lie within the underlying scale's range.
+     *
+     * @minimum 0
+     */
+    tickCount?: number;
+
+    /**
+     * The minimum desired step between axis ticks, in terms of scale domain values. For example, a value of `1` indicates that ticks should not be less than 1 unit apart. If `tickMinStep` is specified, the `tickCount` value will be adjusted, if necessary, to enforce the minimum step value.
+     */
+    tickMinStep?: number;
+
+    /**
+     * Explicitly set the visible axis tick and label values.
+     */
+    values?: any[];
+}
+
+export interface BaseAxis<
+    N = number,
+    NS = number,
+    B = boolean,
+    BNS = number | boolean,
+    S = string,
+    C = string,
+    FW = string,
+    FS = string
+> {
+    /**
+     * The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.
+     *
+     * __Default value:__ `30` for y-axis; `undefined` for x-axis.
+     */
+    minExtent?: N;
+
+    /**
+     * The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.
+     *
+     * __Default value:__ `undefined`.
+     */
+    maxExtent?: N;
+
+    // ---------- Title ----------
+    /**
+     * The padding, in pixels, between title and axis.
+     */
+    titlePadding?: N;
+
+    /**
+     * Color of the title, can be in hex color code or regular color name.
+     */
+    titleColor?: C;
+
+    /**
+     * Font of the title. (e.g., `"Helvetica Neue"`).
+     */
+    titleFont?: S;
+
+    /**
+     * Font size of the title.
+     *
+     * @minimum 0
+     */
+    titleFontSize?: N;
+
+    /**
+     * Font style of the title.
+     */
+    titleFontStyle?: FS;
+
+    /**
+     * Font weight of the title.
+     * This can be either a string (e.g `"bold"`, `"normal"`) or a number (`100`, `200`, `300`, ..., `900` where `"normal"` = `400` and `"bold"` = `700`).
+     */
+    titleFontWeight?: FW;
+
+    /**
+     * Opacity of the axis title.
+     */
+    titleOpacity?: N;
+
+    // ---------- Domain ----------
+    /**
+     * A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.
+     *
+     * __Default value:__ `true`
+     */
+    domain?: boolean;
+
+    /**
+     * The stroke cap for the domain line's ending style. One of `"butt"`, `"round"` or `"square"`.
+     *
+     * __Default value:__ `"butt"`
+     */
+    domainCap?: "butt" | "round" | "square";
+
+    /**
+     * An array of alternating [stroke, space] lengths for dashed domain lines.
+     */
+    domainDash?: number[];
+
+    /**
+     * The pixel offset at which to start drawing with the domain dash array.
+     */
+    domainDashOffset?: number;
+
+    /**
+     * Color of axis domain line.
+     *
+     * __Default value:__ `"gray"`.
+     */
+    domainColor?: C;
+
+    /**
+     * Stroke width of axis domain line
+     *
+     * __Default value:__ `1`
+     */
+    domainWidth?: N;
+
+    // ---------- Ticks ----------
+    /**
+     * Boolean value that determines whether the axis should include ticks.
+     *
+     * __Default value:__ `true`
+     */
+    ticks?: B;
+
+    /**
+     * The stroke cap for the tick lines' ending style. One of `"butt"`, `"round"` or `"square"`.
+     *
+     * __Default value:__ `"butt"`
+     */
+    tickCap?: "butt" | "round" | "square";
+
+    /**
+     * The color of the axis's tick.
+     *
+     * __Default value:__ `"gray"`
+     */
+    tickColor?: C;
+
+    /**
+     * An array of alternating [stroke, space] lengths for dashed tick mark lines.
+     */
+    tickDash?: number[];
+
+    /**
+     * The pixel offset at which to start drawing with the tick mark dash array.
+     */
+    tickDashOffset?: number;
+
+    /**
+     * The size in pixels of axis ticks.
+     *
+     * __Default value:__ `5`
+     * @minimum 0
+     */
+    tickSize?: N;
+
+    /**
+     * The width, in pixels, of ticks.
+     *
+     * __Default value:__ `1`
+     * @minimum 0
+     */
+    tickWidth?: N;
+
+    // ---------- Labels ----------
+    /**
+     * A boolean flag indicating if labels should be included as part of the axis.
+     *
+     * __Default value:__ `true`.
+     */
+    labels?: boolean;
+
+    /**
+     * Horizontal text alignment of axis tick labels, overriding the default setting for the current axis orientation.
+     */
+    labelAlign?: Align;
+
+    /**
+     * The rotation angle of the axis labels.
+     *
+     * __Default value:__ `-90` for nominal and ordinal fields; `0` otherwise.
+     *
+     * @minimum -360
+     * @maximum 360
+     */
+    labelAngle?: number;
+
+    /**
+     * Vertical text baseline of axis tick labels, overriding the default setting for the current axis orientation.
+     * One of `"alphabetic"` (default), `"top"`, `"middle"`, `"bottom"`.
+     */
+    labelBaseline?: Baseline;
+
+    /**
+     * The color of the tick label, can be in hex color code or regular color name.
+     */
+    labelColor?: C;
+
+    /**
+     * The font of the tick label.
+     */
+    labelFont?: S;
+
+    /**
+     * The font size of the label, in pixels.
+     *
+     * @minimum 0
+     */
+    labelFontSize?: N;
+
+    /**
+     * Font style of the title.
+     */
+    labelFontStyle?: FS;
+
+    /**
+     * Font weight of axis tick labels.
+     */
+    labelFontWeight?: FW;
+
+    /**
+     * Maximum allowed pixel width of axis tick labels.
+     *
+     * __Default value:__ `180`
+     */
+    labelLimit?: N;
+
+    /**
+     * The padding, in pixels, between axis and text labels.
+     *
+     * __Default value:__ `2`
+     */
+
+    labelPadding?: N;
+}

package/src/spec/channel.d.ts

@@ -0,0 +1,127 @@
+import { Scale } from "./scale";
+import { Axis } from "./axis";
+
+export type Scalar = string | number | boolean;
+export type FieldName = string;
+
+export type PositionalChannel = "x" | "y";
+
+export type SecondaryPositionalChannel = "x2" | "y2";
+
+export type Channel =
+    | PositionalChannel
+    | SecondaryPositionalChannel
+    | "color"
+    | "fill"
+    | "stroke"
+    | "opacity"
+    | "fillOpacity"
+    | "strokeOpacity"
+    | "strokeWidth"
+    | "size"
+    | "shape"
+    | "text"
+    | "size2"
+    | "color2"
+    | "angle"
+    | "sample"
+    | "uniqueId"
+    | "search"
+    | "facetIndex"
+    | "semanticScore"
+    | "dx"
+    | "dy";
+
+export interface ChannelDefBase {
+    title?: string | null;
+}
+
+export interface ValueDef extends ChannelDefBase {
+    /** A constant value in the context of the range */
+    value: Scalar;
+}
+
+export interface ChannelDefWithScale extends ChannelDefBase {
+    type: string;
+
+    /**
+     * Offset within a band of a band scale, [0, 1]
+     *
+     * TODO: rename to bandPosition: https://github.com/vega/vega-lite/pull/7190
+     */
+    band?: number;
+
+    scale?: Scale;
+    axis?: Axis | null;
+
+    format?: string;
+
+    /**
+     * Use emulated 64 bit floating points to increase precision of scales
+     * computed on the GPU. By default, 32 bit floats are used.
+     */
+    fp64?: boolean;
+
+    /**
+     * Use 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.
+     */
+    resolutionChannel?: Channel;
+}
+
+export interface FieldDef extends ChannelDefWithScale {
+    field: FieldName;
+}
+
+export interface DatumDef extends ChannelDefWithScale {
+    /** A constant value on the data domain */
+    datum: Scalar;
+}
+
+export interface ExprDef extends ChannelDefWithScale {
+    /** An expression. Properties of the data can be accessed through the `datum` object. */
+    expr: string;
+}
+export interface ChromPosDef extends ChannelDefWithScale {
+    type: "locus";
+
+    /**
+     * The field having the chromosome or contig.
+     */
+    chrom: FieldName;
+
+    /**
+     * The field having an intra-chromosomal position.
+     */
+    pos?: FieldName;
+
+    /**
+     * An offset or offsets that allow for adjusting the numbering base. The offset
+     * is subtracted from the positions.
+     *
+     * GenomeSpy uses internally zero-based indexing with half-open intervals.
+     * UCSC-based formats (BED, etc.) generally use this scheme. However, for example,
+     * VCF files use one-based indexing and must be adjusted by setting the offset to
+     * `1`.
+     *
+     * **Default:** `0`
+     */
+    offset?: number;
+}
+
+export interface FacetFieldDef extends ChannelDefBase {
+    field: FieldName;
+    spacing?: number;
+}
+
+export type ChannelDef =
+    | FieldDef
+    | DatumDef
+    | ValueDef
+    | ExprDef
+    | ChromPosDef
+    | FacetFieldDef;
+
+export type Encoding = Partial<Record<Channel, ChannelDef | null>>;

package/src/spec/data.d.ts

@@ -0,0 +1,185 @@
+/*!
+ * Adapted from
+ * https://github.com/vega/vega-lite/blob/master/src/data.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
+ */
+
+/*
+ * Constants and utilities for data.
+ */
+import { FieldName } from "./channel";
+
+export type ParseValue =
+    | null
+    | string
+    | "string"
+    | "boolean"
+    | "date"
+    | "number";
+
+export interface Parse {
+    [field: string]: ParseValue;
+}
+
+export interface DataFormatBase {
+    /**
+     * If set to `null`, disable type inference based on the spec and only use type inference based on the data.
+     * Alternatively, a parsing directive object can be provided for explicit data types. Each property of the object corresponds to a field name, and the value to the desired data type (one of `"number"`, `"boolean"`, `"date"`, or null (do not parse the field)).
+     * For example, `"parse": {"modified_on": "date"}` parses the `modified_on` field in each input record a Date value.
+     *
+     * For `"date"`, we parse data based using Javascript's [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse).
+     * For Specific date formats can be provided (e.g., `{foo: "date:'%m%d%Y'"}`), using the [d3-time-format syntax](https://github.com/d3/d3-time-format#locale_format). UTC date format parsing is supported similarly (e.g., `{foo: "utc:'%m%d%Y'"}`). See more about [UTC time](https://vega.github.io/vega-lite/docs/timeunit.html#utc)
+     */
+    parse?: Parse | null;
+
+    /**
+     * Type of input data: `"json"`, `"csv"`, `"tsv"`, `"dsv"`.
+     *
+     * __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";
+}
+
+export interface CsvDataFormat extends DataFormatBase {
+    type?: "csv" | "tsv";
+}
+
+export interface DsvDataFormat extends DataFormatBase {
+    type?: "dsv";
+
+    /**
+     * The delimiter between records. The delimiter must be a single character (i.e., a single 16-bit code unit); so, ASCII delimiters are fine, but emoji delimiters are not.
+     *
+     * @minLength 1
+     * @maxLength 1
+     */
+    delimiter: string;
+}
+
+export interface JsonDataFormat extends DataFormatBase {
+    type?: "json";
+
+    /**
+     * The JSON property containing the desired data.
+     * This parameter can be used when the loaded JSON file may have surrounding structure or meta-data.
+     * For example `"property": "values.features"` is equivalent to retrieving `json.values.features`
+     * from the loaded JSON object.
+     */
+    property?: string;
+}
+
+export type DataFormat = CsvDataFormat | DsvDataFormat | JsonDataFormat;
+
+export type DataFormatType = "json" | "csv" | "tsv" | "dsv";
+
+export type DataSource =
+    | UrlData
+    | InlineData
+    | NamedData
+    | DynamicCallbackData
+    | DynamicData;
+
+export type Data = DataSource | Generator;
+
+export type InlineDataset =
+    | number[]
+    | string[]
+    | boolean[]
+    | object[]
+    | string
+    | object;
+
+export interface DataBase {
+    /**
+     * An object that specifies the format for parsing the data.
+     */
+    format?: DataFormat;
+
+    /**
+     * Provide a placeholder name and bind data at runtime.
+     */
+    name?: string;
+}
+
+export interface UrlData extends DataBase {
+    /**
+     * An URL or an array of URLs from which to load the data set.
+     * Use the `format.type` property to ensure the loaded data is correctly parsed.
+     */
+    url: string | string[];
+}
+
+export interface InlineData extends DataBase {
+    /**
+     * The full data set, included inline. This can be an array of objects or primitive values, an object, or a string.
+     * Arrays of primitive values are ingested as objects with a `data` property. Strings are parsed according to the specified format type.
+     */
+    values: InlineDataset;
+}
+
+export interface NamedData extends DataBase {
+    /**
+     * Provide a placeholder name and bind data at runtime.
+     */
+    name: string;
+}
+
+export interface DynamicCallbackData extends DataBase {
+    /**
+     * The View class has `getDynamicData()` methods that provides the data.
+     * This is intended for internal use.
+     */
+    dynamicCallbackSource: boolean;
+}
+
+export interface DynamicData extends DataBase {
+    /**
+     * For internal use.
+     */
+    dynamicSource: boolean;
+}
+
+export type Generator = SequenceGenerator;
+
+export interface GeneratorBase {
+    /**
+     * Provide a placeholder name and bind data at runtime.
+     */
+    name?: string;
+}
+
+export interface SequenceGenerator extends GeneratorBase {
+    /**
+     * Generate a sequence of numbers.
+     */
+    sequence: SequenceParams;
+}
+
+export interface SequenceParams {
+    /**
+     * The starting value of the sequence (inclusive).
+     */
+    start: number;
+    /**
+     * The ending value of the sequence (exclusive).
+     */
+    stop: number;
+    /**
+     * The step value between sequence entries.
+     *
+     * __Default value:__ `1`
+     */
+    step?: number;
+
+    /**
+     * The name of the generated sequence field.
+     *
+     * __Default value:__ `"data"`
+     */
+    as?: FieldName;
+}

package/src/spec/font.d.ts

@@ -0,0 +1,15 @@
+export type FontStyle = "normal" | "italic";
+
+export type FontWeight =
+    | number
+    | "thin"
+    | "light"
+    | "regular"
+    | "normal"
+    | "medium"
+    | "bold"
+    | "black";
+
+export type Align = "left" | "center" | "right";
+
+export type Baseline = "top" | "middle" | "bottom" | "alphabetic";

package/src/spec/genome.d.ts

@@ -0,0 +1,35 @@
+export interface Contig {
+    name: string;
+    size: number;
+}
+
+export interface GenomeConfig {
+    /**
+     * Name of the genome assembly, e.g., `hg19` or `hg38`.
+     */
+    name: string;
+
+    /**
+     * Base url of data files: chromsizes, cytobands, and gene annotations.
+     *
+     * **Default:** `"https://genomespy.app/data/genomes/"`
+     */
+    baseUrl?: string;
+
+    /**
+     * As an alternative for chromSizes, the contigs can be provided inline.
+     */
+    contigs?: Contig[];
+}
+
+export interface ChromosomalLocus {
+    /**
+     * The name of the chromosome. For example: `"chr1"`, `"CHR1"`, or `"1"`.
+     */
+    chrom: string;
+
+    /**
+     * The zero-based position inside the chromosome or contig.
+     */
+    pos?: number;
+}