@jbrowse/cli 5.0.0-beta.1 → 5.0.0-beta.3

package/README.md

@@ -59,6 +59,7 @@ COMMANDS
   admin-server         Start up a small admin server for JBrowse configuration
   upgrade              Upgrades JBrowse 2 to latest version
   make-pif             Creates pairwise indexed PAF (PIF), with bgzip and tabix
+  make-density         Counts feature starts per bin into a bigWig density sidecar, with bedGraphToBigWig
   sort-gff             Sort a GFF/GTF for tabix: sort -k1,1 -k4,4n, header kept on top
   sort-bed             Sort a BED for tabix: sort -k1,1 -k2,2n, header kept on top
   add-connection       Add a connection to a JBrowse 2 configuration
@@ -263,9 +264,9 @@ Options:
   -a, --assemblyNames        Assembly name or names for track as comma separated
                              string. For pairwise synteny tracks the order is
                              query,target (reverse of minimap2/nucmer argument
-                             order); for all-vs-all adapters
-                             (AllVsAllPAFAdapter/AllVsAllIndexedPAFAdapter) list
-                             every assembly the file covers, in any order
+                             order); for the multi-genome PAF adapters
+                             (MultiGenomePAFAdapter/MultiGenomeIndexedPAFAdapter)
+                             list every assembly the file covers, in any order
 
       --category             Optional comma separated string of categories to
                              group tracks
@@ -310,6 +311,11 @@ Options:
 
       --bed2                 Used only for mcscan anchors/simpleAnchors types
 
+      --density              Path or URL of a features-per-bin bigWig (jbrowse
+                             make-density) to attach as the adapter's
+                             densityAdapter. A local <file>.density.bw beside
+                             the track file is attached without this flag
+
 Notes:
 
 --load controls how the data file is placed relative to config.json: copy, move,
@@ -337,11 +343,19 @@ or a .json file with an array of BigWig locations or subadapter objects (each
 carrying its own name/color/group). With --load, local list entries are copied
 like any other track file.
 
+--density attaches a features-per-bin bigWig (jbrowse make-density) as the
+adapter's densityAdapter, the band a display draws where the region is too large
+to fetch features. A local <file>.density.bw beside the track file is attached
+without the flag; a URL cannot be probed, so a remote sidecar needs it. The
+adapters carrying the slot are BamAdapter, CramAdapter, HtsgetBamAdapter,
+Gff3TabixAdapter, GtfTabixAdapter, BedTabixAdapter, BigBedAdapter,
+VcfTabixAdapter and SplitVcfTabixAdapter.
+
 For pairwise synteny adapters (PAF/Delta/Chain) --assemblyNames is query,target
-— the reverse of the minimap2/nucmer input order. For the all-vs-all adapters
-(AllVsAllPAFAdapter, AllVsAllIndexedPAFAdapter) it is instead the full list of
-assemblies the file covers, in any order, since one all-vs-all file backs every
-pair.
+— the reverse of the minimap2/nucmer input order. For the multi-genome PAF
+adapters (MultiGenomePAFAdapter, MultiGenomeIndexedPAFAdapter) it is instead the
+full list of assemblies the file covers, in any order, since one multi-genome
+file backs every pair.
 
 Examples:
 
@@ -371,6 +385,9 @@ $ jbrowse add-track --multiwig a.bw,b.bw,c.bw --load copy --name "Coverage"
 
 # ...or from a sources.json carrying per-row name/color for each BigWig
 $ jbrowse add-track --multiwig sources.json --name "CATlas ATAC"
