@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/colorScale.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The scales a colour object paints through, in a module that imports
+ * nothing: `jbrowse validate` carries a copy of it, so the validator and the
+ * displays read one statement.
+ */
+/** How a colour object maps its `field`; `none` paints `value`. */
+export declare const COLOR_SCALES: readonly ['none', 'categorical', 'linear', 'log', 'threshold'];
+/**
+ * The scale that maps no field: each feature paints the colour it carries, and
+ * the key names the colours `domain` lists. Only a display whose features
+ * carry colours of their own declares it.
+ */
+export declare const IDENTITY_SCALE = "identity";
+export type ColorScaleName = (typeof COLOR_SCALES)[number] | typeof IDENTITY_SCALE;
+/**
+ * A field's defaults on a display: the scale it paints through while `scale`
+ * is unset, and the members that scale reads while the config leaves them
+ * unwritten, so a field with a vocabulary or ramp of its own is the colour
+ * object's defaults rather than a painter beside it.
+ */
+export interface FieldPreset<S extends string = ColorScaleName> {
+    scale: S;
+    /** The key a feature carrying no value files under. */
+    missing?: string;
+    domain?: readonly string[];
+    range?: readonly string[];
+    labels?: readonly string[];
+    title?: string;
+    domainMin?: number;
+    domainMax?: number;
+    domainMid?: number;
+    scheme?: string;
+    reverse?: boolean;
+}
+/** Each field's preset, `*` for any other field. */
+export type FieldPresets<S extends string = ColorScaleName> = Readonly<Record<string, FieldPreset<S>>>;
+/**
+ * The fields whose values have names, an order and colours of their own on
+ * every display, beneath each display's own presets. Red forward and blue
+ * reverse is what the synteny ribbons paint too. The SV classes are
+ * `svClassOf`'s, deletion red and duplication blue as dbVar and gnomAD-SV
+ * paint them, insertion the pileup's purple, and the rest kept apart under
+ * deuteranopia and protanopia. A record with no class files under `''`, so
+ * each display keeps its own no-value colour for it.
+ */
+export declare const UNIVERSAL_FIELD_PRESETS: {
+    readonly strand: {
+        readonly scale: 'categorical';
+        readonly missing: '0';
+        readonly domain: readonly ["1", "-1", "0"];
+        readonly range: readonly ["tomato", "cornflowerblue", "goldenrod"];
+        readonly labels: readonly ["Forward strand", "Reverse strand", "No strand"];
+    };
+    readonly svType: {
+        readonly scale: 'categorical';
+        readonly domain: readonly ["DEL", "DUP", "INS", "INV", "CNV", "TR", "BND", "CPX", "OTHER"];
+        readonly range: readonly ["#e41a1c", "#377eb8", "#800080", "#ff7f00", "#7e6148", "#e7298a", "#17becf", "#66a61e", "#000000"];
+        readonly labels: readonly ["Deletion", "Duplication", "Insertion", "Inversion", "Copy-number variable", "Tandem repeat", "Breakend / translocation", "Complex", "Other / mixed"];
+        readonly title: 'SV type';
+    };
+};
+/** The universal preset of `field`, if it has one. */
+export declare function universalPresetOf(field: string): FieldPreset<'categorical'> | undefined;
+/** Every field categorical while `scale` is unset, with nothing preset. */
+export declare const CATEGORICAL_FIELD_PRESETS: {
+    readonly '*': FieldPreset<"categorical">;
+};
+/**
+ * What a feature's field paints through while `scale` is unset: `score` a
+ * ramp, any other field categories.
+ */
+export declare const FEATURE_FIELD_PRESETS: {
+    readonly score: {
+        readonly scale: 'linear';
+    };
+    readonly '*': FieldPreset<"categorical">;
+};
+/**
+ * A field's preset under `presets`: its own, else a universal one, else
+ * `*`'s, else categorical.
+ */
+export declare function presetOf<S extends string>(presets: FieldPresets<S>, field: string): FieldPreset<S | 'categorical'>;
+/** What a field paints through under `presets` while `scale` is unset. */
+export declare function fieldScaleOf<S extends string>(presets: FieldPresets<S>, field: string): S | 'categorical';
+/**
+ * A colour object with its field's preset under it: each member the preset
+ * names and the config leaves unwritten, an empty list counting as unwritten.
+ * Only while the colour paints through the preset's own scale, so the cuts of
+ * a threshold preset never reach a field read through a ramp. A categorical
+ * preset's `range` and `labels` name its `domain`'s values in order, so they
+ * fill only while `domain` does too: a written order keeps each value's own
+ * colour and name.
+ */
+export declare function withPreset<C extends {
+    field?: string;
+    scale?: string;
+}>(color: C, presets: FieldPresets<string>): C;
+/**
+ * The scale a colour object paints through: `none` while no `field` is
+ * named, else its own `scale`, or `fieldScale` where that is unset.
+ */
+export declare function paintedScale<S extends string, F extends string>({ scale, field }: {
+    scale: S | undefined;
+    field: string;
+}, fieldScale: F): S | F | 'none';
+/** A combination of a scale's slots the display cannot draw as written. */
+export interface ScaleProblem {
+    rule: 'threshold-cuts' | 'threshold-range' | 'ramp-domain' | 'domain-ends' | 'domain-quantile' | 'labels-domain';
+    /** the slot to look at, relative to the scale's own object */
+    slot: string;
+    message: string;
+}
+/**
+ * The members a quantitative scale's ends are read by, as a colour ramp,
+ * `scales.y` and a mark's width spell them alike.
+ */
+export interface ScaleEnds {
+    domainMin?: number;
+    domainMax?: number;
+    domainQuantile?: number;
+}
+/**
+ * What a quantitative scale's ends say together that neither can refuse
+ * alone: a `domainMax` below its `domainMin`, which every such scale draws in
+ * order either way, and a `domainQuantile` outside 0.5 to 1, where the quantile
+ * an open end follows is clamped. `reverse` is whether the scale turns round by
+ * a member of its own, which is then the spelling to point at.
+ */
+export declare function scaleEndProblems({ domainMin, domainMax, domainQuantile }: ScaleEnds, { reverse }?: {
+    reverse?: boolean;
+}): ScaleProblem[];
+/** Problems as the lines a display's corner notice lists, under the setting that holds the scale. */
+export declare function noticeLines(setting: string, problems: readonly ScaleProblem[]): string[];
+/** The slots `colorProblems` reads, as a snapshot or a resolved setting holds them. */
+export interface ColorSlots {
+    value?: string;
+    field?: string;
+    scale?: string;
+    domain?: readonly unknown[];
+    range?: readonly unknown[];
+    domainMin?: number;
+    domainMax?: number;
+    domainQuantile?: number;
+    labels?: readonly unknown[];
+}
+/**
+ * What a colour object's slots say together that no single slot can refuse,
+ * since the config editor writes one slot at a time (ADR-133), read with its
+ * field's preset under it. A display shows these as a notice and draws what
+ * it can. A threshold naming no cuts leaves its intervals to the display —
+ * the alignments insert-size band samples its cuts, the wiggle plot cuts at
+ * its origin — so its `labels` go uncounted.
+ */
+export declare function colorProblems(written: ColorSlots, presets: FieldPresets<string>): ScaleProblem[];
+/** `colorProblems` as the lines a display's corner notice lists, under `color`. */
+export declare function colorNotices(color: ColorSlots, presets: FieldPresets<string>): string[];

