@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/featureTable.d.ts

@@ -0,0 +1,224 @@
+import type { Feature, SimpleFeatureSerialized } from './simpleFeature.ts';
+/**
+ * #api
+ * A typed lane a step wrote, one number per row.
+ */
+export type NumberLane = Float64Array | Float32Array | Uint32Array | Int32Array | Uint16Array | Int16Array | Uint8Array | Int8Array;
+/**
+ * #api
+ * Codes into a list of labels, one per row.
+ */
+export type CodeLane = Uint8Array | Uint16Array | Uint32Array;
+/**
+ * #api
+ * Text held as bytes, one per character: row `i`'s is `length[i]` bytes of
+ * `bytes` from `offset[i]`, so many rows share one buffer, as an adapter's
+ * arena holds them.
+ */
+export interface TextColumn {
+    kind: 'text';
+    bytes: Uint8Array;
+    offset: Uint32Array;
+    length: Uint32Array;
+    at: Uint32Array | undefined;
+}
+/**
+ * #api
+ * A list of rows per row: row `i`'s entries are the rows of `entries` from
+ * `start[i]` up to `start[i + 1]`, and `keys`, where the list is a record
+ * keyed by name, the name of each entry.
+ */
+export interface ListColumn {
+    kind: 'list';
+    start: Uint32Array;
+    entries: ColumnTable;
+    keys: Column | undefined;
+    at: Uint32Array | undefined;
+}
+/**
+ * #api
+ * A field's values over a table's rows, resolved once per step so the loop
+ * reading it is chosen before the loop runs: a lane a step wrote, codes into
+ * labels, a field read off the parser's own features, text or lists an
+ * adapter holds typed, or a value a step computes per row. `at` is the row
+ * each of the table's rows reads, where the lane or the features belong to a
+ * table this one stands on.
+ */
+export type Column = {
+    kind: 'number';
+    values: NumberLane;
+    at: Uint32Array | undefined;
+    /** A `NaN` in the lane is a row holding no value, which `get` answers as `undefined`. */
+    nanIsAbsent?: boolean;
+} | {
+    kind: 'category';
+    codes: CodeLane;
+    labels: readonly string[];
+    at: Uint32Array | undefined;
+} | {
+    kind: 'feature';
+    features: readonly Feature[];
+    field: string;
+    at: Uint32Array | undefined;
+} | TextColumn | ListColumn | {
+    kind: 'value';
+    read: (row: number) => unknown;
+} | {
+    kind: 'none';
+};
+/**
+ * #api
+ * The rows one step of a mark's declaration hands the next: a column per
+ * field and a view of one row as a `Feature`, for a `jexl:` expression, a
+ * channel reader and the hover.
+ */
+export interface FeatureTable {
+    readonly length: number;
+    column(field: string): Column;
+    row(i: number): Feature;
+}
+export declare const NO_COLUMN: Column;
+/**
+ * #api
+ * A column's value at a row, whatever its kind: for a loop that reads few rows.
+ */
+export declare function valueAt(column: Column, i: number): unknown;
+/**
+ * #api
+ * A reader of a column's values by row, its kind resolved here once. A
+ * `number` lane with no index reads straight off the lane.
+ */
+export declare function readerOf(column: Column): (i: number) => unknown;
+/**
+ * #api
+ * {@link readerOf} as the number a quantitative channel or step reads,
+ * `NaN` where a row holds none, by `numericValue`'s rules.
+ */
+export declare function numberReaderOf(column: Column): (i: number) => number;
+/**
+ * A column of the table `at` indexes into, read from this one's rows: the
+ * index composed into a lane's, or into a reader for a `value` column.
+ */
+export declare function throughIndex(column: Column, at: Uint32Array): Column;
+/** A table over the features an adapter answered, a field read off each. */
+export declare class SourceTable implements FeatureTable {
+    readonly length: number;
+    readonly features: readonly Feature[];
+    constructor(features: readonly Feature[]);
+    column(field: string): Column;
+    row(i: number): Feature;
+}
+/**
+ * #api
+ * A table an adapter answers from the typed arrays it already holds, where
+ * `getFeaturesArray` would make an object per row: a column per field, and
+ * each row's id. A row's hover JSON is every field it holds.
+ */
+export declare class ColumnTable implements MadeRows {
+    readonly length: number;
+    private readonly columns;
+    private readonly ids;
+    constructor(length: number, columns: ReadonlyMap<string, Column>, id: (i: number) => string);
+    column(field: string): Column;
+    /** The fields the row holds, as a plain record. */
+    record(i: number): Record<string, unknown>;
+    id(i: number): string;
+    json(i: number): SimpleFeatureSerialized;
+    parentOfRow(): undefined;
+    row(i: number): Feature;
+}
+/**
+ * #api
+ * A table over a feature list, or the table itself.
+ */
+export declare function asTable(input: readonly Feature[] | FeatureTable): FeatureTable;
+/**
+ * A table whose rows stand on another's: each row names the parent row it came
+ * from, and a field it does not carry reads through to the parent's. A
+ * subclass answers its own fields in `own`, `undefined` for one it does not
+ * carry, and its own id and JSON.
+ */
+export declare abstract class DerivedTable implements MadeRows {
+    readonly length: number;
+    readonly parent: FeatureTable;
+    readonly parentRow: Uint32Array | undefined;
+    private readonly resolved;
+    constructor(parent: FeatureTable, parentRow: Uint32Array | undefined, length?: number);
+    protected abstract own(field: string): Column | undefined;
+    /**
+     * Whether a row was made from its parent row, as a flattened entry or a run
+     * is, so the parent row is its `parent()`; otherwise the row is its parent
+     * row with fields beside it, and its `parent()` is that row's.
+     */
+    get madeFrom(): boolean;
+    column(field: string): Column;
+    protected inherited(field: string): Column;
+    parentOf(i: number): number;
+    id(i: number): string;
+    /** The row's fields over its parent's, as the hover shows them. */
+    json(i: number): SimpleFeatureSerialized;
+    parentOfRow(i: number): Feature | undefined;
+    row(i: number): Feature;
+}
+/**
+ * #api
+ * A table whose rows a step made, which answers each row's identity, its
+ * hover JSON and the feature it hangs from.
+ */
+export interface MadeRows extends FeatureTable {
+    id(i: number): string;
+    json(i: number): SimpleFeatureSerialized;
+    parentOfRow(i: number): Feature | undefined;
+}
+/**
+ * One row of a table a step made, as a `Feature`: what a `jexl:` expression, a
+ * channel reader and the hover read.
+ */
+export declare class TableRow implements Feature {
+    private readonly table;
+    private readonly i;
+    constructor(table: MadeRows, i: number);
+    get(name: 'refName'): string;
+    get(name: 'name' | 'type' | 'id' | 'source'): string | undefined;
+    get(name: 'start' | 'end'): number;
+    get(name: 'phase'): 0 | 1 | 2 | undefined;
+    get(name: 'strand'): -1 | 0 | 1 | undefined;
+    get(name: 'score'): number | undefined;
+    get(name: 'subfeatures'): Feature[] | undefined;
+    get(name: string): unknown;
+    id(): string;
+    parent(): Feature | undefined;
+    toJSON(): SimpleFeatureSerialized;
+}
+/**
+ * The parent's own rows, kept or reordered: what a `filter` and the facet's
+ * section order answer. Every field and the row's identity read through.
+ */
+export declare class SelectTable extends DerivedTable {
+    protected own(): undefined;
+    row(i: number): Feature;
+}
+/**
+ * The parent's rows, each with fields a step wrote beside the ones it
+ * carries: a `formula`'s value, a `bin`'s edges. A written field shadows the
+ * parent's of the same name.
+ */
+export declare class WithTable extends DerivedTable {
+    private readonly written;
+    constructor(parent: FeatureTable, written: ReadonlyMap<string, Column>, parentRow?: Uint32Array);
+    protected own(field: string): Column | undefined;
+    json(i: number): SimpleFeatureSerialized;
+}
+/**
+ * #api
+ * The table's rows `rows` names, in that order: over an adapter's features, a
+ * source table over those features again, so every field still reads straight
+ * off them; over rows a step made, a table standing on them.
+ */
+export declare function selectRows(table: FeatureTable, rows: Uint32Array): FeatureTable;
+/**
+ * #api
+ * The table's rows with `written` beside them, in the order `rows` names
+ * where it names one.
+ */
+export declare function withColumns(table: FeatureTable, written: ReadonlyMap<string, Column>, rows?: Uint32Array): FeatureTable;