+
+# attach a remote density sidecar (a local genes.gff3.density.bw needs no flag)
+$ jbrowse add-track https://mywebsite.com/genes.gff3.gz --density https://mywebsite.com/genes.gff3.density.bw
 ```
 
 
@@ -398,14 +415,14 @@ nothing. That is what this command is mainly for.
 Two levels are reported:
 
   error    JBrowse accepts it and silently does the wrong thing — an unknown    
-       slot, a track naming an assembly the config never defines, a           
-defaultSession naming a trackId that does not exist, a duplicate           
-trackId. Exits 1.
+       slot, a key a defaultSession view or display does not declare, a         
+  track naming an assembly the config never defines, a defaultSession           
+naming a trackId that does not exist, a duplicate trackId. Exits 1.
 
   warning  JBrowse will complain by itself on load, or handles it — a type name 
           the core plugins do not register (expected if one of your plugins     
-      registers it), or a legacy key a migration rewrites. Never fails          
- the run.
+      registers it), or a legacy key a migration rewrites, such as a view       
+    nesting its settings under "init". Never fails the run.
 
 Types registered by plugins are not known to this command, so they come through
 as warnings rather than errors.
@@ -547,6 +564,9 @@ Options:
   -p, --port                 Specified port to start the server on (default:
                              9090)
 
+      --host                 Interface to bind to (default: 127.0.0.1). Use
+                             0.0.0.0 to accept connections from other machines
+
       --root                 Path to the root of the JB2 installation
 
       --bodySizeLimit        Size limit of the update message (default: 25mb)
@@ -554,9 +574,10 @@ Options:
 Notes:
 
 The admin-server lets a browser session write changes back to config.json on
-disk, authorized by a one-time key printed in the startup URL. It is meant for
-local configuration only: run it on a trusted machine and do not expose the port
-to untrusted networks or the public internet.
+disk, authorized by a one-time key printed in the startup URL. It binds to
+127.0.0.1 so only this machine can reach it. The key gates the config routes,
+but the rest of the JBrowse directory is served unauthenticated, so widen --host
+only on a trusted network.
 
 Examples:
 
@@ -571,6 +592,9 @@ $ jbrowse admin-server --root /path/to/jb2/
 
 # raise the body size limit for very large config updates
 $ jbrowse admin-server --bodySizeLimit 100mb
+
+# accept connections from other machines on the network
+$ jbrowse admin-server --host 0.0.0.0
 ```
 
 
@@ -637,16 +661,22 @@ Options:
 
       --csi                  Create a CSI index for the PIF file instead of TBI
 
-      --coarse               Minimum insertion/deletion length (bp) at which a
-                             coarse-tier row is split into multiple pieces so
-                             each row stays tight — 0 emits an unsplit coarse
-                             tier. Defaults to 10000. The no-CIGAR coarse tier
-                             (prefix T/Q) is emitted alongside the per-row CIGAR
-                             fine tier by default so whole-genome synteny views
-                             can auto-switch to it; pass --no-coarse to omit it.
+      --coarse               Accuracy bound (bp) of the coarse tier. A coarse
+                             row replaces its CIGAR with a coarse CIGAR (cr:Z:)
+                             that keeps every indel longer than half this length
+                             and folds the rest into runs, each run staying
+                             within this many bp of the real alignment. Defaults
+                             to 10000. The coarse tier (prefix T/Q) is emitted
+                             alongside the per-row CIGAR fine tier by default so
+                             whole-genome synteny views can auto-switch to it;
+                             pass --no-coarse to omit it.
+
+      --no-coarse            Do not emit the coarse tier; write only the per-row
+                             CIGAR fine tier.
 
-      --no-coarse            Do not emit the coarse no-CIGAR tier; write only
-                             the per-row CIGAR fine tier.
+      --threads              Compression threads for bgzip. Defaults to 4. Raise
+                             it on a machine with cores to spare, or set 1 to
+                             leave the rest of the machine alone.
 
 Notes:
 
@@ -666,11 +696,70 @@ $ jbrowse make-pif input.paf --out output.pif.gz
 # use a CSI index for assemblies with chromosomes longer than ~512 Mb
 $ jbrowse make-pif input.paf --csi
 
-# emit an unsplit coarse tier (alongside the fine tier)
-$ jbrowse make-pif input.paf --coarse 0
+# a looser coarse tier: runs within 50kb of the alignment, indels over 25kb kept
+$ jbrowse make-pif input.paf --coarse 50000
 
 # emit only the per-row CIGAR fine tier, skipping the coarse tier
 $ jbrowse make-pif input.paf --no-coarse