package/esm/util/colorScale.js

@@ -0,0 +1,243 @@
+/**
+ * The scales a colour object paints through, in a module that imports
+ * nothing: `jbrowse validate` carries a copy of it, so the validator and the
+ * displays read one statement.
+ */
+/** How a colour object maps its `field`; `none` paints `value`. */
+export const COLOR_SCALES = [
+    'none',
+    'categorical',
+    'linear',
+    'log',
+    'threshold',
+];
+/**
+ * The scale that maps no field: each feature paints the colour it carries, and
+ * the key names the colours `domain` lists. Only a display whose features
+ * carry colours of their own declares it.
+ */
+export const IDENTITY_SCALE = 'identity';
+const CATEGORICAL_PRESET = { scale: 'categorical' };
+/**
+ * The fields whose values have names, an order and colours of their own on
+ * every display, beneath each display's own presets. Red forward and blue
+ * reverse is what the synteny ribbons paint too. The SV classes are
+ * `svClassOf`'s, deletion red and duplication blue as dbVar and gnomAD-SV
+ * paint them, insertion the pileup's purple, and the rest kept apart under
+ * deuteranopia and protanopia. A record with no class files under `''`, so
+ * each display keeps its own no-value colour for it.
+ */
+export const UNIVERSAL_FIELD_PRESETS = {
+    strand: {
+        scale: 'categorical',
+        missing: '0',
+        domain: ['1', '-1', '0'],
+        range: ['tomato', 'cornflowerblue', 'goldenrod'],
+        labels: ['Forward strand', 'Reverse strand', 'No strand'],
+    },
+    svType: {
+        scale: 'categorical',
+        domain: ['DEL', 'DUP', 'INS', 'INV', 'CNV', 'TR', 'BND', 'CPX', 'OTHER'],
+        range: [
+            '#e41a1c',
+            '#377eb8',
+            '#800080',
+            '#ff7f00',
+            '#7e6148',
+            '#e7298a',
+            '#17becf',
+            '#66a61e',
+            '#000000',
+        ],
+        labels: [
+            'Deletion',
+            'Duplication',
+            'Insertion',
+            'Inversion',
+            'Copy-number variable',
+            'Tandem repeat',
+            'Breakend / translocation',
+            'Complex',
+            'Other / mixed',
+        ],
+        title: 'SV type',
+    },
+};
+/** The universal preset of `field`, if it has one. */
+export function universalPresetOf(field) {
+    return Object.hasOwn(UNIVERSAL_FIELD_PRESETS, field)
+        ? UNIVERSAL_FIELD_PRESETS[field]
+        : undefined;
+}
+/** Every field categorical while `scale` is unset, with nothing preset. */
+export const CATEGORICAL_FIELD_PRESETS = {
+    '*': CATEGORICAL_PRESET,
+};
+/**
+ * What a feature's field paints through while `scale` is unset: `score` a
+ * ramp, any other field categories.
+ */
+export const FEATURE_FIELD_PRESETS = {
+    score: { scale: 'linear' },
+    '*': CATEGORICAL_PRESET,
+};
+/**
+ * A field's preset under `presets`: its own, else a universal one, else
+ * `*`'s, else categorical.
+ */
+export function presetOf(presets, field) {
+    return ((Object.hasOwn(presets, field)
+        ? presets[field]
+        : (universalPresetOf(field) ?? presets['*'])) ?? CATEGORICAL_PRESET);
+}
+/** What a field paints through under `presets` while `scale` is unset. */
+export function fieldScaleOf(presets, field) {
+    return presetOf(presets, field).scale;
+}
+function unwritten(value) {
+    return value === undefined || (Array.isArray(value) && value.length === 0);
+}
+/**
+ * A colour object with its field's preset under it: each member the preset
+ * names and the config leaves unwritten, an empty list counting as unwritten.
+ * Only while the colour paints through the preset's own scale, so the cuts of
+ * a threshold preset never reach a field read through a ramp. A categorical
+ * preset's `range` and `labels` name its `domain`'s values in order, so they
+ * fill only while `domain` does too: a written order keeps each value's own
+ * colour and name.
+ */
+export function withPreset(color, presets) {
+    const field = color.field ?? '';
+    const preset = presetOf(presets, field);
+    if (!field || (color.scale ?? preset.scale) !== preset.scale) {
+        return color;
+    }
+    const written = new Map(Object.entries(color));
+    const ordered = preset.scale !== 'categorical' ||
+        !preset.domain ||
+        unwritten(written.get('domain'));
+    const filled = Object.entries(preset).filter(([key]) => key !== 'scale' &&
+        key !== 'missing' &&
+        (ordered || (key !== 'range' && key !== 'labels')) &&
+        unwritten(written.get(key)));
+    return filled.length > 0 ? { ...color, ...Object.fromEntries(filled) } : color;
+}
+/**
+ * The scale a colour object paints through: `none` while no `field` is
+ * named, else its own `scale`, or `fieldScale` where that is unset.
+ */
+export function paintedScale({ scale, field }, fieldScale) {
+    return field ? (scale ?? fieldScale) : 'none';
+}
+/**
+ * What a quantitative scale's ends say together that neither can refuse
+ * alone: a `domainMax` below its `domainMin`, which every such scale draws in
+ * order either way, and a `domainQuantile` outside 0.5 to 1, where the quantile
+ * an open end follows is clamped. `reverse` is whether the scale turns round by
+ * a member of its own, which is then the spelling to point at.
+ */
+export function scaleEndProblems({ domainMin, domainMax, domainQuantile }, { reverse = false } = {}) {
+    return [
+        ...(domainMin !== undefined &&
+            domainMax !== undefined &&
+            domainMin > domainMax
+            ? [
+                {
+                    rule: 'domain-ends',
+                    slot: 'domainMax',
+                    message: `domainMax is below domainMin: the scale spans the two in order either way${reverse ? ', and reverse is what turns it round' : ''}`,
+                },
+            ]
+            : []),
+        ...(domainQuantile !== undefined &&
+            !(domainQuantile >= 0.5 && domainQuantile <= 1)
+            ? [
+                {
+                    rule: 'domain-quantile',
+                    slot: 'domainQuantile',
+                    message: 'domainQuantile is a fraction from 0.5 to 1, not a percent: 1 follows the extremes and 0.99 clips the outermost 1% at each end; above 1 reads as 1 and below 0.5 as 0.5',
+                },
+            ]
+            : []),
+    ];
+}
+/** Problems as the lines a display's corner notice lists, under the setting that holds the scale. */
+export function noticeLines(setting, problems) {
+    return problems.map(({ slot, message }) => `${setting}.${slot}: ${message}`);
+}
+function pinned(entry) {
+    return entry !== '' && Number.isFinite(Number(entry));
+}
+/**
+ * What a colour object's slots say together that no single slot can refuse,
+ * since the config editor writes one slot at a time (ADR-133), read with its
+ * field's preset under it. A display shows these as a notice and draws what
+ * it can. A threshold naming no cuts leaves its intervals to the display —
+ * the alignments insert-size band samples its cuts, the wiggle plot cuts at
+ * its origin — so its `labels` go uncounted.
+ */
+export function colorProblems(written, presets) {
+    const color = withPreset(written, presets);
+    const { domain = [] } = color;
+    const { range = [] } = written;
+    const scale = color.scale === IDENTITY_SCALE
+        ? IDENTITY_SCALE
+        : paintedScale({ scale: color.scale, field: color.field ?? '' }, fieldScaleOf(presets, color.field ?? ''));
+    const problems = [];
+    if (scale === 'threshold') {
+        if (domain.some((cut, i) => !pinned(cut) || Number(cut) <= Number(domain[i - 1]))) {
+            problems.push({
+                rule: 'threshold-cuts',
+                slot: 'domain',
+                message: 'threshold cuts are distinct numbers, read in ascending order, with the range running from the lowest interval; a repeated cut leaves an interval no value falls in',
+            });
+        }
+        if (domain.length > 0 &&
+            range.length > 0 &&
+            range.length !== domain.length + 1) {
+            problems.push({
+                rule: 'threshold-range',
+                slot: 'range',
+                message: `${domain.length} threshold ${domain.length === 1 ? 'cut makes' : 'cuts make'} ${domain.length + 1} intervals, one colour each, and range lists ${range.length}: a missing colour comes from the default palette and an extra one is never read`,
+            });
+        }
+    }
+    if (scale === 'linear' || scale === 'log') {
+        if (domain.length > 0) {
+            problems.push({
+                rule: 'ramp-domain',
+                slot: 'domain',
+                message: "a linear or log scale reads no domain, which is a categorical scale's order and a threshold scale's cuts; a ramp's ends are domainMin and domainMax where the colour has them",
+            });
+        }
+        problems.push(...scaleEndProblems(color, { reverse: true }));
+    }
+    const { labels = [] } = color;
+    const named = scale === 'categorical' || scale === IDENTITY_SCALE
+        ? domain.length
+        : scale === 'threshold'
+            ? domain.length + 1
+            : undefined;
+    const cutsFromData = scale === 'threshold' && domain.length === 0;
+    if (labels.length > 0 &&
+        !cutsFromData &&
+        (named === undefined || labels.length > named)) {
+        const what = scale === 'categorical'
+            ? 'value'
+            : scale === IDENTITY_SCALE
+                ? 'colour'
+                : 'interval';
+        problems.push({
+            rule: 'labels-domain',
+            slot: 'labels',
+            message: named === undefined
+                ? "labels names a categorical scale's values, a threshold scale's intervals or an identity scale's colours, and this colour paints none of them"
+                : `labels names one ${what} each, and ${labels.length} ${labels.length === 1 ? 'label names' : 'labels name'} ${named} ${named === 1 ? what : `${what}s`}: a label past them names nothing`,
+        });
+    }
+    return problems;
+}
+/** `colorProblems` as the lines a display's corner notice lists, under `color`. */
+export function colorNotices(color, presets) {
+    return noticeLines('color', colorProblems(color, presets));
+}