package/esm/util/featureTable.js

@@ -0,0 +1,366 @@
+import { numericValue } from './numericValue.js';
+export const NO_COLUMN = { kind: 'none' };
+/**
+ * #api
+ * A column's value at a row, whatever its kind: for a loop that reads few rows.
+ */
+export function valueAt(column, i) {
+    switch (column.kind) {
+        case 'number': {
+            const v = column.values[column.at ? column.at[i] : i];
+            return column.nanIsAbsent && Number.isNaN(v) ? undefined : v;
+        }
+        case 'category': {
+            return column.labels[column.codes[column.at ? column.at[i] : i]];
+        }
+        case 'feature': {
+            return column.features[column.at ? column.at[i] : i].get(column.field);
+        }
+        case 'text': {
+            return textOfRow(column, column.at ? column.at[i] : i);
+        }
+        case 'list': {
+            return listOfRow(column, column.at ? column.at[i] : i);
+        }
+        case 'value': {
+            return column.read(i);
+        }
+        case 'none': {
+            return undefined;
+        }
+    }
+}
+const decoder = new TextDecoder();
+function textOfRow({ bytes, offset, length }, r) {
+    const from = offset[r];
+    return decoder.decode(bytes.subarray(from, from + length[r]));
+}
+// A keyed list is the record its entries are filed in by name, each entry a
+// plain record; any other is its entries as features.
+function listOfRow({ start, entries, keys }, r) {
+    const from = start[r];
+    const to = start[r + 1];
+    if (keys) {
+        const out = {};
+        for (let j = from; j < to; j++) {
+            out[String(valueAt(keys, j))] = entries.record(j);
+        }
+        return out;
+    }
+    const out = [];
+    for (let j = from; j < to; j++) {
+        out.push(entries.row(j));
+    }
+    return out;
+}
+/**
+ * #api
+ * A reader of a column's values by row, its kind resolved here once. A
+ * `number` lane with no index reads straight off the lane.
+ */
+export function readerOf(column) {
+    switch (column.kind) {
+        case 'number': {
+            const { values, at } = column;
+            if (column.nanIsAbsent) {
+                return i => {
+                    const v = values[at ? at[i] : i];
+                    return Number.isNaN(v) ? undefined : v;
+                };
+            }
+            return at ? i => values[at[i]] : i => values[i];
+        }
+        case 'category': {
+            const { codes, labels, at } = column;
+            return at ? i => labels[codes[at[i]]] : i => labels[codes[i]];
+        }
+        case 'feature': {
+            const { features, field, at } = column;
+            return at
+                ? i => features[at[i]].get(field)
+                : i => features[i].get(field);
+        }
+        case 'text': {
+            const { at } = column;
+            return at ? i => textOfRow(column, at[i]) : i => textOfRow(column, i);
+        }
+        case 'list': {
+            const { at } = column;
+            return at ? i => listOfRow(column, at[i]) : i => listOfRow(column, i);
+        }
+        case 'value': {
+            return column.read;
+        }
+        case 'none': {
+            return () => undefined;
+        }
+    }
+}
+/**
+ * #api
+ * {@link readerOf} as the number a quantitative channel or step reads,
+ * `NaN` where a row holds none, by `numericValue`'s rules.
+ */
+export function numberReaderOf(column) {
+    switch (column.kind) {
+        case 'number': {
+            const { values, at } = column;
+            return at ? i => values[at[i]] : i => values[i];
+        }
+        case 'none': {
+            return () => Number.NaN;
+        }
+        case 'feature': {
+            const { features, field, at } = column;
+            return at
+                ? i => numericValue(features[at[i]].get(field))
+                : i => numericValue(features[i].get(field));
+        }
+        case 'category':
+        case 'text':
+        case 'list':
+        case 'value': {
+            const read = readerOf(column);
+            return i => numericValue(read(i));
+        }
+    }
+}
+/**
+ * A column of the table `at` indexes into, read from this one's rows: the
+ * index composed into a lane's, or into a reader for a `value` column.
+ */
+export function throughIndex(column, at) {
+    switch (column.kind) {
+        case 'number':
+        case 'category':
+        case 'feature':
+        case 'text':
+        case 'list': {
+            const inner = column.at;
+            if (!inner) {
+                return { ...column, at };
+            }
+            const composed = new Uint32Array(at.length);
+            for (let i = 0; i < at.length; i++) {
+                composed[i] = inner[at[i]];
+            }
+            return { ...column, at: composed };
+        }
+        case 'value': {
+            const { read } = column;
+            return { kind: 'value', read: i => read(at[i]) };
+        }
+        case 'none': {
+            return column;
+        }
+    }
+}
+/** A table over the features an adapter answered, a field read off each. */
+export class SourceTable {
+    length;
+    features;
+    constructor(features) {
+        this.features = features;
+        this.length = features.length;
+    }
+    column(field) {
+        return { kind: 'feature', features: this.features, field, at: undefined };
+    }
+    row(i) {
+        return this.features[i];
+    }
+}
+/**
+ * #api
+ * A table an adapter answers from the typed arrays it already holds, where
+ * `getFeaturesArray` would make an object per row: a column per field, and
+ * each row's id. A row's hover JSON is every field it holds.
+ */
+export class ColumnTable {
+    length;
+    columns;
+    ids;
+    constructor(length, columns, id) {
+        this.length = length;
+        this.columns = columns;
+        this.ids = id;
+    }
+    column(field) {
+        return this.columns.get(field) ?? NO_COLUMN;
+    }
+    /** The fields the row holds, as a plain record. */
+    record(i) {
+        const out = {};
+        for (const [field, column] of this.columns) {
+            const v = valueAt(column, i);
+            if (v !== undefined) {
+                out[field] = v;
+            }
+        }
+        return out;
+    }
+    id(i) {
+        return this.ids(i);
+    }
+    json(i) {
+        return {
+            ...this.record(i),
+            uniqueId: this.id(i),
+        };
+    }
+    parentOfRow() {
+        return undefined;
+    }
+    row(i) {
+        return new TableRow(this, i);
+    }
+}
+/**
+ * #api
+ * A table over a feature list, or the table itself.
+ */
+export function asTable(input) {
+    return isTable(input) ? input : new SourceTable(input);
+}
+function isTable(input) {
+    return !Array.isArray(input);
+}
+/**
+ * A table whose rows stand on another's: each row names the parent row it came
+ * from, and a field it does not carry reads through to the parent's. A
+ * subclass answers its own fields in `own`, `undefined` for one it does not
+ * carry, and its own id and JSON.
+ */
+export class DerivedTable {
+    length;
+    parent;
+    parentRow;
+    resolved = new Map();
+    constructor(parent, parentRow, length = parentRow ? parentRow.length : parent.length) {
+        this.parent = parent;
+        this.parentRow = parentRow;
+        this.length = length;
+    }
+    /**
+     * Whether a row was made from its parent row, as a flattened entry or a run
+     * is, so the parent row is its `parent()`; otherwise the row is its parent
+     * row with fields beside it, and its `parent()` is that row's.
+     */
+    get madeFrom() {
+        return false;
+    }
+    column(field) {
+        let column = this.resolved.get(field);
+        if (column === undefined) {
+            column = this.own(field) ?? this.inherited(field);
+            this.resolved.set(field, column);
+        }
+        return column;
+    }
+    inherited(field) {
+        const column = this.parent.column(field);
+        return this.parentRow ? throughIndex(column, this.parentRow) : column;
+    }
+    parentOf(i) {
+        return this.parentRow ? this.parentRow[i] : i;
+    }
+    id(i) {
+        return this.parent.row(this.parentOf(i)).id();
+    }
+    /** The row's fields over its parent's, as the hover shows them. */
+    json(i) {
+        return this.parent.row(this.parentOf(i)).toJSON();
+    }
+    parentOfRow(i) {
+        const up = this.parent.row(this.parentOf(i));
+        return this.madeFrom ? up : up.parent?.();
+    }
+    row(i) {
+        return new TableRow(this, i);
+    }
+}
+/**
+ * One row of a table a step made, as a `Feature`: what a `jexl:` expression, a
+ * channel reader and the hover read.
+ */
+export class TableRow {
+    table;
+    i;
+    constructor(table, i) {
+        this.table = table;
+        this.i = i;
+    }
+    get(name) {
+        return valueAt(this.table.column(name), this.i);
+    }
+    id() {
+        return this.table.id(this.i);
+    }
+    parent() {
+        return this.table.parentOfRow(this.i);
+    }
+    toJSON() {
+        return this.table.json(this.i);
+    }
+}
+/**
+ * The parent's own rows, kept or reordered: what a `filter` and the facet's
+ * section order answer. Every field and the row's identity read through.
+ */
+export class SelectTable extends DerivedTable {
+    own() {
+        return undefined;
+    }
+    row(i) {
+        return this.parent.row(this.parentOf(i));
+    }
+}
+/**
+ * The parent's rows, each with fields a step wrote beside the ones it
+ * carries: a `formula`'s value, a `bin`'s edges. A written field shadows the
+ * parent's of the same name.
+ */
+export class WithTable extends DerivedTable {
+    written;
+    constructor(parent, written, parentRow) {
+        super(parent, parentRow);
+        this.written = written;
+    }
+    own(field) {
+        return this.written.get(field);
+    }
+    json(i) {
+        const out = { ...super.json(i) };
+        for (const [field, column] of this.written) {
+            out[field] = valueAt(column, i);
+        }
+        return out;
+    }
+}
+/**
+ * #api
+ * The table's rows `rows` names, in that order: over an adapter's features, a
+ * source table over those features again, so every field still reads straight
+ * off them; over rows a step made, a table standing on them.
+ */
+export function selectRows(table, rows) {
+    if (table instanceof SourceTable) {
+        const { features } = table;
+        const listed = new Array(rows.length);
+        for (let k = 0; k < rows.length; k++) {
+            listed[k] = features[rows[k]];
+        }
+        return new SourceTable(listed);
+    }
+    return new SelectTable(table, rows);
+}
+/**
+ * #api
+ * The table's rows with `written` beside them, in the order `rows` names
+ * where it names one.
+ */
+export function withColumns(table, written, rows) {
+    return rows && table instanceof SourceTable
+        ? new WithTable(selectRows(table, rows), written)
+        : new WithTable(table, written, rows);
+}

