@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/stepTables.js

@@ -0,0 +1,243 @@
+// The pieces of the transform steps that the fused bin-and-aggregate kernel
+// shares with the steps themselves. Imported by relative path only, so none
+// of it is a package subpath or part of the plugin ABI.
+import { aggregateFieldName } from './aggregateFieldName.js';
+import { NO_COLUMN, TableRow, numberReaderOf, readerOf, valueAt, } from './featureTable.js';
+import { fieldReader, isPlainFieldRef } from './fieldReader.js';
+import { isJexl } from './jexlStrings.js';
+import { numericValue } from './numericValue.js';
+export const DEFAULT_BIN_AS = ['start', 'end'];
+/** What a `bin` over `fields` writes on each piece: the bases of its interval inside its bin. */
+export const BIN_OVERLAP_FIELD = 'overlap';
+// A step reads a name or a dotted path. A plain name reads the table's column;
+// a path walks each row, chosen once per step. A computed field is a `formula`
+// step's to make.
+export function stepReader(table, ref, step) {
+    if (isJexl(ref)) {
+        throw new Error(`${step} field is a name or a dotted path, and a formula step in front computes one (${ref})`);
+    }
+    if (isPlainFieldRef(ref)) {
+        return readerOf(table.column(ref));
+    }
+    const read = fieldReader(ref, undefined);
+    return (i) => read(table.row(i));
+}
+export function stepNumberReader(table, ref, step) {
+    if (isPlainFieldRef(ref) && !isJexl(ref)) {
+        return numberReaderOf(table.column(ref));
+    }
+    const read = stepReader(table, ref, step);
+    return (i) => numericValue(read(i));
+}
+// A list holding one value is that value, as a VCF's ALT and INFO fields
+// arrive, and a longer one is its text: a Map keys a list by identity, which
+// made every row a group of its own. A missing value is one group, whether
+// the field is absent or holds a VCF's `.`.
+export function groupKey(value) {
+    return Array.isArray(value)
+        ? value.length === 1
+            ? (value[0] ?? undefined)
+            : value.join(',')
+        : (value ?? undefined);
+}
+export function binSize({ step }) {
+    if (!(step > 0)) {
+        throw new Error(`a bin step needs a positive size (${step})`);
+    }
+    return step;
+}
+/**
+ * Each row's interval and the bins it overlaps, `first` to `last`, with each
+ * section's lowest and highest bin: `first` NaN where the ends are not
+ * numbers or run backwards, so the row is no piece. A zero-length interval
+ * is its position's bin alone.
+ */
+export function intervalsOf(table, [startField, endField], size, bounds) {
+    const n = table.length;
+    const readStart = stepNumberReader(table, startField, 'a bin');
+    const readEnd = stepNumberReader(table, endField, 'a bin');
+    const start = new Float64Array(n);
+    const end = new Float64Array(n);
+    const firstBin = new Float64Array(n);
+    const lastBin = new Float64Array(n);
+    const sections = bounds.length - 1;
+    const lowBin = new Float64Array(sections).fill(Infinity);
+    const highBin = new Float64Array(sections).fill(-Infinity);
+    let pieces = 0;
+    for (let s = 0; s < sections; s++) {
+        let low = Infinity;
+        let high = -Infinity;
+        for (let i = bounds[s]; i < bounds[s + 1]; i++) {
+            const rowS = readStart(i);
+            const rowE = readEnd(i);
+            start[i] = rowS;
+            end[i] = rowE;
+            if (!(Number.isFinite(rowS) && Number.isFinite(rowE) && rowE >= rowS)) {
+                firstBin[i] = Number.NaN;
+                continue;
+            }
+            const first = Math.floor(rowS / size);
+            // The last bin starting before the end, found by the product the
+            // pieces are cut at.
+            let last = first;
+            while ((last + 1) * size < rowE) {
+                last++;
+            }
+            firstBin[i] = first;
+            lastBin[i] = last;
+            pieces += last - first + 1;
+            if (first < low) {
+                low = first;
+            }
+            if (last > high) {
+                high = last;
+            }
+        }
+        lowBin[s] = low;
+        highBin[s] = high;
+    }
+    return {
+        start,
+        end,
+        first: firstBin,
+        last: lastBin,
+        pieces,
+        lowBin,
+        highBin,
+    };
+}
+/**
+ * Rows a step made from nothing: an `aggregate`'s groups and a `coverage`'s
+ * runs, carrying only the fields they wrote and an id from their span, with
+ * no feature to hang from.
+ */
+export class MadeTable {
+    length;
+    columns;
+    tags;
+    constructor(length, columns, tags) {
+        this.length = length;
+        this.columns = columns;
+        this.tags = tags;
+    }
+    column(field) {
+        return field === 'uniqueId'
+            ? { kind: 'value', read: i => this.id(i) }
+            : (this.columns.get(field) ?? NO_COLUMN);
+    }
+    id(i) {
+        const at = (field) => String(valueAt(this.column(field), i));
+        return `${at('refName')}:${at('start')}-${at('end')}${this.tags(i)}`;
+    }
+    parentOfRow() {
+        return undefined;
+    }
+    row(i) {
+        return new TableRow(this, i);
+    }
+    json(i) {
+        const out = {};
+        for (const [field, column] of this.columns) {
+            out[field] = valueAt(column, i);
+        }
+        out.uniqueId = this.id(i);
+        return out;
+    }
+}
+export function valueColumn(values) {
+    return { kind: 'value', read: i => values[i] };
+}
+// An aggregate's groups as rows, section by section: the groupby fields, the
+// ops, and the reference name and extent each group spans.
+export function madeGroups({ groups, keys, ops, step, refNames, start, end, sectionOf, sections, }) {
+    const columns = new Map();
+    for (const [field, values] of keys) {
+        columns.set(field, valueColumn(values));
+    }
+    for (const [k, agg] of step.ops.entries()) {
+        columns.set(aggregateFieldName(agg), ops[k]);
+    }
+    columns.set('refName', valueColumn(refNames));
+    columns.set('start', { kind: 'number', values: start, at: undefined });
+    columns.set('end', { kind: 'number', values: end, at: undefined });
+    const serial = new Uint32Array(groups);
+    const out = new Uint32Array(sections);
+    let s = 0;
+    for (let g = 0; g < groups; g++) {
+        while (s < sectionOf[g]) {
+            s++;
+            out[s] = g;
+        }
+        serial[g] = g - out[s];
+    }
+    for (s++; s < sections; s++) {
+        out[s] = groups;
+    }
+    return {
+        table: new MadeTable(groups, columns, g => `#${serial[g]}`),
+        bounds: out,
+    };
+}
+// Whether an op reads its `weight`: a weight moves no minimum or maximum.
+export function isWeighted({ op, weight }) {
+    return weight !== undefined && op !== 'min' && op !== 'max';
+}
+/**
+ * One op's running sums per group, which the aggregate and the binned
+ * aggregate both add rows to in row order, so the two answer the same
+ * doubles. An unweighted row adds a weight of 1, which leaves every sum what
+ * it was before weights.
+ */
+export class OpSums {
+    op;
+    readsValue;
+    sum;
+    weight;
+    min;
+    max;
+    constructor({ op, field }, groups) {
+        if (op !== 'count' && field === undefined) {
+            throw new Error(`an aggregate ${op} needs a field`);
+        }
+        this.op = op;
+        this.readsValue = op !== 'count';
+        this.sum = new Float64Array(groups);
+        this.weight = new Float64Array(groups);
+        this.min = new Float64Array(groups).fill(Infinity);
+        this.max = new Float64Array(groups).fill(-Infinity);
+    }
+    add(g, v, w) {
+        if ((this.readsValue && !Number.isFinite(v)) || !Number.isFinite(w)) {
+            return;
+        }
+        this.weight[g] += w;
+        if (this.readsValue) {
+            this.sum[g] += v * w;
+            if (v < this.min[g]) {
+                this.min[g] = v;
+            }
+            if (v > this.max[g]) {
+                this.max[g] = v;
+            }
+        }
+    }
+    column(groups) {
+        const { op } = this;
+        if (op === 'count' || op === 'sum') {
+            const values = (op === 'count' ? this.weight : this.sum).slice(0, groups);
+            return { kind: 'number', values, at: undefined };
+        }
+        const values = new Float64Array(groups);
+        for (let g = 0; g < groups; g++) {
+            values[g] =
+                this.weight[g] === 0
+                    ? Number.NaN
+                    : op === 'mean'
+                        ? this.sum[g] / this.weight[g]
+                        : op === 'min'
+                            ? this.min[g]
+                            : this.max[g];
+        }
+        return { kind: 'number', values, at: undefined, nanIsAbsent: true };
+    }
+}

