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

package/esm/GtfAdapter/GtfAdapter.d.ts

@@ -1,28 +1,11 @@
 import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { IntervalTree } from '@jbrowse/core/util';
+import type { GtfAdapterConfig } from './configSchema.ts';
 import type { BaseOptions } from '@jbrowse/core/data_adapters/BaseAdapter';
-import type { Feature, SimpleFeatureSerialized } from '@jbrowse/core/util';
+import type { Feature } from '@jbrowse/core/util';
 import type { Region } from '@jbrowse/core/util/types';
-import type { Observer } from 'rxjs';
-type StatusCallback = (arg: string) => void;
-type SimpleFeat = SimpleFeatureSerialized;
-export default class GtfAdapter extends BaseFeatureDataAdapter {
-    calculatedIntervalTreeMap: Record<string, IntervalTree<SimpleFeat>>;
-    gtfFeatures?: Promise<{
-        header: string;
-        intervalTreeMap: Record<string, (sc?: StatusCallback) => IntervalTree<SimpleFeat>>;
-    }>;
-    private loadDataP;
+export default class GtfAdapter extends BaseFeatureDataAdapter<GtfAdapterConfig> {
     private loadData;
     getRefNames(opts?: BaseOptions): Promise<string[]>;
     getHeader(opts?: BaseOptions): Promise<string>;
     getFeatures(query: Region, opts?: BaseOptions): import("rxjs").Observable<Feature>;
-    getFeaturesHelper({ query, opts, observer, allowRedispatch, originalQuery, }: {
-        query: Region;
-        opts: BaseOptions;
-        observer: Observer<Feature>;
-        allowRedispatch: boolean;
-        originalQuery?: Region;
-    }): Promise<void>;
 }
-export {};

package/esm/GtfAdapter/GtfAdapter.js

@@ -1,65 +1,33 @@
-import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { IntervalTree, SimpleFeature, doesIntersect2, fetchAndMaybeUnzip, max, min, } from '@jbrowse/core/util';
+import { BaseFeatureDataAdapter, cachedSetup, } from '@jbrowse/core/data_adapters/BaseAdapter';
+import { SimpleFeature, fetchAndMaybeUnzip } from '@jbrowse/core/util';
 import { openLocation } from '@jbrowse/core/util/io';
-import { parseLineByLine } from '@jbrowse/core/util/parseLineByLine';
+import { groupLinesByRef, makeFeatureIntervalTreeMap, } from '@jbrowse/core/util/parseLineByLine';
 import { ObservableCreate } from '@jbrowse/core/util/rxjs';
-import { parseStringSync } from 'gtf-nostream';
-import { featureData } from "../util.js";
+import { aggregateGtfFeatures, parseGtfToFeatures } from '../util.js';
 export default class GtfAdapter extends BaseFeatureDataAdapter {
-    calculatedIntervalTreeMap = {};
-    gtfFeatures;
-    async loadDataP(opts) {
-        const loc = openLocation(this.getConf('gtfLocation'), this.pluginManager);
-        const buffer = await fetchAndMaybeUnzip(loc, opts);
-        const headerLines = [];
-        const featureMap = {};
-        parseLineByLine(buffer, line => {
-            if (line.startsWith('#')) {
-                headerLines.push(line);
-            }
-            else if (line.startsWith('>')) {
-                return false;
-            }
-            else {
-                const ret = line.indexOf('\t');
-                const refName = line.slice(0, ret);
-                if (!featureMap[refName]) {
-                    featureMap[refName] = '';
-                }
-                featureMap[refName] += `${line}\n`;
-            }
-            return true;
-        }, opts?.statusCallback);
-        const intervalTreeMap = Object.fromEntries(Object.entries(featureMap).map(([refName, lines]) => [
-            refName,
-            (sc) => {
-                if (!this.calculatedIntervalTreeMap[refName]) {
-                    sc?.('Parsing GTF data');
-                    const intervalTree = new IntervalTree();
-                    for (const obj of parseStringSync(lines)
-                        .flat()
-                        .map((f, i) => featureData(f, `${this.id}-${refName}-${i}`))) {
-                        intervalTree.insert([obj.start, obj.end], obj);
-                    }
-                    this.calculatedIntervalTreeMap[refName] = intervalTree;
-                }
-                return this.calculatedIntervalTreeMap[refName];
-            },
-        ]));
-        return {
-            header: headerLines.join('\n'),
-            intervalTreeMap,
-        };
-    }
-    async loadData(opts = {}) {
-        if (!this.gtfFeatures) {
-            this.gtfFeatures = this.loadDataP(opts).catch((e) => {
-                this.gtfFeatures = undefined;
-                throw e;
-            });
-        }
-        return this.gtfFeatures;
-    }
+    // the whole file is resident after one load, so genes are aggregated once
+    // here and stored in the interval tree already spanning all their
+    // transcripts; getFeatures is then a plain tree search with no per-query
+    // aggregation or redispatch. Progress comes from inside the load itself
+    // rather than a label wrapped around it
+    loadData = cachedSetup({
+        setup: async (opts) => {
+            const aggregateField = this.getConf('aggregateField');
+            const buffer = await fetchAndMaybeUnzip(openLocation(this.getConf('gtfLocation'), this.pluginManager), opts);
+            const { headerLines, linesByRef } = groupLinesByRef(buffer, opts.statusCallback);
+            const intervalTreeMap = makeFeatureIntervalTreeMap(linesByRef, (lines, refName) => aggregateGtfFeatures({
+                feats: parseGtfToFeatures(lines.map(line => ({ line })), (_record, i) => `${this.id}-${refName}-${i}`),
+                aggregateField,
+                refName,
+                idPrefix: this.id,
+                // whole-ref bounds so nothing is clipped at load; the tree search
+                // in getFeatures does the per-query clipping instead
+                regionStart: 0,
+                regionEnd: Number.MAX_SAFE_INTEGER,
+            }), 'Parsing GTF data');
+            return { header: headerLines.join('\n'), intervalTreeMap };
+        },
+    });
     async getRefNames(opts = {}) {
         const { intervalTreeMap } = await this.loadData(opts);
         return Object.keys(intervalTreeMap);
@@ -71,94 +39,21 @@ export default class GtfAdapter extends BaseFeatureDataAdapter {
     getFeatures(query, opts = {}) {
         return ObservableCreate(async (observer) => {
             try {
-                await this.getFeaturesHelper({
-                    query,
-                    opts,
-                    observer,
-                    allowRedispatch: true,
-                });
+                const { intervalTreeMap } = await this.loadData(opts);
+                const tree = intervalTreeMap[query.refName];
+                if (tree) {
+                    for (const feat of tree(opts.statusCallback).search([
+                        query.start,
+                        query.end,
+                    ])) {
+                        observer.next(new SimpleFeature({ id: feat.uniqueId, data: feat }));
+                    }
+                }
+                observer.complete();
             }
             catch (e) {
                 observer.error(e);
             }
         }, opts.stopToken);
     }
-    async getFeaturesHelper({ query, opts, observer, allowRedispatch, originalQuery = query, }) {
-        const aggregateField = this.getConf('aggregateField');
-        const { start, end, refName } = query;
-        const { intervalTreeMap } = await this.loadData(opts);
-        const feats = intervalTreeMap[refName]?.(opts.statusCallback).search([
-            start,
-            end,
-        ]);
-        if (feats) {
-            if (allowRedispatch && feats.length) {
-                let minStart = Number.POSITIVE_INFINITY;
-                let maxEnd = Number.NEGATIVE_INFINITY;
-                let hasAnyAggregateField = false;
-                for (const feat of feats) {
-                    if (feat.start < minStart) {
-                        minStart = feat.start;
-                    }
-                    if (feat.end > maxEnd) {
-                        maxEnd = feat.end;
-                    }
-                    if (feat[aggregateField]) {
-                        hasAnyAggregateField = true;
-                    }
-                }
-                if (hasAnyAggregateField &&
-                    (maxEnd > query.end || minStart < query.start)) {
-                    await this.getFeaturesHelper({
-                        query: {
-                            ...query,
-                            start: minStart - 500_000,
-                            end: maxEnd + 500_000,
-                        },
-                        opts,
-                        observer,
-                        allowRedispatch: false,
-                        originalQuery: query,
-                    });
-                    return;
-                }
-            }
-            const parentAggregation = {};
-            for (const feat of feats) {
-                const aggr = feat[aggregateField];
-                if (!parentAggregation[aggr]) {
-                    parentAggregation[aggr] = [];
-                }
-                if (aggr) {
-                    parentAggregation[aggr].push(feat);
-                }
-                else {
-                    observer.next(new SimpleFeature({
-                        id: feat.uniqueId,
-                        data: feat,
-                    }));
-                }
-            }
-            for (const [name, subfeatures] of Object.entries(parentAggregation)) {
-                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 { uniqueId, strand } = subfeatures[0];
-                    observer.next(new SimpleFeature({
-                        id: `${uniqueId}-parent`,
-                        data: {
-                            type: 'gene',
-                            subfeatures,
-                            strand,
-                            name,
-                            start: s,
-                            end: e,
-                            refName: query.refName,
-                        },
-                    }));
-                }
-            }
-        }
-        observer.complete();
-    }
 }

package/esm/GtfAdapter/configSchema.d.ts

@@ -1,16 +1,42 @@
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function normalizeSnapshot(snap: Record<string, unknown>): Record<string, unknown>;
+/**
+ * #config GtfAdapter
+ * #category adapter
+ * #trackType FeatureTrack
+ * #fileFormat feature | GTF (plain) | Loaded entirely into memory; for small files
+ * used to load plain-text GTF files (optionally gzipped). Loads the whole file
+ * into memory, so prefer the GtfTabixAdapter for large files.
+ *
+ * #example
+ * The `uri` shorthand works for plain or gzipped GTF:
+ * ```js
+ * {
+ *   type: 'GtfAdapter',
+ *   uri: 'https://example.com/genes.gtf',
+ * }
+ * ```
+ */
 declare const GtfAdapter: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    gtfLocation: {
-        type: string;
-        description: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
+    /**
+     * #slot
+     */
+    readonly gtfLocation: {
+        readonly type: "fileLocation";
+        readonly description: "path to gtf file, also allows for gzipped gtf";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my.gtf";
+            readonly locationType: "UriLocation";
         };
     };
-    aggregateField: {
-        type: string;
-        description: string;
-        defaultValue: string;
+    /**
+     * #slot
+     */
+    readonly aggregateField: {
+        readonly type: "string";
+        readonly description: "attribute naming the parent gene that transcripts are aggregated into. transcripts are grouped by gene_id where the file has one (gene names are not unique within a reference), so this is the gene label, and the grouping key only for files with no gene_id";
+        readonly defaultValue: "gene_name";
     };
 }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type GtfAdapterConfig = Instance<typeof GtfAdapter>;
 export default GtfAdapter;

package/esm/GtfAdapter/configSchema.js

@@ -1,6 +1,36 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+export function normalizeSnapshot(snap) {
+    return snap.uri
+        ? {
+            ...snap,
+            gtfLocation: {
+                uri: snap.uri,
+                baseUri: snap.baseUri,
+            },
+        }
+        : snap;
+}
+/**
+ * #config GtfAdapter
+ * #category adapter
+ * #trackType FeatureTrack
+ * #fileFormat feature | GTF (plain) | Loaded entirely into memory; for small files
+ * used to load plain-text GTF files (optionally gzipped). Loads the whole file
+ * into memory, so prefer the GtfTabixAdapter for large files.
+ *
+ * #example
+ * The `uri` shorthand works for plain or gzipped GTF:
+ * ```js
+ * {
+ *   type: 'GtfAdapter',
+ *   uri: 'https://example.com/genes.gtf',
+ * }
+ * ```
+ */
 const GtfAdapter = ConfigurationSchema('GtfAdapter', {
+    /**
+     * #slot
+     */
     gtfLocation: {
         type: 'fileLocation',
         description: 'path to gtf file, also allows for gzipped gtf',
@@ -9,23 +39,28 @@ const GtfAdapter = ConfigurationSchema('GtfAdapter', {
             locationType: 'UriLocation',
         },
     },
+    /**
+     * #slot
+     */
     aggregateField: {
         type: 'string',
-        description: 'field used to aggregate multiple transcripts into a single parent gene feature',
+        description: 'attribute naming the parent gene that transcripts are aggregated into. transcripts are grouped by gene_id where the file has one (gene names are not unique within a reference), so this is the gene label, and the grouping key only for files with no gene_id',
         defaultValue: 'gene_name',
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                gtfLocation: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "GtfAdapter",
+     *   "uri": "yourfile.gtf"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default GtfAdapter;

package/esm/GtfAdapter/index.js

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

package/esm/GtfTabixAdapter/GtfTabixAdapter.d.ts

@@ -0,0 +1,12 @@
+import { BaseFeatureDataAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+import type { GtfTabixAdapterConfig } 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';
+export default class GtfTabixAdapter extends BaseFeatureDataAdapter<GtfTabixAdapterConfig> {
+    private configure;
+    getRefNames(opts?: BaseOptions): Promise<string[]>;
+    getHeader(opts?: BaseOptions): Promise<string>;
+    getRegionByteSize(regions: Region[], opts?: BaseOptions): Promise<number>;
+    getFeatures(query: Region, opts?: BaseOptions): import("rxjs").Observable<Feature>;
+}

package/esm/GtfTabixAdapter/GtfTabixAdapter.js

@@ -0,0 +1,79 @@
+import { TabixIndexedFile } from '@gmod/tabix';
+import { BaseFeatureDataAdapter, cachedSetup, } from '@jbrowse/core/data_adapters/BaseAdapter';
+import { SimpleFeature, 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';
+import { readTabixLinesRedispatched } from '@jbrowse/core/util/tabix';
+import { aggregateGtfFeatures, parseGtfToFeatures } from '../util.js';
+export default class GtfTabixAdapter extends BaseFeatureDataAdapter {
+    configure = cachedSetup({
+        label: 'Downloading index',
+        setup: async (_opts, onProgress) => {
+            const gtf = new TabixIndexedFile({
+                filehandle: openLocation(this.getConf('gtfGzLocation'), this.pluginManager),
+                ...openTabixIndexFilehandle(this.getConf(['index', 'location']), this.getConf(['index', 'indexType']), this.pluginManager),
+                chunkCacheBudget: decompressedBytesBudget,
+                bgzfWorkerPool: sharedBgzfWorkerPool(),
+            });
+            return {
+                gtf,
+                dontRedispatchSet: new Set(this.getConf('dontRedispatch')),
+                // the index is a whole-file read, so its byte ticks turn the
+                // "Downloading index" label into a determinate bar
+                header: await gtf.getHeader({ onProgress }),
+            };
+        },
+    });
+    async getRefNames(opts = {}) {
+        const { gtf } = await this.configure(opts);
+        return downloadStatus('Downloading index', opts.statusCallback, onProgress => gtf.getReferenceSequenceNames({ ...opts, onProgress }));
+    }
+    async getHeader(opts = {}) {
+        const { header } = await this.configure(opts);
+        return header;
+    }
+    // Index-only compressed-byte estimate (no feature download), used by the
+    // feature-fetch RPC to short-circuit an over-budget region before pulling
+    // every line — see executeRenderFeatureData.
+    async getRegionByteSize(regions, opts = {}) {
+        const { gtf } = await this.configure(opts);
+        return gtf.bytesForRegions(regions, opts);
+    }
+    getFeatures(query, opts = {}) {
+        return ObservableCreate(async (observer) => {
+            try {
+                const { gtf, dontRedispatchSet } = await this.configure(opts);
+                // The type list alone, and `opts.topLevelOnly` is deliberately not
+                // honoured — both for the same reason. A GTF line has no `ID`/`Parent`,
+                // so there is no cheap "can this have children"; and a GTF top-level
+                // feature is not a line at all, it is synthesized by
+                // `aggregateGtfFeatures` from the transcripts in the FETCHED set, whose
+                // span it takes from them. So the argument that lets GFF3 skip the
+                // flanks — a top-level feature overlapping the query is already in the
+                // query's own read — does not transfer, and a narrower bound could draw
+                // a gene short rather than merely flat. Nothing is lost by declining:
+                // no GTF record shape makes this bound expensive (the fixtures top out
+                // at 19 kb, against GFF3's chromosome-long `match`).
+                const lines = await readTabixLinesRedispatched(gtf, query, line => !dontRedispatchSet.has(line.type), opts);
+                const feats = parseGtfToFeatures(lines, record => `${this.id}-offset-${record.offset}`);
+                const aggregated = aggregateGtfFeatures({
+                    feats,
+                    aggregateField: this.getConf('aggregateField'),
+                    refName: query.refName,
+                    idPrefix: this.id,
+                    regionStart: query.start,
+                    regionEnd: query.end,
+                });
+                for (const feat of aggregated) {
+                    observer.next(new SimpleFeature({ id: feat.uniqueId, data: feat }));
+                }
+                observer.complete();
+            }
+            catch (e) {
+                observer.error(e);
+            }
+        }, opts.stopToken);
+    }
+}

package/esm/GtfTabixAdapter/configSchema.d.ts

@@ -0,0 +1,81 @@
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function normalizeSnapshot(snap: Record<string, unknown>): Record<string, unknown>;
+/**
+ * #config GtfTabixAdapter
+ * #category adapter
+ * #trackType FeatureTrack
+ * #fileFormat feature | GTF (tabix)
+ * used to load bgzip-compressed, tabix-indexed GTF files
+ *
+ * #example
+ * The `uri` shorthand auto-resolves the `.tbi` index; add `csi: true` for a
+ * `.csi` index instead:
+ * ```js
+ * {
+ *   type: 'GtfTabixAdapter',
+ *   uri: 'https://example.com/genes.gtf.gz',
+ * }
+ * ```
+ */
+declare const GtfTabixAdapter: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+    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 bgzip-compressed GTF, sorted by position. Must be bgzip
+     * rather than plain gzip, which tabix cannot index.
+     */
+    readonly gtfGzLocation: {
+        readonly type: "fileLocation";
+        readonly defaultValue: {
+            readonly uri: "/path/to/my.gtf.gz";
+            readonly locationType: "UriLocation";
+        };
+    };
+    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.';
+        };
+        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>>;
+    /**
+     * #slot
+     * the GtfTabixAdapter has to "redispatch" if it fetches a region and
+     * features it finds inside that region extend outside the region we
+     * requested. you can disable this for certain feature types to avoid
+     * fetching e.g. the entire chromosome
+     *
+     * the defaults are the whole-sequence records the common annotation sources
+     * emit: `region` (NCBI), `supercontig`/`scaffold` (Ensembl, for
+     * non-chromosomal sequences), plus `chromosome` and `contig`. They span an
+     * entire reference and have no children, so letting one expand the fetch
+     * would pull a whole chromosome to gain nothing
+     */
+    readonly dontRedispatch: {
+        readonly type: "stringArray";
+        readonly defaultValue: readonly ["chromosome", "region", "contig", "supercontig", "scaffold"];
+    };
+    /**
+     * #slot
+     */
+    readonly aggregateField: {
+        readonly type: "string";
+        readonly description: "attribute naming the parent gene that transcripts are aggregated into. transcripts are grouped by gene_id where the file has one (gene names are not unique within a reference), so this is the gene label, and the grouping key only for files with no gene_id";
+        readonly defaultValue: "gene_name";
+    };
+}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+export type GtfTabixAdapterConfig = Instance<typeof GtfTabixAdapter>;
+export default GtfTabixAdapter;

package/esm/GtfTabixAdapter/configSchema.js

@@ -0,0 +1,88 @@
+import { ConfigurationSchema, expandTabixShorthand, tabixIndexFields, } from '@jbrowse/core/configuration';
+import { densityAdapterConfigSchemaFields } from '@jbrowse/core/data_adapters/BaseAdapter';
+export function normalizeSnapshot(snap) {
+    return expandTabixShorthand(snap, 'gtfGzLocation');
+}
+/**
+ * #config GtfTabixAdapter
+ * #category adapter
+ * #trackType FeatureTrack
+ * #fileFormat feature | GTF (tabix)
+ * used to load bgzip-compressed, tabix-indexed GTF files
+ *
+ * #example
+ * The `uri` shorthand auto-resolves the `.tbi` index; add `csi: true` for a
+ * `.csi` index instead:
+ * ```js
+ * {
+ *   type: 'GtfTabixAdapter',
+ *   uri: 'https://example.com/genes.gtf.gz',
+ * }
+ * ```
+ */
+const GtfTabixAdapter = ConfigurationSchema('GtfTabixAdapter', {
+    /**
+     * #slot
+     * location of the bgzip-compressed GTF, sorted by position. Must be bgzip
+     * rather than plain gzip, which tabix cannot index.
+     */
+    gtfGzLocation: {
+        type: 'fileLocation',
+        defaultValue: {
+            uri: '/path/to/my.gtf.gz',
+            locationType: 'UriLocation',
+        },
+    },
+    index: ConfigurationSchema('TabixIndex', { ...tabixIndexFields }),
+    /**
+     * #slot
+     * the GtfTabixAdapter has to "redispatch" if it fetches a region and
+     * features it finds inside that region extend outside the region we
+     * requested. you can disable this for certain feature types to avoid
+     * fetching e.g. the entire chromosome
+     *
+     * the defaults are the whole-sequence records the common annotation sources
+     * emit: `region` (NCBI), `supercontig`/`scaffold` (Ensembl, for
+     * non-chromosomal sequences), plus `chromosome` and `contig`. They span an
+     * entire reference and have no children, so letting one expand the fetch
+     * would pull a whole chromosome to gain nothing
+     */
+    dontRedispatch: {
+        type: 'stringArray',
+        defaultValue: [
+            'chromosome',
+            'region',
+            'contig',
+            'supercontig',
+            'scaffold',
+        ],
+    },
+    /**
+     * #slot
+     */
+    aggregateField: {
+        type: 'string',
+        description: 'attribute naming the parent gene that transcripts are aggregated into. transcripts are grouped by gene_id where the file has one (gene names are not unique within a reference), so this is the gene label, and the grouping key only for files with no gene_id',
+        defaultValue: 'gene_name',
+    },
+    ...densityAdapterConfigSchemaFields,
+}, {
+    explicitlyTyped: true,
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config, assumes tbi index at
+     * yourfile.gtf.gz.tbi (or .csi if csi:true):
+     *
+     * ```json
+     * {
+     *   "type": "GtfTabixAdapter",
+     *   "uri": "yourfile.gtf.gz",
+     *   "csi": true
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
+});
+export default GtfTabixAdapter;

package/esm/GtfTabixAdapter/index.d.ts

@@ -0,0 +1,2 @@
+import type PluginManager from '@jbrowse/core/PluginManager';
+export default function GtfTabixAdapterF(pluginManager: PluginManager): void;

package/esm/GtfTabixAdapter/index.js

@@ -0,0 +1,11 @@
+import { AdapterType } from '@jbrowse/core/pluggableElementTypes';
+import configSchema, { normalizeSnapshot } from './configSchema.js';
+export default function GtfTabixAdapterF(pluginManager) {
+    pluginManager.addAdapterType(() => new AdapterType({
+        name: 'GtfTabixAdapter',
+        displayName: 'GTF tabix adapter',
+        normalizeSnapshot,
+        configSchema,
+        getAdapterClass: () => import('./GtfTabixAdapter.js').then(r => r.default),
+    }));
+}