package/esm/util/colorSchemes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * #api
+ * The named ramps a continuous colour scale's `scheme` takes, each one a stop
+ * table in `colorRamp.ts` that every ramp baker reads, so no display can name
+ * a scheme nothing bakes. `viridis`, `magma`, `inferno` and `cividis` are
+ * matplotlib's perceptual ramps, dark at the low end; `juicebox` fades from
+ * transparent to red, as Juicebox paints contacts; `fall` runs white through
+ * yellow and red to black, as HiGlass does; `reds` and `blues` are
+ * ColorBrewer's, from white; `redblue` and `purpleorange` diverge through
+ * white, ColorBrewer's RdBu and PuOr.
+ */
+export declare const COLOR_SCHEMES: readonly ['viridis', 'magma', 'inferno', 'cividis', 'juicebox', 'fall', 'reds', 'blues', 'redblue', 'purpleorange'];
+/** #api */
+export type ColorSchemeName = (typeof COLOR_SCHEMES)[number];
+/**
+ * #api
+ * The ramp a continuous scale samples while it names no `range` and no
+ * `scheme`, so a declaration spelling it out and one leaving it unset resolve
+ * alike.
+ */
+export declare const DEFAULT_COLOR_SCHEME: ColorSchemeName;

package/esm/util/colorSchemes.js

