@jbrowse/core 5.0.0-beta.4 → 5.0.0-beta.7

package/esm/util/featureTransforms.js

@@ -0,0 +1,342 @@
+import { stringToJexlExpression } from './jexlStrings.js';
+import SimpleFeature, { buildJexlContext } from './simpleFeature.js';
+export const DEFAULT_BIN_AS = ['start', 'end'];
+export const DEFAULT_COVERAGE_AS = 'coverage';
+export const DEFAULT_STACK_AS = 'row';
+export const DEFAULT_STACK_FIELDS = ['start', 'end'];
+/**
+ * A feature with fields written over another's: what `formula` and `bin`
+ * produce, without copying the base feature's data per step.
+ */
+class DerivedFeature {
+    base;
+    fields;
+    constructor(base, fields) {
+        this.base = base;
+        this.fields = fields;
+    }
+    get = ((name) => name in this.fields
+        ? this.fields[name]
+        : this.base.get(name));
+    id() {
+        return this.base.id();
+    }
+    parent() {
+        return this.base.parent?.();
+    }
+    children() {
+        return this.base.children?.();
+    }
+    toJSON() {
+        return { ...this.base.toJSON(), ...this.fields };
+    }
+}
+/**
+ * A feature a step made from nothing: what `aggregate` and `coverage` answer,
+ * carrying only the fields they wrote. `SimpleFeature`'s constructor costs
+ * more than the encode of what it builds, and nothing here needs its checks.
+ */
+class MadeFeature {
+    data;
+    tag;
+    constructor(data, tag) {
+        this.data = data;
+        this.tag = tag;
+    }
+    get = ((name) => name === 'uniqueId' ? this.id() : this.data[name]);
+    id() {
+        const { refName, start, end } = this.data;
+        return `${String(refName)}:${String(start)}-${String(end)}${this.tag}`;
+    }
+    toJSON() {
+        return { ...this.data, uniqueId: this.id() };
+    }
+}
+function expression(expr, jexl) {
+    if (!jexl) {
+        throw new Error(`a jexl transform needs a jexl instance (${expr})`);
+    }
+    return stringToJexlExpression(expr, jexl);
+}
+function filter(features, expr, jexl) {
+    const compiled = expression(expr, jexl);
+    return features.filter(f => compiled.eval(buildJexlContext({ feature: f })));
+}
+function formula(features, expr, as, jexl) {
+    const compiled = expression(expr, jexl);
+    return features.map(f => new DerivedFeature(f, {
+        [as]: compiled.eval(buildJexlContext({ feature: f })),
+    }));
+}
+/**
+ * One element of a fanned-out array field, reading its own fields over the
+ * feature it came from: an exon that still knows its gene's name and strand.
+ */
+class FlattenedFeature {
+    container;
+    item;
+    constructor(container, item) {
+        this.container = container;
+        this.item = item;
+    }
+    get = ((name) => {
+        const v = this.item.get(name);
+        return v === undefined ? this.container.get(name) : v;
+    });
+    id() {
+        return this.item.id();
+    }
+    parent() {
+        return this.container;
+    }
+    children() {
+        return this.item.children?.();
+    }
+    toJSON() {
+        return { ...this.container.toJSON(), ...this.item.toJSON() };
+    }
+}
+function flatten(features, step) {
+    const { field = 'subfeatures', index, keepEmpty } = step;
+    const out = [];
+    for (const f of features) {
+        const items = f.get(field);
+        if (!Array.isArray(items) || items.length === 0) {
+            if (keepEmpty) {
+                out.push(f);
+            }
+            continue;
+        }
+        for (const [i, item] of items.entries()) {
+            const child = typeof item?.get === 'function'
+                ? item
+                : new SimpleFeature({
+                    ...item,
+                    uniqueId: `${f.id()}#${i}`,
+                });
+            const flat = new FlattenedFeature(f, child);
+            out.push(index ? new DerivedFeature(flat, { [index]: i }) : flat);
+        }
+    }
+    return out;
+}
+function bin(features, step) {
+    const { field = 'start', step: size } = step;
+    if (!(size > 0)) {
+        throw new Error(`a bin step needs a positive size (${size})`);
+    }
+    const [asStart, asEnd] = step.as ?? DEFAULT_BIN_AS;
+    return features.map(f => {
+        const v = Number(f.get(field));
+        const start = Math.floor(v / size) * size;
+        return new DerivedFeature(f, { [asStart]: start, [asEnd]: start + size });
+    });
+}
+export function aggregateFieldName({ op, field, as }) {
+    return as ?? (op === 'count' || field === undefined ? op : `${op}_${field}`);
+}
+function groupMembers(features, groupby) {
+    if (groupby.length === 0) {
+        return features.length > 0 ? [[...features]] : [];
+    }
+    const last = groupby.length - 1;
+    const root = new Map();
+    const groups = [];
+    for (const f of features) {
+        let node = root;
+        for (let i = 0; i < last; i++) {
+            const v = f.get(groupby[i]);
+            let next = node.get(v);
+            if (!next) {
+                next = new Map();
+                node.set(v, next);
+            }
+            node = next;
+        }
+        const v = f.get(groupby[last]);
+        let members = node.get(v);
+        if (!members) {
+            members = [];
+            node.set(v, members);
+            groups.push(members);
+        }
+        members.push(f);
+    }
+    return groups;
+}
+function aggregate(features, step) {
+    const { groupby = [], ops } = step;
+    const out = [];
+    let serial = 0;
+    for (const members of groupMembers(features, groupby)) {
+        const first = members[0];
+        const refName = first.get('refName');
+        let start = Infinity;
+        let end = -Infinity;
+        for (const m of members) {
+            start = Math.min(start, m.get('start'));
+            end = Math.max(end, m.get('end'));
+        }
+        const data = {};
+        for (const field of groupby) {
+            data[field] = first.get(field);
+        }
+        for (const agg of ops) {
+            data[aggregateFieldName(agg)] = aggregateValue(members, agg);
+        }
+        out.push(new MadeFeature({ ...data, refName, start, end }, `#${serial++}`));
+    }
+    return out;
+}
+function aggregateValue(members, { op, field }) {
+    if (op === 'count') {
+        return members.length;
+    }
+    if (field === undefined) {
+        throw new Error(`an aggregate ${op} needs a field`);
+    }
+    let sum = 0;
+    let n = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const m of members) {
+        const v = Number(m.get(field));
+        if (!Number.isFinite(v)) {
+            continue;
+        }
+        sum += v;
+        n++;
+        min = Math.min(min, v);
+        max = Math.max(max, v);
+    }
+    switch (op) {
+        case 'sum': {
+            return sum;
+        }
+        case 'mean': {
+            return n > 0 ? sum / n : undefined;
+        }
+        case 'min': {
+            return n > 0 ? min : undefined;
+        }
+        case 'max': {
+            return n > 0 ? max : undefined;
+        }
+    }
+}
+/**
+ * The lowest row each feature fits on, greedy first fit in start order: the
+ * layout a pileup is, as a step in front of the encoder rather than a packer
+ * behind it. `rowEnds[r]` is where row `r` is free again, so the scan is over
+ * rows rather than over features.
+ */
+function stack(features, step) {
+    const as = step.as ?? DEFAULT_STACK_AS;
+    const [startField, endField] = step.fields ?? DEFAULT_STACK_FIELDS;
+    const padding = step.padding ?? 0;
+    const out = [];
+    for (const members of groupMembers(features, step.groupby ?? [])) {
+        members.sort((a, b) => Number(a.get(startField)) - Number(b.get(startField)));
+        const rowEnds = [];
+        for (const f of members) {
+            const start = Number(f.get(startField));
+            const end = Number(f.get(endField));
+            let row = 0;
+            while (row < rowEnds.length && rowEnds[row] > start) {
+                row++;
+            }
+            rowEnds[row] = (end > start ? end : start) + padding;
+            out.push(new DerivedFeature(f, { [as]: row }));
+        }
+    }
+    return out;
+}
+/**
+ * Piecewise-constant depth over the features' spans: one feature per run of
+ * equal depth, where the depth is not zero. A sweep over the sorted edges,
+ * so the input need not be sorted.
+ */
+function coverage(features, step) {
+    const as = step.as ?? DEFAULT_COVERAGE_AS;
+    const n = features.length;
+    if (n === 0) {
+        return [];
+    }
+    const starts = new Float64Array(n);
+    const ends = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        starts[i] = features[i].get('start');
+        ends[i] = features[i].get('end');
+    }
+    starts.sort();
+    ends.sort();
+    const refName = features[0].get('refName');
+    const out = [];
+    let depth = 0;
+    let runStart = starts[0];
+    let si = 0;
+    let ei = 0;
+    const emit = (to) => {
+        if (depth > 0 && to > runStart) {
+            out.push(new MadeFeature({ refName, start: runStart, end: to, [as]: depth }, ''));
+        }
+    };
+    while (si < n || ei < n) {
+        const nextStart = si < n ? starts[si] : Infinity;
+        const nextEnd = ei < n ? ends[ei] : Infinity;
+        const at = Math.min(nextStart, nextEnd);
+        emit(at);
+        runStart = at;
+        while (si < n && starts[si] === at) {
+            depth++;
+            si++;
+        }
+        while (ei < n && ends[ei] === at) {
+            depth--;
+            ei++;
+        }
+    }
+    return out;
+}
+/**
+ * #api
+ * Run the transform steps over a feature list, in order, in the worker. The
+ * list a step answers is what the next one reads, and the last one is what
+ * the encoder walks.
+ */
+export function runTransforms(features, steps, jexl) {
+    let current = features;
+    for (const step of steps) {
+        switch (step.type) {
+            case 'filter': {
+                current = filter(current, step.expr, jexl);
+                break;
+            }
+            case 'formula': {
+                current = formula(current, step.expr, step.as, jexl);
+                break;
+            }
+            case 'flatten': {
+                current = flatten(current, step);
+                break;
+            }
+            case 'bin': {
+                current = bin(current, step);
+                break;
+            }
+            case 'aggregate': {
+                current = aggregate(current, step);
+                break;
+            }
+            case 'coverage': {
+                current = coverage(current, step);
+                break;
+            }
+            case 'stack': {
+                current = stack(current, step);
+                break;
+            }
+        }
+    }
+    return current;
+}

