@jbrowse/plugin-bed 4.3.0 → 5.0.0-beta.2

package/esm/BedpeAdapter/configSchema.js

@@ -1,6 +1,34 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+export function normalizeSnapshot(snap) {
+    return snap.uri
+        ? {
+            ...snap,
+            bedpeLocation: {
+                uri: snap.uri,
+                baseUri: snap.baseUri,
+                locationType: 'UriLocation',
+            },
+        }
+        : snap;
+}
+/**
+ * #config BedpeAdapter
+ * #trackType VariantTrack
+ * #fileFormat variants | BEDPE | Paired/breakend records, e.g. SV calls or Hi-C loops
+ * intended for SVs in a single assembly
+ *
+ * #example
+ * ```js
+ * {
+ *   type: 'BedpeAdapter',
+ *   uri: 'https://example.com/sv.bedpe',
+ * }
+ * ```
+ */
 const BedpeAdapter = ConfigurationSchema('BedpeAdapter', {
+    /**
+     * #slot
+     */
     bedpeLocation: {
         type: 'fileLocation',
         description: 'can be plaintext or gzipped, not indexed so loaded into memory on startup',
@@ -9,6 +37,9 @@ const BedpeAdapter = ConfigurationSchema('BedpeAdapter', {
             locationType: 'UriLocation',
         },
     },
+    /**
+     * #slot
+     */
     columnNames: {
         type: 'stringArray',
         description: 'List of column names',
@@ -16,16 +47,18 @@ const BedpeAdapter = ConfigurationSchema('BedpeAdapter', {
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                bedpeLocation: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "BedpeAdapter",
+     *   "uri": "yourfile.bedpe.gz"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default BedpeAdapter;

package/esm/BedpeAdapter/index.js

@@ -1,10 +1,12 @@
 import AdapterType from '@jbrowse/core/pluggableElementTypes/AdapterType';
-import configSchema from "./configSchema.js";
+import configSchema, { normalizeSnapshot } from './configSchema.js';
 export default function BedpeAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'BedpeAdapter',
         displayName: 'BEDPE adapter',
         configSchema,
-        getAdapterClass: () => import("./BedpeAdapter.js").then(r => r.default),
+        getAdapterClass: () => import('./BedpeAdapter.js').then(r => r.default),
+        locationKey: 'bedpeLocation',
+        normalizeSnapshot,
     }));
 }

package/esm/BedpeAdapter/util.js

@@ -1,22 +1,35 @@
 import { SimpleFeature } from '@jbrowse/core/util';
+import { parseStrand } from '../util.js';
 const svTypes = new Set(['DUP', 'TRA', 'INV', 'CNV', 'DEL']);
 export function featureData(line, uniqueId, flip, names) {
     const l = line.split('\t');
     const ref1 = l[flip ? 3 : 0];
     const start1 = +l[flip ? 4 : 1];
     const end1 = +l[flip ? 5 : 2];
-    const ref2 = l[!flip ? 3 : 0];
-    const start2 = +l[!flip ? 4 : 1];
-    const end2 = +l[!flip ? 5 : 2];
-    const name = l[6];
-    const score = l[7] ? +l[7] : undefined;
-    const strand1 = parseStrand(l[8]);
-    const strand2 = parseStrand(l[9]);
+    const ref2 = l[flip ? 0 : 3];
+    const start2 = +l[flip ? 1 : 4];
+    const end2 = +l[flip ? 2 : 5];
+    // '.' is BED's "missing" marker, so a file that leaves the standard name and
+    // score columns unset must not produce the literal string '.' and a NaN
+    // score. Same rule `defaultParser` applies on the plain-BED path.
+    const name = l[6] === '.' ? undefined : l[6];
+    const score = l[7] && l[7] !== '.' ? +l[7] : undefined;
+    // Columns 9 and 10 ride with the blocks they describe. Left behind on a
+    // flipped row they anchored the feature at one end and gave it the other
+    // end's orientation, which every consumer reading a junction edge off the
+    // strand then got backwards for that half of the record.
+    const strand1 = parseStrand(l[flip ? 9 : 8]);
+    const strand2 = parseStrand(l[flip ? 8 : 9]);
     const extra = l.slice(10);
     const rest = names
         ? Object.fromEntries(names.slice(10).map((n, idx) => [n, extra[idx]]))
         : {};
     const ALT = svTypes.has(extra[0]) ? `<${extra[0]}>` : undefined;
+    // `name` and `score` are spread only when the file actually sets them, which
+    // is what lets a column past 10 of the same name through. juicer's bedpe is
+    // the case that needs it: Arrowhead writes '.' in both standard columns and
+    // its corner score in column 12, also called `score`, so an unconditional
+    // positional key shadowed the only column the caller ranks domains by.
     return new SimpleFeature({
         ...rest,
         start: start1,
@@ -24,8 +37,8 @@ export function featureData(line, uniqueId, flip, names) {
         type: 'paired_feature',
         refName: ref1,
         strand: strand1,
-        name,
-        score,
+        ...(name === undefined ? {} : { name }),
+        ...(score === undefined ? {} : { score }),
         uniqueId,
         mate: {
             refName: ref2,
@@ -36,17 +49,3 @@ export function featureData(line, uniqueId, flip, names) {
         ...(ALT ? { ALT: [ALT] } : {}),
     });
 }
-function parseStrand(strand) {
-    if (strand === '+') {
-        return 1;
-    }
-    else if (strand === '-') {
-        return -1;
-    }
-    else if (strand === '.') {
-        return 0;
-    }
-    else {
-        return undefined;
-    }
-}

package/esm/BigBedAdapter/BigBedAdapter.d.ts

@@ -1,32 +1,33 @@
 import { BigBed } from '@gmod/bbi';
 import BED from '@gmod/bed';
 import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+import type { BigBedAdapterConfig } from './configSchema.ts';
 import type { BaseOptions } from '@jbrowse/core/data_adapters/BaseAdapter';
 import type { Feature } from '@jbrowse/core/util';
 import type { Region } from '@jbrowse/core/util/types';
 import type { Observer } from 'rxjs';
-export default class BigBedAdapter extends BaseFeatureDataAdapter {
-    private cachedP?;
-    configurePre(opts?: BaseOptions): Promise<{
+export default class BigBedAdapter extends BaseFeatureDataAdapter<BigBedAdapterConfig> {
+    configure: (opts?: BaseOptions) => Promise<{
         bigbed: BigBed;
         header: import("@gmod/bbi").BigWigHeaderWithRefNames;
         parser: BED;
     }>;
-    configure(opts?: BaseOptions): Promise<{
+    configurePre(opts?: BaseOptions): Promise<{
         bigbed: BigBed;
-        header: Awaited<ReturnType<BigBed["getHeader"]>>;
+        header: import("@gmod/bbi").BigWigHeaderWithRefNames;
         parser: BED;
     }>;
     getRefNames(opts?: BaseOptions): Promise<string[]>;
+    getRegionByteSize(regions: Region[], opts?: BaseOptions): Promise<number>;
     getRefNameAliases(opts?: BaseOptions): Promise<{
         refName: unknown;
-        aliases: unknown[];
+        aliases: string[];
         override: boolean;
     }[]>;
     getData(): Promise<Feature[]>;
     getHeader(opts?: BaseOptions): Promise<{
         version: number;
-        fileType: string;
+        fileType: "bigbed" | "bigwig";
         autoSql: {};
         fields: {
             [k: string]: string;

package/esm/BigBedAdapter/BigBedAdapter.js

@@ -1,13 +1,20 @@
 import { BigBed } from '@gmod/bbi';
 import BED from '@gmod/bed';
-import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { SimpleFeature, doesIntersect2, max, min, updateStatus, } from '@jbrowse/core/util';
+import { BaseFeatureDataAdapter, cachedSetup, } from '@jbrowse/core/data_adapters/BaseAdapter';
+import { SimpleFeature, doesIntersect2, downloadStatus, max, min, updateStatus, } from '@jbrowse/core/util';
 import { openLocation } from '@jbrowse/core/util/io';
 import { ObservableCreate } from '@jbrowse/core/util/rxjs';
+import { withStopTokenSignal } from '@jbrowse/core/util/stopToken';
 import { firstValueFrom, toArray } from 'rxjs';
-import { featureData2 } from "../util.js";
+import { featureData } from '../util.js';
 export default class BigBedAdapter extends BaseFeatureDataAdapter {
-    cachedP;
+    // `label` on cachedSetup so "Downloading header" shows only while the first
+    // fetch is in flight; every later getFeatures resolves from the memo with no
+    // re-flash.
+    configure = cachedSetup({
+        label: 'Downloading header',
+        setup: opts => this.configurePre(opts),
+    });
     async configurePre(opts) {
         const pm = this.pluginManager;
         const bigbed = new BigBed({
@@ -23,19 +30,19 @@ export default class BigBedAdapter extends BaseFeatureDataAdapter {
             parser,
         };
     }
-    async configure(opts) {
-        if (!this.cachedP) {
-            this.cachedP = this.configurePre(opts).catch((e) => {
-                this.cachedP = undefined;
-                throw e;
-            });
-        }
-        return this.cachedP;
-    }
     async getRefNames(opts) {
         const { header } = await this.configure(opts);
         return Object.keys(header.refsByName);
     }
+    // Compressed download-size estimate straight from the bbi R-tree index (block
+    // byte lengths, no data blocks read), so a display can byte-gate an over-large
+    // BigBed fetch before it starts. Overrides the base no-estimate default, which
+    // left BigBed tracks ungated.
+    async getRegionByteSize(regions, opts) {
+        const { bigbed } = await this.configure(opts);
+        return bigbed.getRegionByteSizeMulti(regions, opts);
+    }
+    // allow using BigBedAdapter for aliases with chromAlias.bb file from UCSC
     async getRefNameAliases(opts) {
         const { header } = await this.configure(opts);
         const ret = await Promise.all(Object.keys(header.refsByName).map(async (refName) => (await firstValueFrom(this.getFeatures({
@@ -48,22 +55,20 @@ export default class BigBedAdapter extends BaseFeatureDataAdapter {
             .map(r => r.toJSON())
             .map(r => ({
             refName: r.ucsc,
-            aliases: [r.ncbi, r.refseq, r.genbank],
+            // chromAlias.bb columns are sparse: a chrom may lack an ncbi/refseq/
+            // genbank name, returned as empty strings that are not valid refNames
+            aliases: [r.ncbi, r.refseq, r.genbank].filter((alias) => !!alias),
             override: true,
         }));
     }
     async getData() {
         const refNames = await this.getRefNames();
-        const features = [];
-        for (const refName of refNames) {
-            const f = await firstValueFrom(this.getFeatures({
-                assemblyName: 'unknown',
-                refName,
-                start: 0,
-                end: Number.MAX_SAFE_INTEGER,
-            }).pipe(toArray()));
-            features.push(f);
-        }
+        const features = await Promise.all(refNames.map(refName => firstValueFrom(this.getFeatures({
+            assemblyName: 'unknown',
+            refName,
+            start: 0,
+            end: Number.MAX_SAFE_INTEGER,
+        }).pipe(toArray()))));
         return features.flat();
     }
     async getHeader(opts) {
@@ -83,78 +88,69 @@ export default class BigBedAdapter extends BaseFeatureDataAdapter {
         return Object.fromEntries(fields.map(({ name, comment }) => [name, comment]));
     }
     async getFeaturesHelper({ query, opts, observer, allowRedispatch, originalQuery = query, }) {
-        const { statusCallback = () => { } } = opts;
+        const { statusCallback } = opts;
         const scoreColumn = this.getConf('scoreColumn');
         const aggregateField = this.getConf('aggregateField');
         const disableGeneHeuristic = this.getConf('disableGeneHeuristic');
-        const { parser, bigbed } = await updateStatus('Downloading header', statusCallback, () => this.configure(opts));
-        const feats = await updateStatus('Downloading features', statusCallback, () => bigbed.getFeatures(query.refName, query.start, query.end, {
+        const { parser, bigbed } = await this.configure(opts);
+        // downloadStatus, not updateStatus: bbi knows the total block bytes up front
+        // (they come from the R-tree index) so this reports a determinate fraction
+        // rather than an indeterminate spinner. Matters most here — BigBed is a
+        // full-feature download, which is why getRegionByteSize gates it above.
+        const feats = await withStopTokenSignal(opts.stopToken, signal => downloadStatus('Downloading features', statusCallback, onProgress => bigbed.getFeatures(query.refName, query.start, query.end, {
             basesPerSpan: query.end - query.start,
-        }));
+            onProgress,
+            signal,
+        })));
         await updateStatus('Processing features', statusCallback, async () => {
             const parentAggregation = {};
-            const parentAggregationFlat = [];
-            if (feats.some(f => f.uniqueId === undefined)) {
-                throw new Error('found uniqueId undefined');
-            }
+            const singletons = [];
+            let minAggStart = Infinity;
+            let maxAggEnd = -Infinity;
             for (const feat of feats) {
-                const splitLine = [
-                    query.refName,
-                    `${feat.start}`,
-                    `${feat.end}`,
-                    ...(feat.rest?.split('\t') || []),
-                ];
-                const data = parser.parseLine(splitLine, {
-                    uniqueId: feat.uniqueId,
-                });
-                const aggr = data[aggregateField];
-                const aggrIsNotNone = aggr && aggr !== 'none';
-                const aggrKey = typeof aggr === 'string' ? aggr : `${aggr}`;
-                if (aggrIsNotNone && !parentAggregation[aggrKey]) {
-                    parentAggregation[aggrKey] = [];
-                }
-                const { uniqueId, type, chrom, chromStart, chromEnd, description, chromStarts: chromStarts2, blockStarts: blockStarts2, blockSizes: blockSizes2, score: score2, blockCount, thickStart, thickEnd, strand, ...rest } = data;
-                const f = featureData2({
-                    ...rest,
+                // empty chrom/start/end placeholders keep `rest` columns aligned to the
+                // autoSql schema (which begins at chrom); featureData reads back the
+                // numeric start/end/refName passed below, so positions 0-2 are unused
+                const splitLine = ['', '', '', ...(feat.rest?.split('\t') ?? [])];
+                const f = featureData({
                     scoreColumn,
                     splitLine,
                     parser,
-                    uniqueId: uniqueId,
+                    uniqueId: feat.uniqueId,
                     start: feat.start,
                     end: feat.end,
                     refName: query.refName,
                     disableGeneHeuristic,
                 });
+                const aggr = f[aggregateField];
+                const aggrIsNotNone = typeof aggr === 'string' && aggr && aggr !== 'none';
                 if (aggrIsNotNone) {
-                    parentAggregation[aggrKey].push(f);
-                    parentAggregationFlat.push(f);
+                    parentAggregation[aggr] ??= [];
+                    parentAggregation[aggr].push(f);
+                    if (f.start < minAggStart) {
+                        minAggStart = f.start;
+                    }
+                    if (f.end > maxAggEnd) {
+                        maxAggEnd = f.end;
+                    }
                 }
                 else {
-                    if (doesIntersect2(f.start, f.end, originalQuery.start, originalQuery.end)) {
-                        observer.next(new SimpleFeature({
-                            id: `${this.id}-${uniqueId}`,
-                            data: f,
-                        }));
-                    }
+                    singletons.push(f);
                 }
             }
-            if (allowRedispatch && parentAggregationFlat.length) {
-                let minStart = Number.POSITIVE_INFINITY;
-                let maxEnd = Number.NEGATIVE_INFINITY;
-                for (const feat of parentAggregationFlat) {
-                    if (feat.start < minStart) {
-                        minStart = feat.start;
-                    }
-                    if (feat.end > maxEnd) {
-                        maxEnd = feat.end;
-                    }
-                }
-                if (maxEnd > query.end || minStart < query.start) {
+            if (allowRedispatch && maxAggEnd > -Infinity) {
+                if (maxAggEnd > query.end || minAggStart < query.start) {
+                    // redispatch re-fetches a superset region, so emitting singletons
+                    // here too would double-emit them; defer emission to the recursion
                     await this.getFeaturesHelper({
                         query: {
                             ...query,
-                            start: minStart - 500_000,
-                            end: maxEnd + 500_000,
+                            // extend query to catch gene subfeatures outside the current view;
+                            // 500 kbp heuristic covers most genes/transcripts. Clamped at 0 so
+                            // a gene near the start of a contig doesn't produce a negative
+                            // region start.
+                            start: Math.max(0, minAggStart - 500_000),
+                            end: maxAggEnd + 500_000,
                         },
                         opts,
                         observer,
@@ -164,59 +160,56 @@ export default class BigBedAdapter extends BaseFeatureDataAdapter {
                     return;
                 }
             }
-            Object.entries(parentAggregation).map(([name, subfeatures]) => {
-                const s = min(subfeatures.map(f => f.start));
-                const e = max(subfeatures.map(f => f.end));
-                if (doesIntersect2(s, e, originalQuery.start, originalQuery.end)) {
-                    const subs = subfeatures.sort((a, b) => a.uniqueId.localeCompare(b.uniqueId));
-                    if (subs.some((a, i) => subs.some((b, j) => i !== j && doesIntersect2(a.start, a.end, b.start, b.end)))) {
+            for (const f of singletons) {
+                if (doesIntersect2(f.start, f.end, originalQuery.start, originalQuery.end)) {
+                    observer.next(new SimpleFeature({
+                        id: `${this.id}-${f.uniqueId}`,
+                        data: f,
+                    }));
+                }
+            }
+            for (const [name, subfeatures] of Object.entries(parentAggregation)) {
+                const subs = subfeatures.sort((a, b) => a.uniqueId.localeCompare(b.uniqueId));
+                const sortedByStart = [...subs].sort((a, b) => a.start - b.start);
+                const hasOverlaps = sortedByStart.some((f, i) => i > 0 && sortedByStart[i - 1].end > f.start);
+                // overlapping subs → one gene parent; non-overlapping → one parent per sub
+                // (handles bacterial GFF where two genes share a name but are distinct loci)
+                const groups = hasOverlaps ? [subs] : subs.map(sub => [sub]);
+                for (const group of groups) {
+                    // gate on each parent's own extent: a distant non-overlapping locus
+                    // sharing this name must not ride in on a sibling that intersects
+                    const groupStart = min(group.map(f => f.start));
+                    const groupEnd = max(group.map(f => f.end));
+                    if (doesIntersect2(groupStart, groupEnd, originalQuery.start, originalQuery.end)) {
                         observer.next(new SimpleFeature({
-                            id: `${this.id}-${subs[0]?.uniqueId}-parent`,
+                            id: `${this.id}-${group[0].uniqueId}-parent`,
                             data: {
                                 type: 'gene',
-                                subfeatures: subs,
-                                strand: subs[0]?.strand || 1,
+                                subfeatures: group,
+                                strand: group.find(f => f.strand !== 0)?.strand ?? 1,
                                 name,
-                                start: s,
-                                end: e,
+                                start: groupStart,
+                                end: groupEnd,
                                 refName: query.refName,
                             },
                         }));
                     }
-                    else {
-                        for (const sub of subs) {
-                            observer.next(new SimpleFeature({
-                                id: `${this.id}-${sub.uniqueId}-parent`,
-                                data: {
-                                    type: 'gene',
-                                    subfeatures: [sub],
-                                    strand: subs[0]?.strand || 1,
-                                    name,
-                                    start: sub.start,
-                                    end: sub.end,
-                                    refName: query.refName,
-                                },
-                            }));
-                        }
-                    }
                 }
-            });
+            }
         });
-        observer.complete();
     }
     getFeatures(query, opts = {}) {
         return ObservableCreate(async (observer) => {
             try {
                 await this.getFeaturesHelper({
-                    query: {
-                        ...query,
-                        start: query.start,
-                        end: query.end,
-                    },
+                    query,
                     opts,
                     observer,
                     allowRedispatch: true,
                 });
+                // complete once here, not in the helper: a redispatch recurses into the
+                // helper, so completing there would fire complete() twice
+                observer.complete();
             }
             catch (e) {
                 observer.error(e);

package/esm/BigBedAdapter/configSchema.d.ts

@@ -1,25 +1,60 @@
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function normalizeSnapshot(snap: Record<string, unknown>): Record<string, unknown>;
+/**
+ * #config BigBedAdapter
+ * #trackType FeatureTrack
+ * #fileFormat feature | BigBed
+ *
+ * #example
+ * ```js
+ * {
+ *   type: 'BigBedAdapter',
+ *   uri: 'https://example.com/features.bb',
+ * }
+ * ```
+ */
 declare const BigBedAdapter: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    bigBedLocation: {
-        type: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
+    readonly densityAdapter: {
+        readonly type: 'frozen';
+        readonly defaultValue: null;
+        readonly description: 'optional quantitative sub-adapter (e.g. a BigWigAdapter over a features-per-bin bigWig) drawn as a density band where the region is too large to fetch features; null disables it';
+    };
+    /**
+     * #slot
+     * location of the BigBed file. It carries its own index and summary zoom
+     * levels, so there is no separate index to configure.
+     */
+    readonly bigBedLocation: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my.bb";
+            readonly locationType: "UriLocation";
         };
     };
-    scoreColumn: {
-        type: string;
-        description: string;
-        defaultValue: string;
+    /**
+     * #slot
+     */
+    readonly scoreColumn: {
+        readonly type: "string";
+        readonly description: "The column to use as a \"score\" attribute";
+        readonly defaultValue: "";
     };
-    aggregateField: {
-        type: string;
-        description: string;
-        defaultValue: string;
+    /**
+     * #slot
+     */
+    readonly aggregateField: {
+        readonly type: "string";
+        readonly description: "An attribute to aggregate features with";
+        readonly defaultValue: "geneName2";
     };
-    disableGeneHeuristic: {
-        type: string;
-        description: string;
-        defaultValue: boolean;
+    /**
+     * #slot
+     */
+    readonly disableGeneHeuristic: {
+        readonly type: "boolean";
+        readonly description: "Disable the heuristic that auto-detects BED12 features as gene/transcript structures. Useful for files that have BED12-like structure but are not genes (e.g. tandem duplications)";
+        readonly defaultValue: false;
     };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type BigBedAdapterConfig = Instance<typeof BigBedAdapter>;
 export default BigBedAdapter;