@@ -0,0 +1,30 @@
+/**
+ * #api
+ * The named ramps a continuous colour scale's `scheme` takes, each one a stop
+ * table in `colorRamp.ts` that every ramp baker reads, so no display can name
+ * a scheme nothing bakes. `viridis`, `magma`, `inferno` and `cividis` are
+ * matplotlib's perceptual ramps, dark at the low end; `juicebox` fades from
+ * transparent to red, as Juicebox paints contacts; `fall` runs white through
+ * yellow and red to black, as HiGlass does; `reds` and `blues` are
+ * ColorBrewer's, from white; `redblue` and `purpleorange` diverge through
+ * white, ColorBrewer's RdBu and PuOr.
+ */
+export const COLOR_SCHEMES = [
+    'viridis',
+    'magma',
+    'inferno',
+    'cividis',
+    'juicebox',
+    'fall',
+    'reds',
+    'blues',
+    'redblue',
+    'purpleorange',
+];
+/**
+ * #api
+ * The ramp a continuous scale samples while it names no `range` and no
+ * `scheme`, so a declaration spelling it out and one leaving it unset resolve
+ * alike.
+ */
+export const DEFAULT_COLOR_SCHEME = 'viridis';

package/esm/util/colord.d.ts

@@ -1,3 +1,9 @@
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
 interface HSLA {
     h: number;
     s: number;
@@ -8,6 +14,7 @@ export interface Colord {
     alpha(): number;
     alpha(value: number): Colord;
     toHex(): string;
+    toRgb(): RGBA;
     toRgbString(): string;
     toHsl(): HSLA;
     toHslString(): string;
@@ -20,4 +27,5 @@ export declare function colord(input: string | {
     s: number;
     l: number;
 }): Colord;
+export declare function hexToGLrgb(hex: string): [number, number, number];
 export {};