package/esm/util/featureTransforms.d.ts

@@ -0,0 +1,80 @@
+import type { FeatureTable } from './featureTable.ts';
+import type { JexlInstance } from './jexlStrings.ts';
+import type { FacetSection, FacetSpec, FieldRef, TransformStep } from './markEncodingTypes.ts';
+import type { Feature } from './simpleFeature.ts';
+export { BIN_OVERLAP_FIELD, DEFAULT_BIN_AS } from './stepTables.ts';
+export declare const DEFAULT_BIN_FIELD = "start";
+export declare const DEFAULT_FLATTEN_FIELD = "subfeatures";
+export declare const DEFAULT_CELLS_FIELD = "seq";
+export declare const DEFAULT_COVERAGE_AS = "coverage";
+export declare const DEFAULT_PILEUP_AS = "row";
+export declare const DEFAULT_PILEUP_FIELDS: [string, string];
+/**
+ * #api
+ * How a record states its other end, or undefined where it states none: the
+ * `mate` a paired adapter fills (BEDPE, STAR-Fusion), or an `ALT` the breakend
+ * and symbolic-SV readers resolve. The `mate` step admits exactly the features
+ * this names one for, so a caller deciding whether links are the picture a
+ * track wants asks here rather than re-reading the fields.
+ */
+export declare function matedBy(f: Feature): "alt" | "mate" | undefined;
+/**
+ * #api
+ * One layer of a faceted request: its rows in section order, and the stacked
+ * row of each, index for index.
+ */
+export interface FacetedLayer {
+    table: FeatureTable;
+    rows: Uint32Array;
+}
+/**
+ * #api
+ * A faceted request's layers: the rows split on the facet's field, the
+ * facet's own steps and then each layer's run over each section alone, and
+ * the sections stacked — a section's rows start where the one above it ends,
+ * and it is as tall as the tallest layer packed it. Every layer's rows come
+ * back in section order beside their stacked rows, so a faceted display is
+ * the unfaceted one drawn once per section, and a row is handed on as its
+ * steps left it. A layer naming no `row` field stands on each section's first
+ * row, the answer the unfaceted encoder gives it.
+ *
+ * The split is a counting sort into section order rather than a list per
+ * section: every step runs once over the ordered rows, keeping section order,
+ * and one that groups rows groups within a section.
+ */
+export declare function facetLayers(input: readonly Feature[] | FeatureTable, facet: FacetSpec, layers: readonly {
+    transform?: readonly TransformStep[];
+    row?: FieldRef;
+}[], jexl?: JexlInstance): {
+    layers: FacetedLayer[];
+    sections: FacetSection[];
+};
+/**
+ * #api
+ * Run the transform steps over a feature list or a table, in order, in the
+ * worker. The table a step answers is what the next one reads, and the last
+ * one is what the encoder walks.
+ */
+export declare function runTransforms(input: readonly Feature[] | FeatureTable, steps: readonly TransformStep[], jexl?: JexlInstance): FeatureTable;
+/**
+ * #api
+ * A layered request's rows: the shared steps, the facet's split where it
+ * names one, and each layer's own steps, with the row each layer's rows stand
+ * in — the field it names, or under a facet each row's stacked row. The split
+ * comes as early as it can: after the last shared step that must see every
+ * row, so the steps that follow it read the rows already in section order.
+ */
+export declare function layerTables(input: readonly Feature[] | FeatureTable, request: {
+    transform?: readonly TransformStep[];
+    facet?: FacetSpec;
+    layers: readonly {
+        transform?: readonly TransformStep[];
+        row?: FieldRef;
+    }[];
+}, jexl?: JexlInstance): {
+    layers: {
+        table: FeatureTable;
+        row: FieldRef | Uint32Array | undefined;
+    }[];
+    sections: FacetSection[] | undefined;
+};