package/esm/util/freezeDeep.d.ts

@@ -1,20 +1,18 @@
 /**
  * Freeze `value` and everything reachable from it, in place, and return it.
  *
- * For a value handed to consumers **by reference on purpose**: a config slot's
- * `promotedBase` (the one literal every track sitting at base resolves to) and a
- * stored user preference (a promoted display-type default, read by every
- * following display). Sharing the reference is load-bearing in both cases —
- * `===` stability is what lets a display's cached MobX computed re-resolve
+ * For a value handed to consumers **by reference on purpose**: a stored user
+ * preference, read by everything that follows it. Sharing the reference is
+ * load-bearing — `===` stability is what lets a cached MobX computed re-derive
  * without waking anything downstream — so handing out a defensive copy per read
  * would trade a silent hazard for a real re-render on every read. Freezing keeps
  * the identity and makes "nothing mutates this" throw rather than quietly
- * rewriting a value every other track is reading.
+ * rewriting a value every other reader sees.
  *
- * Both callers freeze once, at schema build or at the store write, over a value
- * that has to survive `postMessage` anyway — so the recursion is over small JSON
- * and costs nothing per read. Cyclic input terminates: each object is frozen
- * before its children are visited.
+ * The caller freezes once, at the store write, over a value that has to survive
+ * `postMessage` anyway — so the recursion is over small JSON and costs nothing
+ * per read. Cyclic input terminates: each object is frozen before its children
+ * are visited.
  *
  * **Unconditional, deliberately unlike MST's own `deepFreeze`** (whose body this
  * otherwise mirrors), which is gated on `devMode()`. MST gates because it freezes

package/esm/util/freezeDeep.js

@@ -6,20 +6,18 @@ function isObjectLike(value) {
 /**
  * Freeze `value` and everything reachable from it, in place, and return it.
  *
- * For a value handed to consumers **by reference on purpose**: a config slot's
- * `promotedBase` (the one literal every track sitting at base resolves to) and a
- * stored user preference (a promoted display-type default, read by every
- * following display). Sharing the reference is load-bearing in both cases —
- * `===` stability is what lets a display's cached MobX computed re-resolve
+ * For a value handed to consumers **by reference on purpose**: a stored user
+ * preference, read by everything that follows it. Sharing the reference is
+ * load-bearing — `===` stability is what lets a cached MobX computed re-derive
  * without waking anything downstream — so handing out a defensive copy per read
  * would trade a silent hazard for a real re-render on every read. Freezing keeps
  * the identity and makes "nothing mutates this" throw rather than quietly
- * rewriting a value every other track is reading.
+ * rewriting a value every other reader sees.
  *
- * Both callers freeze once, at schema build or at the store write, over a value
- * that has to survive `postMessage` anyway — so the recursion is over small JSON
- * and costs nothing per read. Cyclic input terminates: each object is frozen
- * before its children are visited.
+ * The caller freezes once, at the store write, over a value that has to survive
+ * `postMessage` anyway — so the recursion is over small JSON and costs nothing
+ * per read. Cyclic input terminates: each object is frozen before its children
+ * are visited.
  *
  * **Unconditional, deliberately unlike MST's own `deepFreeze`** (whose body this
  * otherwise mirrors), which is gated on `devMode()`. MST gates because it freezes

package/esm/util/glyphNames.d.ts

@@ -0,0 +1,8 @@
+import type { GlyphName } from './markEncodingTypes.ts';
+/**
+ * #api
+ * The `point` shape's glyph code for each name an encoding can say.
+ */
+export declare const GLYPH_CODES: Record<GlyphName, number>;
+/** The glyph names in range order: what an unlisted `range` hands out. */
+export declare const GLYPH_NAMES: GlyphName[];

