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

package/esm/BedGraphAdapter/configSchema.d.ts

@@ -1,15 +1,41 @@
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function normalizeSnapshot(snap: Record<string, unknown>): Record<string, unknown>;
+/**
+ * #config BedGraphAdapter
+ * #trackType QuantitativeTrack
+ * #fileFormat quantitative | BedGraph (plain) | Loaded entirely into memory; for small files
+ * used to load plain-text bedGraph signal files. Loads the whole file into
+ * memory, so prefer the BedGraphTabixAdapter for large files.
+ *
+ * #example
+ * ```js
+ * {
+ *   type: 'BedGraphAdapter',
+ *   uri: 'https://example.com/signal.bedGraph',
+ * }
+ * ```
+ */
 declare const BedGraphAdapter: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    bedGraphLocation: {
-        type: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
+    /**
+     * #slot
+     * location of the plain-text bedGraph (`chrom start end value`, one line
+     * per interval). May be gzipped.
+     */
+    readonly bedGraphLocation: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my.bedgraph";
+            readonly locationType: "UriLocation";
         };
     };
-    columnNames: {
-        type: string;
-        description: string;
-        defaultValue: never[];
+    /**
+     * #slot
+     */
+    readonly columnNames: {
+        readonly type: "stringArray";
+        readonly description: "List of column names";
+        readonly defaultValue: readonly [];
     };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type BedGraphAdapterConfig = Instance<typeof BedGraphAdapter>;
 export default BedGraphAdapter;

package/esm/BedGraphAdapter/configSchema.js

@@ -1,6 +1,36 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+export function normalizeSnapshot(snap) {
+    return snap.uri
+        ? {
+            ...snap,
+            bedGraphLocation: {
+                uri: snap.uri,
+                baseUri: snap.baseUri,
+            },
+        }
+        : snap;
+}
+/**
+ * #config BedGraphAdapter
+ * #trackType QuantitativeTrack
+ * #fileFormat quantitative | BedGraph (plain) | Loaded entirely into memory; for small files
+ * used to load plain-text bedGraph signal files. Loads the whole file into
+ * memory, so prefer the BedGraphTabixAdapter for large files.
+ *
+ * #example
+ * ```js
+ * {
+ *   type: 'BedGraphAdapter',
+ *   uri: 'https://example.com/signal.bedGraph',
+ * }
+ * ```
+ */
 const BedGraphAdapter = ConfigurationSchema('BedGraphAdapter', {
+    /**
+     * #slot
+     * location of the plain-text bedGraph (`chrom start end value`, one line
+     * per interval). May be gzipped.
+     */
     bedGraphLocation: {
         type: 'fileLocation',
         defaultValue: {
@@ -8,6 +38,9 @@ const BedGraphAdapter = ConfigurationSchema('BedGraphAdapter', {
             locationType: 'UriLocation',
         },
     },
+    /**
+     * #slot
+     */
     columnNames: {
         type: 'stringArray',
         description: 'List of column names',
@@ -15,16 +48,18 @@ const BedGraphAdapter = ConfigurationSchema('BedGraphAdapter', {
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                bedGraphLocation: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "BedGraphAdapter",
+     *   "uri": "yourfile.bed"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default BedGraphAdapter;

package/esm/BedGraphAdapter/index.js

@@ -1,10 +1,11 @@
 import AdapterType from '@jbrowse/core/pluggableElementTypes/AdapterType';
-import configSchema from "./configSchema.js";
+import configSchema, { normalizeSnapshot } from './configSchema.js';
 export default function BedGraphAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'BedGraphAdapter',
         displayName: 'BedGraph adapter',
+        normalizeSnapshot,
         configSchema,
-        getAdapterClass: () => import("./BedGraphAdapter.js").then(r => r.default),
+        getAdapterClass: () => import('./BedGraphAdapter.js').then(r => r.default),
     }));
 }

package/esm/BedGraphTabixAdapter/BedGraphTabixAdapter.d.ts

@@ -1,15 +1,15 @@
 import { TabixIndexedFile } from '@gmod/tabix';
 import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+import type { BedGraphTabixAdapterConfig } from './configSchema.ts';
 import type { BaseOptions } from '@jbrowse/core/data_adapters/BaseAdapter';
 import type { Feature, Region } from '@jbrowse/core/util';
-export default class BedGraphAdapter extends BaseFeatureDataAdapter {
-    private configured?;
-    private configurePre;
-    protected configure(): Promise<{
+export default class BedGraphTabixAdapter extends BaseFeatureDataAdapter<BedGraphTabixAdapterConfig> {
+    protected configure: (opts?: BaseOptions) => Promise<{
+        columnNames: string[];
         bedGraph: TabixIndexedFile;
         header: string;
-        columnNames: string[];
     }>;
+    private configurePre;
     getNames(): Promise<string[] | undefined>;
     getRefNames(opts?: BaseOptions): Promise<string[]>;
     getHeader(): Promise<string>;

package/esm/BedGraphTabixAdapter/BedGraphTabixAdapter.js

@@ -1,74 +1,80 @@
 import { TabixIndexedFile } from '@gmod/tabix';
-import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { SimpleFeature } from '@jbrowse/core/util';
-import { openLocation } from '@jbrowse/core/util/io';
+import { BaseFeatureDataAdapter, cachedSetup, } from '@jbrowse/core/data_adapters/BaseAdapter';
+import { downloadStatus } from '@jbrowse/core/util';
+import { sharedBgzfWorkerPool } from '@jbrowse/core/util/bgzfWorkerPool';
+import { decompressedBytesBudget } from '@jbrowse/core/util/cacheBudgets';
+import { openLocation, openTabixIndexFilehandle } from '@jbrowse/core/util/io';
 import { ObservableCreate } from '@jbrowse/core/util/rxjs';
-export default class BedGraphAdapter extends BaseFeatureDataAdapter {
-    configured;
+import { withStopTokenSignal } from '@jbrowse/core/util/stopToken';
+import { readTabixHeaderLines } from '@jbrowse/core/util/tabix';
+import { makeBedGraphFeature } from '../bedGraphUtil.js';
+import { parseNamesFromHeader } from '../util.js';
+export default class BedGraphTabixAdapter extends BaseFeatureDataAdapter {
+    // `label` because the index setup narrates nothing itself; the helper shows
+    // it only while the first attempt is in flight, so pan/zoom re-entry (every
+    // getFeatures/byte-estimate awaits it) doesn't re-flash "Downloading index"
+    configure = cachedSetup({
+        label: 'Downloading index',
+        setup: () => this.configurePre(),
+    });
     async configurePre() {
         const pm = this.pluginManager;
         const bedGraphGzLocation = this.getConf('bedGraphGzLocation');
         const location = this.getConf(['index', 'location']);
         const indexType = this.getConf(['index', 'indexType']);
-        const filehandle = openLocation(bedGraphGzLocation, pm);
-        const isCSI = indexType === 'CSI';
         const bedGraph = new TabixIndexedFile({
-            filehandle,
-            csiFilehandle: isCSI ? openLocation(location, pm) : undefined,
-            tbiFilehandle: !isCSI ? openLocation(location, pm) : undefined,
-            chunkCacheSize: 50 * 2 ** 20,
+            filehandle: openLocation(bedGraphGzLocation, pm),
+            ...openTabixIndexFilehandle(location, indexType, pm),
+            chunkCacheBudget: decompressedBytesBudget,
+            bgzfWorkerPool: sharedBgzfWorkerPool(),
         });
         const columnNames = this.getConf('columnNames');
-        const header = await bedGraph.getHeader();
+        // Not bedGraph.getHeader(): that returns only a `#`-commented header, so a
+        // file whose header is a plain row skipped via `tabix -S 1` reported none
+        // and quietly lost the names of its value columns.
+        const header = (await readTabixHeaderLines(bedGraph)).join('\n');
         return {
             columnNames,
             bedGraph,
             header,
         };
     }
-    async configure() {
-        if (!this.configured) {
-            this.configured = this.configurePre().catch((e) => {
-                this.configured = undefined;
-                throw e;
-            });
-        }
-        return this.configured;
-    }
     async getNames() {
-        const { bedGraph, columnNames } = await this.configure();
-        if (columnNames.length) {
-            return columnNames;
-        }
-        const header = await bedGraph.getHeader();
-        const defs = header.split(/\n|\r\n|\r/).filter(f => !!f);
-        const defline = defs.at(-1);
-        return defline?.includes('\t')
-            ? defline
-                .slice(1)
-                .split('\t')
-                .map(f => f.trim())
-            : undefined;
+        const { header, columnNames } = await this.configure();
+        return columnNames.length ? columnNames : parseNamesFromHeader(header);
     }
     async getRefNames(opts = {}) {
-        const { bedGraph } = await this.configure();
-        return bedGraph.getReferenceSequenceNames(opts);
+        const { bedGraph } = await this.configure(opts);
+        return downloadStatus('Downloading index', opts.statusCallback, onProgress => bedGraph.getReferenceSequenceNames({ ...opts, onProgress }));
     }
     async getHeader() {
-        const { bedGraph } = await this.configure();
-        return bedGraph.getHeader();
+        const { header } = await this.configure();
+        return header;
     }
     getFeatures(query, opts = {}) {
         return ObservableCreate(async (observer) => {
-            const { bedGraph } = await this.configure();
+            const { bedGraph } = await this.configure(opts);
             const meta = await bedGraph.getMetadata();
             const { columnNumbers } = meta;
             const colRef = columnNumbers.ref - 1;
             const colStart = columnNumbers.start - 1;
             const colEnd = columnNumbers.end - 1;
             const same = colStart === colEnd;
-            const names = (await this.getNames())?.slice(same ? 2 : 3) || [];
-            await bedGraph.getLines(query.refName, query.start + (same ? -1 : 0), query.end, {
+            const names = (await this.getNames())?.slice(same ? 2 : 3) ?? [];
+            await withStopTokenSignal(opts.stopToken, signal => downloadStatus('Downloading features', opts.statusCallback, onProgress => 
+            // `same` is a single-coordinate file — a GWAS-style txt with only a
+            // start column, indexed `-b N -e N`. The widening is not slop: the
+            // column value is used below as an interbase start (point p is
+            // drawn at [p, p+1)), while the index reads that same column as a
+            // 1-based position and places the record at [p-1, p). getLines
+            // filters on the index's view, so the point at exactly query.start
+            // — visible at the left edge of the view — is one the query would
+            // otherwise not ask for. Widening by a base is what asks for it.
+            //
+            // For a file indexed `-0`, the two views agree and this instead
+            // pulls in one extra point just left of the view, which is
+            // harmless.
+            bedGraph.getLines(query.refName, query.start + (same ? -1 : 0), query.end, {
                 lineCallback: (line, fileOffset) => {
                     const cols = line.split('\t');
                     const refName = cols[colRef];
@@ -79,26 +85,25 @@ export default class BedGraphAdapter extends BaseFeatureDataAdapter {
                         throw new Error(`start/end NaN on line "${line}", with colStart:${colStart} and colEnd:${colEnd}. run "tabix -p bed" to ensure bed preset`);
                     }
                     for (let j = 0; j < rest.length; j++) {
-                        const uniqueId = `${this.id}-${fileOffset}-${j}`;
-                        const score = Math.abs(+rest[j]);
-                        const source = names[j] || `col${j}`;
-                        if (score) {
-                            observer.next(new SimpleFeature({
-                                id: uniqueId,
-                                data: {
-                                    refName,
-                                    start,
-                                    end,
-                                    score,
-                                    source,
-                                },
-                            }));
+                        const feat = makeBedGraphFeature({
+                            uniqueId: `${this.id}-${fileOffset}-${j}`,
+                            refName,
+                            start,
+                            end,
+                            names,
+                            j,
+                            value: rest[j],
+                        });
+                        if (feat) {
+                            observer.next(feat);
                         }
                     }
                 },
                 ...opts,
-            });
+                onProgress,
+                signal,
+            })));
             observer.complete();
-        });
+        }, opts.stopToken);
     }
 }

package/esm/BedGraphTabixAdapter/configSchema.d.ts

@@ -1,29 +1,58 @@
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function normalizeSnapshot(snap: Record<string, unknown>): Record<string, unknown>;
+/**
+ * #config BedGraphTabixAdapter
+ * #trackType QuantitativeTrack
+ * #fileFormat quantitative | BedGraph (tabix)
+ * used to load bgzip-compressed, tabix-indexed bedGraph signal files
+ *
+ * #example
+ * The `uri` shorthand auto-resolves the `.tbi` index:
+ * ```js
+ * {
+ *   type: 'BedGraphTabixAdapter',
+ *   uri: 'https://example.com/signal.bedGraph.gz',
+ * }
+ * ```
+ */
 declare const BedGraphTabixAdapter: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    bedGraphGzLocation: {
-        type: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
+    /**
+     * #slot
+     * location of the bgzip-compressed bedGraph (`chrom start end value`,
+     * sorted by position). Must be bgzip rather than plain gzip, which tabix
+     * cannot index.
+     */
+    readonly bedGraphGzLocation: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my.bedgraph";
+            readonly locationType: "UriLocation";
         };
     };
-    index: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-        indexType: {
-            model: import("@jbrowse/mobx-state-tree").ISimpleType<"TBI" | "CSI">;
-            type: string;
-            defaultValue: string;
+    readonly index: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly indexType: {
+            readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"CSI" | "TBI">;
+            readonly type: 'stringEnum';
+            readonly defaultValue: 'TBI';
+            readonly description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address.';
         };
-        location: {
-            type: string;
-            defaultValue: {
-                uri: string;
-                locationType: string;
+        readonly location: {
+            readonly type: 'fileLocation';
+            readonly defaultValue: {
+                readonly uri: '/path/to/my.gz.tbi';
+                readonly locationType: 'UriLocation';
             };
+            readonly description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.';
         };
     }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
-    columnNames: {
-        type: string;
-        description: string;
-        defaultValue: never[];
+    /**
+     * #slot
+     */
+    readonly columnNames: {
+        readonly type: "stringArray";
+        readonly description: "List of column names";
+        readonly defaultValue: readonly [];
     };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type BedGraphTabixAdapterConfig = Instance<typeof BedGraphTabixAdapter>;
 export default BedGraphTabixAdapter;

package/esm/BedGraphTabixAdapter/configSchema.js

@@ -1,7 +1,29 @@
-import { ConfigurationSchema } from '@jbrowse/core/configuration';
-import { types } from '@jbrowse/mobx-state-tree';
-function x() { }
+import { ConfigurationSchema, expandTabixShorthand, tabixIndexFields, } from '@jbrowse/core/configuration';
+export function normalizeSnapshot(snap) {
+    return expandTabixShorthand(snap, 'bedGraphGzLocation');
+}
+/**
+ * #config BedGraphTabixAdapter
+ * #trackType QuantitativeTrack
+ * #fileFormat quantitative | BedGraph (tabix)
+ * used to load bgzip-compressed, tabix-indexed bedGraph signal files
+ *
+ * #example
+ * The `uri` shorthand auto-resolves the `.tbi` index:
+ * ```js
+ * {
+ *   type: 'BedGraphTabixAdapter',
+ *   uri: 'https://example.com/signal.bedGraph.gz',
+ * }
+ * ```
+ */
 const BedGraphTabixAdapter = ConfigurationSchema('BedGraphTabixAdapter', {
+    /**
+     * #slot
+     * location of the bgzip-compressed bedGraph (`chrom start end value`,
+     * sorted by position). Must be bgzip rather than plain gzip, which tabix
+     * cannot index.
+     */
     bedGraphGzLocation: {
         type: 'fileLocation',
         defaultValue: {
@@ -9,20 +31,10 @@ const BedGraphTabixAdapter = ConfigurationSchema('BedGraphTabixAdapter', {
             locationType: 'UriLocation',
         },
     },
-    index: ConfigurationSchema('VcfIndex', {
-        indexType: {
-            model: types.enumeration('IndexType', ['TBI', 'CSI']),
-            type: 'stringEnum',
-            defaultValue: 'TBI',
-        },
-        location: {
-            type: 'fileLocation',
-            defaultValue: {
-                uri: '/path/to/my.vcf.gz.tbi',
-                locationType: 'UriLocation',
-            },
-        },
-    }),
+    index: ConfigurationSchema('TabixIndex', { ...tabixIndexFields }),
+    /**
+     * #slot
+     */
     columnNames: {
         type: 'stringArray',
         description: 'List of column names',
@@ -30,22 +42,18 @@ const BedGraphTabixAdapter = ConfigurationSchema('BedGraphTabixAdapter', {
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                bedGraphGzLocation: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-                index: {
-                    location: {
-                        uri: `${snap.uri}.tbi`,
-                        baseUri: snap.baseUri,
-                    },
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config, assumes yourfile.bg.gz.tbi:
+     * ```json
+     * {
+     *   "type": "BedGraphTabixAdapter",
+     *   "uri": "yourfile.bg.gz"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default BedGraphTabixAdapter;

package/esm/BedGraphTabixAdapter/index.js

@@ -1,10 +1,11 @@
 import AdapterType from '@jbrowse/core/pluggableElementTypes/AdapterType';
-import configSchema from "./configSchema.js";
+import configSchema, { normalizeSnapshot } from './configSchema.js';
 export default function BedGraphTabixAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'BedGraphTabixAdapter',
         displayName: 'BedGraphTabix adapter',
+        normalizeSnapshot,
         configSchema,
-        getAdapterClass: () => import("./BedGraphTabixAdapter.js").then(r => r.default),
+        getAdapterClass: () => import('./BedGraphTabixAdapter.js').then(r => r.default),
     }));
 }

package/esm/BedTabixAdapter/BedTabixAdapter.d.ts

@@ -1,51 +1,47 @@
 import { TabixIndexedFile } from '@gmod/tabix';
 import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+import type { BedTabixAdapterConfig } from './configSchema.ts';
 import type PluginManager from '@jbrowse/core/PluginManager';
-import type { AnyConfigurationModel } from '@jbrowse/core/configuration';
 import type { BaseOptions } from '@jbrowse/core/data_adapters/BaseAdapter';
 import type { getSubAdapterType } from '@jbrowse/core/data_adapters/dataAdapterCache';
 import type { Feature, Region } from '@jbrowse/core/util';
-export default class BedTabixAdapter extends BaseFeatureDataAdapter {
-    private parser;
+export default class BedTabixAdapter extends BaseFeatureDataAdapter<BedTabixAdapterConfig> {
+    private getParser;
+    private readonly bedGzLoc;
     protected bed: TabixIndexedFile;
-    protected columnNames: string[];
-    protected scoreColumn: string;
     static capabilities: string[];
-    setupP?: Promise<{
-        meta: Awaited<ReturnType<TabixIndexedFile['getMetadata']>>;
+    getMetadata: (opts?: BaseOptions) => Promise<{
+        refNameToId: Record<string, number>;
+        refIdToName: string[];
+        metaChar: string | undefined;
+        columnNumbers: {
+            ref: number;
+            start: number;
+            end: number;
+        };
+        coordinateType: string;
+        format: string;
+        maxRefLength: number;
+        skipLines?: number;
+        maxBlockSize: number;
+        firstDataLine?: import("@gmod/tabix").default;
+        refCount?: number;
+        csi?: boolean;
+        csiVersion?: number;
+        minShift: number;
+        depth: number;
+        maxBinNumber: number;
     }>;
-    constructor(config: AnyConfigurationModel, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager);
+    getNames: (opts?: BaseOptions) => Promise<string[] | undefined>;
+    constructor(config: BedTabixAdapterConfig, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager);
     getRefNames(opts?: BaseOptions): Promise<string[]>;
     getHeader(opts?: BaseOptions): Promise<string>;
-    getMetadataPre2(_opts?: BaseOptions): Promise<{
-        meta: Awaited<ReturnType<TabixIndexedFile["getMetadata"]>>;
-    }>;
-    getMetadataPre(): Promise<{
-        meta: {
-            refNameToId: Record<string, number>;
-            refIdToName: string[];
-            metaChar: string | undefined;
-            columnNumbers: {
-                ref: number;
-                start: number;
-                end: number;
-            };
-            coordinateType: string;
-            format: string;
-            maxRefLength: number;
-            skipLines?: number;
-            maxBinNumber?: number;
-            maxBlockSize: number;
-            firstDataLine?: import("@gmod/tabix").default;
-            refCount?: number;
-            csi?: boolean;
-            csiVersion?: number;
-            depth?: number;
-        };
-    }>;
-    getMetadata(opts?: BaseOptions): Promise<{
-        meta: Awaited<ReturnType<TabixIndexedFile["getMetadata"]>>;
-    }>;
-    getNames(): Promise<string[] | undefined>;
+    /**
+     * Estimate compressed bytes for regions straight from the tabix index — no
+     * feature download. Lets wrapping adapters (e.g. MafTabix) byte-budget a
+     * fetch before pulling the (potentially huge) per-line payload.
+     */
+    getRegionByteSize(regions: Region[], opts?: BaseOptions): Promise<number>;
+    private readNames;
     getFeatures(query: Region, opts?: BaseOptions): import("rxjs").Observable<Feature>;
 }