+
+# give bgzip more (or fewer) compression threads than the default 4
+$ jbrowse make-pif input.paf --threads 8
+```
+
+
+## jbrowse make-density
+
+```
+Counts feature starts per bin into a bigWig, the density sidecar a track draws
+where the region is too large to fetch its features
+
+Usage: jbrowse make-density <file> [options]
+
+Options:
+  -h, --help                 Show help
+
+      --bin                  Width of each bin, in bp [default: 1000]
+
+      --chrom-sizes          Two-column reference name and length table for the
+                             assembly the file is on
+
+      --assembly             FASTA of the assembly the file is on; its .fai
+                             supplies the reference lengths, in place of
+                             --chrom-sizes
+
+      --out                  Where to write the bigWig. Defaults to
+                             <file>.density.bw beside the input, which is where
+                             add-track looks for it
+
+Notes:
+
+The sidecar is attached to a track through its adapter's densityAdapter slot,
+which BamAdapter, CramAdapter, HtsgetBamAdapter, Gff3TabixAdapter,
+GtfTabixAdapter, BedTabixAdapter, BigBedAdapter, VcfTabixAdapter and
+SplitVcfTabixAdapter declare. add-track attaches it on its own when the default
+<file>.density.bw sits beside the track file, so building it before adding the
+track is all it takes; --density attaches one by path or URL.
+
+GFF3 counts only top-level features — a line whose attributes carry no Parent= —
+so a gene is one count rather than one per exon. GTF, BED and VCF have no parent
+link to follow, so every record counts.
+
+BAM and CRAM are out of scope: read depth is not feature density, and the tools
+that compute it already write bigWig. Point add-track --density at what they
+produce.
+
+Requires bedGraphToBigWig (UCSC) on the PATH.
+
+Examples:
+
+# writes genes.gff3.density.bw beside the input, in 1kb bins
+$ jbrowse make-density genes.gff3.gz --chrom-sizes hg38.chrom.sizes
+
+# take the reference lengths from the assembly FASTA index instead
+$ jbrowse make-density variants.vcf.gz --assembly hg38.fa
+
+# coarser bins, and a name of your own
+$ jbrowse make-density genes.gff3.gz --assembly hg38.fa --bin 10000 --out genes.10kb.bw
 ```
 
 

package/dist/commands/add-track-utils/adapter-utils.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import { adapterTypesToTrackTypeMap, formats, matchFormat, resolveIndexType, trackTypeForAdapter, } from '@jbrowse/add-track-core';
+import { isURL } from '../../types/common.js';
+import { densitySidecarPath } from '../shared/density.js';
 function hasLocField(spec) {
     return 'locField' in spec;
 }
@@ -51,6 +53,53 @@ export function siblingSidecar(location, suffix) {
     ];
     return candidates.find(c => fs.existsSync(c)) ?? candidates[0];
 }
+// The feature adapters whose schema spreads
+// `densityAdapterConfigSchemaFields`, so a `densityAdapter` written onto one
+// resolves to a slot rather than being dropped. Change one, change the other.
+const densityAdapterTypes = new Set([
+    'BamAdapter',
+    'CramAdapter',
+    'HtsgetBamAdapter',
+    'Gff3TabixAdapter',
+    'GtfTabixAdapter',
+    'BedTabixAdapter',
+    'BigBedAdapter',
+    'VcfTabixAdapter',
+    'SplitVcfTabixAdapter',
+]);
+/**
+ * The adapter with its density sidecar attached, and the local file to load
+ * beside the config when there is one.
+ *
+ * An explicit `--density` is taken as given, since a URL cannot be probed;
+ * otherwise the conventional `<file>.density.bw` counts only when it is
+ * actually there, the way `siblingSidecar` probes an index.
+ */
+export function withDensityAdapter({ adapter, location, density, makeLocation, }) {
+    const supported = densityAdapterTypes.has(adapter.type);
+    if (density !== undefined && !supported) {
+        throw new Error(`--density has no slot on ${adapter.type}. The adapters carrying a density sidecar are: ${[...densityAdapterTypes].join(', ')}`);
+    }
+    const probed = location !== undefined && fs.existsSync(densitySidecarPath(location))
+        ? densitySidecarPath(location)
+        : undefined;
+    if (probed !== undefined && !supported) {
+        console.warn(`Warning: ${probed} sits beside the track file but ${adapter.type} has no densityAdapter slot, so it is not attached. The adapters carrying one are indexed: bgzip and tabix the file, then add it.`);
+    }
+    const file = density === undefined ? (supported ? probed : undefined) : density;
+    return file === undefined
+        ? { adapter }
+        : {
+            adapter: {
+                ...adapter,
+                densityAdapter: {
+                    type: 'BigWigAdapter',
+                    bigWigLocation: makeLocation(file),
+                },
+            },
+            file: isURL(file) ? undefined : file,
+        };
+}
 // builds the adapter object and the list of source files for a spec in one
 // place, so the config it writes and the files add-track copies can never drift
 function buildFromSpec(spec, { location, index, bed1, bed2, makeLocation }) {

package/dist/commands/add-track.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { printHelp, readConfigFile, resolveConfigPath } from '../utils.js';
-import { guessTrack, guessTrackType, makeLocationProtocol, } from './add-track-utils/adapter-utils.js';
+import { guessTrack, guessTrackType, makeLocationProtocol, withDensityAdapter, } from './add-track-utils/adapter-utils.js';
 import { loadFiles } from './add-track-utils/file-operations.js';
 import { buildMultiWiggle } from './add-track-utils/multiwig.js';
 import { addSyntenyAssemblyNames, buildTrackConfig, mapLocationForFiles, mergeDisplayDefaults, } from './add-track-utils/track-config.js';
@@ -39,7 +39,7 @@ export async function run(args) {
         assemblyNames: {
             type: 'string',
             short: 'a',
-            description: 'Assembly name or names for track as comma separated string. For pairwise synteny tracks the order is query,target (reverse of minimap2/nucmer argument order); for all-vs-all adapters (AllVsAllPAFAdapter/AllVsAllIndexedPAFAdapter) list every assembly the file covers, in any order',
+            description: 'Assembly name or names for track as comma separated string. For pairwise synteny tracks the order is query,target (reverse of minimap2/nucmer argument order); for the multi-genome PAF adapters (MultiGenomePAFAdapter/MultiGenomeIndexedPAFAdapter) list every assembly the file covers, in any order',
         },
         category: {
             type: 'string',
@@ -104,6 +104,10 @@ export async function run(args) {
             type: 'string',
             description: 'Used only for mcscan anchors/simpleAnchors types',
         },
+        density: {
+            type: 'string',
+            description: "Path or URL of a features-per-bin bigWig (jbrowse make-density) to attach as the adapter's densityAdapter. A local <file>.density.bw beside the track file is attached without this flag",
+        },
     };
     const { values: flags, positionals } = parseArgs({
         args,
@@ -134,11 +138,18 @@ export async function run(args) {
         'BigWig files/URLs, or a .json file with an array of BigWig locations or ' +
         'subadapter objects (each carrying its own name/color/group). With --load, ' +
         'local list entries are copied like any other track file.\n\n' +
+        '--density attaches a features-per-bin bigWig (jbrowse make-density) as the ' +
+        "adapter's densityAdapter, the band a display draws where the region is too " +
+        'large to fetch features. A local <file>.density.bw beside the track file is ' +
+        'attached without the flag; a URL cannot be probed, so a remote sidecar needs ' +
+        'it. The adapters carrying the slot are BamAdapter, CramAdapter, ' +
+        'HtsgetBamAdapter, Gff3TabixAdapter, GtfTabixAdapter, BedTabixAdapter, ' +
+        'BigBedAdapter, VcfTabixAdapter and SplitVcfTabixAdapter.\n\n' +
         'For pairwise synteny adapters (PAF/Delta/Chain) --assemblyNames is ' +
         'query,target — the reverse of the minimap2/nucmer input order. For the ' +
-        'all-vs-all adapters (AllVsAllPAFAdapter, AllVsAllIndexedPAFAdapter) it is ' +
+        'multi-genome PAF adapters (MultiGenomePAFAdapter, MultiGenomeIndexedPAFAdapter) it is ' +
         'instead the full list of assemblies the file covers, in any order, since ' +
-        'one all-vs-all file backs every pair.';
+        'one multi-genome file backs every pair.';
     const examples = [
         '# copy /path/to/my.bam and /path/to/my.bam.bai to current directory and adds track to config.json',
         '$ jbrowse add-track /path/to/my.bam --load copy',
@@ -166,6 +177,9 @@ export async function run(args) {
         '',
         '# ...or from a sources.json carrying per-row name/color for each BigWig',
         '$ jbrowse add-track --multiwig sources.json --name "CATlas ATAC"',
+        '',
+        '# attach a remote density sidecar (a local genes.gff3.density.bw needs no flag)',
+        '$ jbrowse add-track https://mywebsite.com/genes.gff3.gz --density https://mywebsite.com/genes.gff3.density.bw',
     ];
     if (flags.help) {
         printHelp({
@@ -187,7 +201,7 @@ export async function run(args) {
     const mapLocation = (p) => wrap(mapLocationForFiles(p, load, subDir));
     // build the adapter (and the set of files to load) up front, so the track-arg
     // and load validation runs before we touch the config on disk
-    const { adapter, files, trackType, trackId } = multiwig
+    const { adapter: builtAdapter, files, trackType, trackId, } = multiwig
         ? buildMultiWiggleTrack({
             sources: multiwig,
             mapLocation,
@@ -207,6 +221,15 @@ export async function run(args) {
             trackType: flags.trackType,
             trackId: flags.trackId,
         });
+    const { adapter, file: densityFile } = withDensityAdapter({
+        adapter: builtAdapter,
+        location,
+        density: flags.density,
+        makeLocation: mapLocation,
+    });
+    if (densityFile !== undefined && !load) {
+        throw new Error(`--density names a local file (${densityFile}); pass --load to say how it is placed beside the config`);
+    }
     const baseConfigObj = config ? parseConfigFlag(config) : undefined;
     const displayDefaults = mergeDisplayDefaults({
         configObj: baseConfigObj,
@@ -245,7 +268,7 @@ export async function run(args) {
     });
     const updatedConfig = { ...configContents, tracks };
     await loadFiles({
-        files,
+        files: [...files, densityFile],
         destDir: configDir,
         mode: load,
         subDir,

package/dist/commands/admin-server/index.js

@@ -13,6 +13,11 @@ export async function run(args) {
             short: 'p',
             description: 'Specified port to start the server on (default: 9090)',
         },
+        host: {
+            type: 'string',
+            description: 'Interface to bind to (default: 127.0.0.1). Use 0.0.0.0 to accept ' +
+                'connections from other machines',
+        },
         root: {
             type: 'string',
             description: 'Path to the root of the JB2 installation',
@@ -40,12 +45,15 @@ export async function run(args) {
         '',
         '# raise the body size limit for very large config updates',
         '$ jbrowse admin-server --bodySizeLimit 100mb',
+        '',
+        '# accept connections from other machines on the network',
+        '$ jbrowse admin-server --host 0.0.0.0',
     ];
     const notes = 'The admin-server lets a browser session write changes back to ' +
         'config.json on disk, authorized by a one-time key printed in the ' +
-        'startup URL. It is meant for local configuration only: run it on a ' +
-        'trusted machine and do not expose the port to untrusted networks or the ' +
-        'public internet.';
+        'startup URL. It binds to 127.0.0.1 so only this machine can reach it. ' +
+        'The key gates the config routes, but the rest of the JBrowse directory ' +
+        'is served unauthenticated, so widen --host only on a trusted network.';
     if (flags.help) {
         printHelp({
             description,
@@ -56,7 +64,7 @@ export async function run(args) {
         });
         return;
     }
-    const { root, bodySizeLimit = '25mb' } = flags;
+    const { root, host, bodySizeLimit = '25mb' } = flags;
     const { outFile, baseDir } = await setupConfigFile({ root });
     const port = parsePort({ portStr: flags.port });
     // the key lives only in this process and in the startup URL printed below. It
@@ -71,5 +79,5 @@ export async function run(args) {
         serverRef,
         bodySizeLimit: parseByteLimit(bodySizeLimit),
     }));
-    startServer({ server, port, key, outFile, serverRef });
+    startServer({ server, port, host, key, outFile, serverRef });
 }

package/dist/commands/admin-server/utils.js

@@ -4,6 +4,9 @@ import path from 'node:path';
 import handler from 'serve-handler';
 import { debug, isRecord, resolveConfigPath, writeJsonFile, } from '../../utils.js';
 import { createDefaultConfig } from '../add-assembly/utils.js';
+// Loopback, so the unauthenticated static handler below does not serve the
+// data directory to every host on the network. `--host` opts out.
+export const DEFAULT_HOST = '127.0.0.1';
 export function parsePort({ portStr, defaultPort = 9090, }) {
     if (!portStr) {
         return defaultPort;
@@ -122,9 +125,8 @@ function sendText(res, status, body) {
     res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
     res.end(body);
 }
-// What `cors()` sent. The server binds to localhost for a browser tab on the
-// same machine to talk to, and the admin key is what authorizes a write — the
-// origin never was.
+// What `cors()` sent. The admin key is what authorizes a write; the origin
+// never was.
 function applyCorsHeaders(res) {
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, POST, OPTIONS');
@@ -278,9 +280,9 @@ export function createRequestHandler({ baseDir, outFile, key, serverRef, bodySiz
         }
     };
 }
-export function startServer({ server, port, key, outFile, serverRef, }) {
-    server.listen(port, () => {
-        console.log(`Admin server started on port ${port}\n\n` +
+export function startServer({ server, port, host = DEFAULT_HOST, key, outFile, serverRef, }) {
+    server.listen(port, host, () => {
+        console.log(`Admin server started on ${host}:${port}\n\n` +
             `To access the admin interface, open your browser to:\n` +
             `http://localhost:${port}?adminKey=${key}\n\n` +
             `Admin key: ${key}\n` +