package/esm/util/glyphNames.js

@@ -0,0 +1,12 @@
+import { GLYPH_DIAMOND, GLYPH_DISC, GLYPH_TRIANGLE, } from '@jbrowse/render-core/shaders/pointMarkConsts';
+/**
+ * #api
+ * The `point` shape's glyph code for each name an encoding can say.
+ */
+export const GLYPH_CODES = {
+    disc: GLYPH_DISC,
+    triangle: GLYPH_TRIANGLE,
+    diamond: GLYPH_DIAMOND,
+};
+/** The glyph names in range order: what an unlisted `range` hands out. */
+export const GLYPH_NAMES = Object.keys(GLYPH_CODES);

package/esm/util/index.d.ts

@@ -37,7 +37,6 @@ export { indexedDBAvailable, isElectron, isNode, rIC } from './environment.ts';
 export { isWebWorker } from './isWebWorker.ts';
 export { sessionStorageAvailable, sessionStorageGetItem, sessionStorageRemoveItem, sessionStorageSetItem, } from './sessionStorage.ts';
 export { isObject } from './objectUtils.ts';
-export { openPromotableDisplays } from './openDisplays.ts';
 export { type ReorderDirection, applyOrderWithin, reorder, reorderWithin, } from './reorder.ts';
 export { getStr } from './getStr.ts';
 export { downloadPhase, getLocationUri, resolveUri } from './getLocationUri.ts';