package/esm/util/stringUtils.d.ts

@@ -0,0 +1,5 @@
+export declare function shorten(name: string, max?: number, short?: number): string;
+export declare function shorten2(name: string, max?: number): string;
+export declare function truncateMiddle(str: string, maxLen?: number): string;
+export declare function pluralize(count: number, noun: string, plural?: string): string;
+export declare function capitalizeFirst(s: string): string;

package/esm/util/stringUtils.js

@@ -0,0 +1,34 @@
+export function shorten(name, max = 70, short = 30) {
+    return name.length > max
+        ? `${name.slice(0, short)}...${name.slice(-short)}`
+        : name;
+}
+export function shorten2(name, max = 70) {
+    return name.length > max ? `${name.slice(0, max)}...` : name;
+}
+export function truncateMiddle(str, maxLen = 40) {
+    if (str.length <= maxLen) {
+        return str;
+    }
+    const half = Math.floor((maxLen - 3) / 2);
+    return `${str.slice(0, half)}...${str.slice(-half)}`;
+}
+// Plural noun for a count, for the "N hidden features" / "Clear N highlights"
+// family of labels. Takes the count rather than returning a bare suffix so the
+// call site reads as the sentence it produces, and so `0` pairs with the plural
+// ("0 features") the way English does — the hand-written `n > 1 ? 's' : ''`
+// scattered around got that right only because every one of those labels was
+// already gated on n > 0.
+//
+// `plural` covers the irregular pairs the same sentences run into once the noun
+// is not the only word that inflects — `pluralize(n, 'was', 'were')`,
+// `pluralize(n, 'URL is', 'URLs are')` — so those don't grow a second helper.
+export function pluralize(count, noun, plural = `${noun}s`) {
+    return count === 1 ? noun : plural;
+}
+// Sentence-case a noun that arrives lowercase because it also appears
+// mid-sentence — the display nouns ('feature', 'read', 'variant') that name
+// what a track holds are the case this exists for.
+export function capitalizeFirst(s) {
+    return `${s.charAt(0).toUpperCase()}${s.slice(1)}`;
+}