package/dist/commands/make-density/density-generator.js

@@ -0,0 +1,180 @@
+import { createReadStream, existsSync, readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { createGunzip } from 'node:zlib';
+// Which parser a filename selects. BAM/CRAM/SAM are named so the refusal can
+// say what to do instead, rather than falling into the unknown-extension case.
+const formats = [
+    { regex: /\.gff3?(\.b?gz)?$/i, format: 'gff3' },
+    { regex: /\.gtf(\.b?gz)?$/i, format: 'gtf' },
+    { regex: /\.vcf(\.b?gz)?$/i, format: 'vcf' },
+    { regex: /\.bed(\.b?gz)?$/i, format: 'bed' },
+];
+const alignmentFormat = /\.(bam|cram|sam)$/i;
+export function densityFormat(file) {
+    const hit = formats.find(f => f.regex.test(file));
+    if (!hit) {
+        throw new Error(alignmentFormat.test(file)
+            ? `${file} is an alignment file, which make-density cannot read. Count coverage with a tool that reads BAM/CRAM (e.g. "bamCoverage" or "samtools depth" piped to bedGraphToBigWig) and pass the result with add-track --density.`
+            : `Cannot tell what kind of file ${file} is. make-density reads GFF3, GTF, BED and VCF, plain or bgzipped.`);
+    }
+    return hit.format;
+}
+/**
+ * The reference name and 0-based start of one record, or undefined for a line
+ * that contributes nothing: a header, a directive, a short line, or — in GFF3 —
+ * a child feature, whose start would count its parent's locus a second time.
+ * A GTF row says whether it is a `transcript`, the record its track draws;
+ * BED and VCF have no parent link to follow, so every record counts.
+ */
+function parseRecord(line, format) {
+    const columns = line.split('\t');
+    const refName = columns[0];
+    const startsHeader = line.startsWith('#') ||
+        line.startsWith('track ') ||
+        line.startsWith('browser ');
+    if (startsHeader || refName === undefined || refName === '') {
+        return undefined;
+    }
+    if (format === 'bed') {
+        const start = columns[1];
+        return start === undefined
+            ? undefined
+            : { refName, start: +start, transcript: false };
+    }
+    const start = columns[format === 'vcf' ? 1 : 3];
+    const attributes = columns[8];
+    const isChild = format === 'gff3' && attributes?.includes('Parent=');
+    return start === undefined || isChild
+        ? undefined
+        : {
+            refName,
+            start: +start - 1,
+            transcript: format === 'gtf' && columns[2] === 'transcript',
+        };
+}
+function tally(bins, key, bin) {
+    const existing = bins.get(key);
+    const perRef = existing === undefined ? new Map() : existing;
+    if (existing === undefined) {
+        bins.set(key, perRef);
+    }
+    const count = perRef.get(bin);
+    perRef.set(bin, count === undefined ? 1 : count + 1);
+}
+export async function countFeatureStarts({ file, format, binSize, chromSizes, }) {
+    // A GTF's transcripts are tallied apart from its exons and CDS rows: where a
+    // file has transcript rows they are the count, and a file with none (an
+    // exon-only GTF) counts every row.
+    const all = new Map();
+    const transcripts = new Map();
+    const unknownRefNames = new Set();
+    let records = 0;
+    let transcriptRecords = 0;
+    const source = createReadStream(file);
+    const lines = createInterface({
+        input: /\.b?gz$/i.test(file) ? source.pipe(createGunzip()) : source,
+        crlfDelay: Number.POSITIVE_INFINITY,
+    });
+    for await (const line of lines) {
+        // everything after a GFF3 ##FASTA directive is sequence, not features
+        if (line.trimEnd() === '##FASTA') {
+            break;
+        }
+        const record = parseRecord(line, format);
+        if (record && Number.isFinite(record.start)) {
+            records++;
+            transcriptRecords += record.transcript ? 1 : 0;
+            const length = chromSizes.get(record.refName);
+            if (length === undefined) {
+                unknownRefNames.add(record.refName);
+            }
+            else if (record.start >= 0 && record.start < length) {
+                const bin = Math.floor(record.start / binSize);
+                tally(all, record.refName, bin);
+                if (record.transcript) {
+                    tally(transcripts, record.refName, bin);
+                }
+            }
+        }
+    }
+    lines.close();
+    source.destroy();
+    return transcriptRecords > 0
+        ? { bins: transcripts, records: transcriptRecords, unknownRefNames }
+        : { bins: all, records, unknownRefNames };
+}
+/**
+ * bedGraph rows covering every base of every reference, in the order
+ * bedGraphToBigWig demands (`sort -k1,1 -k2,2n`): one row per counted bin,
+ * clipped to the reference's length, and one per run of empty bins between
+ * them. The empty runs are load-bearing: a bigWig's zoom levels average over
+ * the bases its rows cover, so a file that skipped them would read, zoomed out,
+ * as the mean over the bins that held something rather than over the span, and
+ * a gene desert beside a cluster would score the same.
+ */
+export function* bedGraphLines({ bins, chromSizes, binSize, }) {
+    const byName = [...chromSizes.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    for (const [refName, length] of byName) {
+        const perRef = bins.get(refName);
+        const counted = perRef
+            ? [...perRef.entries()].sort(([a], [b]) => a - b)
+            : [];
+        let cursor = 0;
+        for (const [bin, count] of counted) {
+            const start = bin * binSize;
+            const end = Math.min(start + binSize, length);
+            if (start > cursor) {
+                yield `${refName}\t${cursor}\t${start}\t0\n`;
+            }
+            yield `${refName}\t${start}\t${end}\t${count}\n`;
+            cursor = end;
+        }
+        if (cursor < length) {
+            yield `${refName}\t${cursor}\t${length}\t0\n`;
+        }
+    }
+}
+export function chromSizesLines(chromSizes) {
+    return [...chromSizes.entries()]
+        .map(([refName, length]) => `${refName}\t${length}\n`)
+        .join('');
+}
+// a `.chrom.sizes` and a `.fai` both put the name in column 1 and the length in
+// column 2, so one parser reads either
+function parseChromSizes(text, source) {
+    const sizes = new Map();
+    for (const line of text.split('\n')) {
+        const [refName, length] = line.split('\t');
+        if (refName && length !== undefined && Number.isFinite(+length)) {
+            sizes.set(refName, +length);
+        }
+    }
+    if (sizes.size === 0) {
+        throw new Error(`No reference sequences found in ${source}`);
+    }
+    return sizes;
+}
+/**
+ * The reference lengths the bigWig header needs, from an explicit
+ * `--chrom-sizes` or from the `.fai` beside an `--assembly` FASTA.
+ */
+export function resolveChromSizes({ chromSizes, assembly, }) {
+    if (chromSizes !== undefined) {
+        return parseChromSizes(readFileSync(chromSizes, 'utf8'), chromSizes);
+    }
+    if (assembly !== undefined) {
+        const fai = `${assembly}.fai`;
+        if (!existsSync(fai)) {
+            throw new Error(`No index beside ${assembly}: expected ${fai}. Make one with "samtools faidx ${assembly}", or pass --chrom-sizes instead.`);
+        }
+        return parseChromSizes(readFileSync(fai, 'utf8'), fai);
+    }
+    throw new Error('Reference lengths are required: pass --chrom-sizes <file> or --assembly <fasta> (whose .fai is read)');
+}
+export function parseBinSize(bin) {
+    const binSize = +bin;
+    if (!Number.isInteger(binSize) || binSize < 1) {
+        throw new Error(`--bin must be a positive whole number of bp, got ${bin}`);
+    }
+    return binSize;
+}