package/esm/util/index.js

@@ -44,7 +44,6 @@ export { indexedDBAvailable, isElectron, isNode, rIC } from './environment.js';
 export { isWebWorker } from './isWebWorker.js';
 export { sessionStorageAvailable, sessionStorageGetItem, sessionStorageRemoveItem, sessionStorageSetItem, } from './sessionStorage.js';
 export { isObject } from './objectUtils.js';
-export { openPromotableDisplays } from './openDisplays.js';
 export { applyOrderWithin, reorder, reorderWithin, } from './reorder.js';
 export { getStr } from './getStr.js';
 export { downloadPhase, getLocationUri, resolveUri } from './getLocationUri.js';

package/esm/util/markEncoding.d.ts

@@ -0,0 +1,76 @@
+import type { JexlInstance } from './jexlStrings.ts';
+import type { ColorEncoding, Encoded, EncodedChannels, FieldRef, GlyphEncoding, LaneName, ValueEncoding } from './markEncodingTypes.ts';
+import type { ProgressReporter } from './progress.ts';
+import type { Feature } from './simpleFeature.ts';
+export type { AggregateOp, AggregateStep, BinStep, CategoricalRef, ColorEncoding, CoverageStep, ColorScaleTable, CoreEncodeFeaturesArgs, Encoded, EncodedChannels, EncodedFeaturesResult, FieldRef, FilterStep, FormulaStep, GlyphEncoding, GlyphName, GlyphScaleTable, LaneName, LayerRequest, MarkEncoding, RampRef, ScaleTable, TransformStep, ValueEncoding, } from './markEncodingTypes.ts';
+export declare const DEFAULT_MARK_COLOR = "#0068d1";
+/**
+ * #api
+ * The key row a feature with nothing in a categorical field lands on, so the
+ * legend says why a mark is grey, or a disc, rather than listing a blank
+ * value.
+ */
+export declare const NO_VALUE_LABEL = "(no value)";
+/**
+ * #api
+ * A channel read per feature: the compiled form of a {@link FieldRef}, and
+ * what a display's own worker method hands the encoder for a channel no
+ * field name can say — a join against a second adapter, a lookup table, a
+ * rule over two fields.
+ */
+export type ChannelReader<T = unknown> = (feature: Feature) => T;
+/**
+ * #api
+ * What `encodeFeatures` takes: a {@link MarkEncoding}, any channel of which
+ * may be a {@link ChannelReader} in place of its declared form. The declared
+ * form is what crosses the wire; a reader is built in the worker.
+ */
+export interface MarkEncodingInput {
+    x?: FieldRef | ChannelReader;
+    x2?: FieldRef | ChannelReader;
+    y?: ValueEncoding | ChannelReader;
+    row?: FieldRef | ChannelReader;
+    color?: ColorEncoding | ChannelReader<number>;
+    glyph?: GlyphEncoding | ChannelReader<number>;
+}
+/**
+ * #api
+ * What surrounds an encode: the jexl instance a `jexl:` channel compiles
+ * against — a caller whose channels are all readers or field names passes
+ * none — and a progress reporter.
+ */
+export interface EncodeContext {
+    jexl?: JexlInstance;
+    report?: ProgressReporter;
+}
+/**
+ * #api
+ * The field a `y` declaration reads, whichever of its two forms it is
+ * written in.
+ */
+export declare function valueField(y: ValueEncoding): FieldRef;
+/**
+ * #api
+ * Evaluate one encoding over a feature list into dense channel arrays for
+ * the lanes named, the scale table each scaled channel came from, the `y`
+ * extremes and — when `index` is among the lanes — a hit index.
+ *
+ * A feature whose `x`, `x2` or (declared and asked-for) `y` is not finite is
+ * skipped and counted in `skipped`, so every array stays index-aligned with
+ * the Flatbush. Pure: the RPC around it owns the adapter, the filters and the
+ * transferables.
+ */
+export declare function encodeFeatures<L extends LaneName>(features: readonly Feature[], encoding: MarkEncodingInput, lanes: readonly L[], ctx?: EncodeContext): Encoded<L>;
+/**
+ * #api
+ * A CSS colour or `jexl:` colour expression as a per-feature packed ABGR —
+ * the unscaled arm of {@link ColorEncoding}, on its own for a display that
+ * carries a plain `color` slot.
+ */
+export declare function colorEvaluator(color: string, jexl: JexlInstance | undefined): (feature: Feature) => number;
+/**
+ * #api
+ * The buffers an {@link EncodedChannels} owns, for `rpcResult`'s transfer
+ * list.
+ */
+export declare function encodedChannelTransferables(c: EncodedChannels): ArrayBufferLike[];