package/esm/util/svAlt.d.ts

@@ -0,0 +1,145 @@
+import type { Feature } from './simpleFeature.ts';
+import type { Breakend } from '@gmod/vcf';
+export declare const SV_SYMBOLIC_ALLELES: string[];
+/**
+ * #api
+ * parseBreakend, honoring its `Breakend | undefined` signature. ALT strings are
+ * user data and malformed breakends do occur; @gmod/vcf <=7.0.10 throws on them
+ * instead of returning undefined, which would otherwise fail a whole render or
+ * feature-parse pass over one bad allele. Use this everywhere rather than
+ * importing parseBreakend directly; it can become a plain re-export once the
+ * upstream fix ships.
+ */
+export declare function safeParseBreakend(alt: string): Breakend | undefined;
+/**
+ * #api
+ * The mate locString ("chr2:100") of a parsed breakend, or undefined when it
+ * names no navigable position. Two ALT forms reach here without one: a single
+ * breakend (`.A` / `G.`) has no mate at all, and the symbolic-mate forms
+ * (`G<DEL>`, `<DEL>G`) get a placeholder `<DEL>:1` from parseBreakend, which
+ * puts a symbolic allele id where a contig name belongs. Callers that navigate
+ * or split-view a mate must drop both rather than treat `<DEL>` as a refName.
+ */
+export declare function getBreakendMateLocString(breakend?: Breakend): string | undefined;
+/**
+ * #api
+ * Parse raw (non-assembly-resolved) mate coordinates from a VCF SV feature+alt.
+ * Returns undefined when no mate coordinate info is found. `alleleIndex` is
+ * the alt's place in `ALT`, which a record repeating one symbolic allele with
+ * several lengths needs; it defaults to the first place `alt` appears.
+ */
+export declare function parseSvAlt(feature: Feature, alt?: string, alleleIndex?: number): {
+    mateRefName: string;
+    matePos: number;
+    mateDirection?: number;
+    joinDirection?: number;
+} | undefined;
+/**
+ * #api
+ * Which way the sequence each end of a breakend KEEPS runs from its breakpoint,
+ * as `+1 = right` / `-1 = left` — the convention `StarFusionAdapter`'s
+ * `tickDirection` states and the one every producer in the tree emits.
+ *
+ * The two halves read their strings with OPPOSITE polarity, which is the whole
+ * reason to state them together. `Join: 'right'` says the mate piece is joined
+ * to the RIGHT of the ref base, so this end keeps the sequence to its left:
+ * negated. `MateDirection: 'right'` says the mate's own piece extends to the
+ * right of the mate position, which is already the direction it keeps: taken as
+ * read. So `N[chr2:2000[` is `{ joinDirection: -1, mateDirection: 1 }`, and that
+ * is the same pair `StarFusionAdapter` emits for the fusion it describes — the
+ * donor keeps the sequence below its breakpoint (-1) and the acceptor the
+ * sequence above its own (+1).
+ *
+ * Split out of `parseSvAlt` because a consumer holding an already-parsed
+ * `Breakend` was re-deriving it by hand, in two adjacent ternaries of opposite
+ * polarity — the shape that produced 78bb7b84f9.
+ */
+export declare function breakendKeepsDirections(bnd: Breakend): {
+    mateDirection: number;
+    joinDirection: number;
+};
+/**
+ * #api
+ * Breakend notation, without parsing it: bracket forms (`G[chr2:100[`), single
+ * breakends (`.A` / `G.`), and the symbolic-mate form (`G<DEL>`, an angle
+ * bracket past position 0; a leading `<` is a plain symbolic allele).
+ */
+export declare function isBreakend(alt: string): boolean;
+/**
+ * #api
+ * The conventional size floor for calling a sequence indel structural.
+ */
+export declare const SV_MIN_LENGTH = 50;
+/**
+ * #api
+ * The class a symbolic allele id, `SVTYPE` or `EVENTTYPE` names. A subtype folds
+ * into its first level (`DEL:ME:ALU` is DEL, `DUP:TANDEM` DUP), except the
+ * tandem repeats VCF 4.4 spells `CNV:TR` and ExpansionHunter `STRn`, and the
+ * inverted duplication `INV:DUP`. 1000 Genomes' `CNn` counts one haplotype's
+ * copies, so none is a deletion and two or more a duplication. `''` for an
+ * empty or missing token.
+ */
+export declare function svClassOfToken(raw: string): string;
+/**
+ * #api
+ * The structural-variant class one ALT allele states, `''` for one that is not
+ * structural. A symbolic allele's own id wins. Otherwise VCF 4.4's `EVENTTYPE`
+ * does; then a breakend is the class its `SVTYPE` declares where that says more
+ * than BND, and a sequence allele is an insertion or deletion by its length
+ * against REF, else its `SVTYPE`'s class.
+ */
+export declare function svClassOfAlt(alt: string, { ref, info, alleleIndex, }?: {
+    ref?: string;
+    info?: Record<string, unknown>;
+    alleleIndex?: number;
+}): string;
+/**
+ * #api
+ * The structural-variant class of a VCF record as a whole: the one class its
+ * alleles state, CNV where they are losses and gains of one segment, OTHER
+ * where they otherwise disagree, and `''` for a record with no structural
+ * allele.
+ */
+export declare function svClassOf(feature: Feature): string;
+export declare function readTranslocationMate(info: {
+    CHR2?: string[];
+    END?: number[];
+    STRANDS?: string[];
+}): {
+    chr: string;
+    pos: number;
+    myDir: string;
+    mateDir: string;
+    myKeepsDir: number;
+    mateKeepsDir: number;
+} | undefined;
+/**
+ * One end of a junction: the base beside the join on the side this end keeps,
+ * 0-based.
+ */
+export interface JunctionEnd {
+    refName: string;
+    pos: number;
+    /** which way the sequence this end keeps runs from it: 1 right, -1 left, 0 unknown */
+    keeps: number;
+}
+/**
+ * #api
+ * Where a paired record's junction is at each of its two ends, and which side
+ * of it each end keeps — the one answer every launcher, the row menu and the
+ * chain walk take, whether the record is a VCF breakend, a symbolic SV or a
+ * paired adapter's row (BEDPE, STAR-Fusion). Refnames are as the record spells
+ * them. `undefined` for a record naming no other end. A VCF record is read
+ * through `alt`, its first ALT unless the caller names another.
+ *
+ * A VCF end is its own position. A paired adapter's end is a block, and the
+ * junction is the block's edge on the side the end keeps: stated by
+ * `mateDirection` where the adapter knows it, read off the strands where the
+ * record states one for each end as BEDPE does, and with neither the two
+ * blocks face each other. A PAF row's strand is the query's orientation and
+ * states none for the target, so it names no side.
+ */
+export declare function junctionEnds(feature: Feature, alt?: string | undefined, alleleIndex?: number): {
+    own: JunctionEnd;
+    mate: JunctionEnd;
+} | undefined;