@jbrowse/cli 5.0.0-beta.11 → 5.0.0-beta.14

package/README.md

@@ -59,7 +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
+  make-density         Counts feature starts per bin into a bigWig, 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
@@ -280,7 +280,7 @@ Options:
                              displayDefaults
 
       --displayDefaults      Inline JSON merged into the track displayDefaults
-                             (labels, mouseover, filter, etc.)
+                             (labels, color, filter, etc.)
 
       --multiwig             Build a MultiQuantitativeTrack from several BigWigs
                              (in place of the positional track arg): a
@@ -311,11 +311,6 @@ 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,
@@ -335,21 +330,13 @@ text-index.
 JSON. Wrap the value in single quotes and use double quotes inside a jexl
 callback so nothing needs escaping, e.g. --color
 'jexl:feature.strand==1?"blue":"red"'. --displayDefaults takes inline JSON for
-any other appearance setting (labels, mouseover, filter).
+any other appearance setting (labels, facet, filter).
 
 --multiwig bundles several BigWigs into one MultiQuantitativeTrack, in place of
 the positional track argument: pass a comma-separated list of 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.
-
---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.
+with its own name/color/group). With --load, local list entries are copied like
+any other track file.
 
 For pairwise synteny adapters (PAF/Delta/Chain) --assemblyNames is query,target
 — the reverse of the minimap2/nucmer input order. For the multi-genome PAF
@@ -382,11 +369,8 @@ $ jbrowse add-track genes.gff3.gz --load copy --color 'jexl:feature.strand==1?"b
 # bundle several BigWigs into one MultiQuantitativeTrack (no positional track arg)
 $ 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
+# ...or from a sources.json with 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
 ```
 
 
@@ -407,9 +391,10 @@ Options:
 
 Notes:
 
-A config key JBrowse does not recognize is ignored rather than reported, so a
-misspelled slot leaves the track loading normally with the setting doing
-nothing. That is what this command is mainly for.
+A config key JBrowse does not recognize does nothing: a track, an adapter or a
+display names it on the browser console and loads without it, and a session
+snapshot drops it in silence. This command reports each one offline, before
+anyone opens the config.
 
 Two levels are reported:
 
@@ -429,7 +414,7 @@ what it cannot draw in a corner notice rather than refusing the track. This
 command runs the display's own rule list over every "marks" list in the file: an
 error where a mark draws nothing, never draws or a step cannot run, and a
 warning where a slot waits unread or the marks draw in an arrangement the author
-may not have meant. With --json each finding carries the stable "rule" id of the
+may not have meant. With --json each finding has the stable "rule" id of the
 rule that made it.
 
 Types registered by plugins are not known to this command, so they come through
@@ -703,7 +688,7 @@ sh, sort, bgzip, and tabix on the PATH.
 
 Examples:
 
-# creates input.pif.gz and input.pif.gz.tbi in the same directory
+# creates input.pif.gz and input.pif.gz.tbi in the current directory
 $ jbrowse make-pif input.paf
 
 # specify the output file, also creates output.pif.gz.tbi
@@ -726,8 +711,8 @@ $ jbrowse make-pif input.paf --threads 8
 ## jbrowse make-density
 
 ```text
-Counts feature starts per bin into a bigWig, the density sidecar a track draws
-where the region is too large to fetch its features
+Counts feature starts per bin into a bigWig, which add-track turns into a
+quantitative track of where the features are
 
 Usage: jbrowse make-density <file> [options]
 
@@ -744,25 +729,21 @@ Options:
                              --chrom-sizes
 
       --out                  Where to write the bigWig. Defaults to
-                             <file>.density.bw beside the input, which is where
-                             add-track looks for it
+                             <file>.density.bw beside the input
 
 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 have no Parent= —
+so a gene is one count rather than one per exon. GTF counts its transcript rows
+where it has any, and every row otherwise. BED and VCF have no parent link to
+follow, so every record counts.
 
-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.
+Every base is covered, empty bins as zero, so the zoomed-out summaries a bigWig
+keeps average over real counts rather than only the bins that hold something.
 
 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.
+that compute it (bamCoverage, mosdepth) already write it as a bigWig or
+bedGraph.
 
 Requires bedGraphToBigWig (UCSC) on the PATH.
 

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

@@ -1,8 +1,5 @@
 import fs from 'node:fs';
 import { adapterTypesToTrackTypeMap, fileNameOf, formats, matchFormat, resolveIndexType, sidecarCandidateNames, trackTypeForAdapter, } from '@jbrowse/add-track-core';
-import { isURL } from '../../types/common.js';
-import { densitySidecarPath } from '../shared/density.js';
-import { configManifest } from '../validate/configManifest.generated.js';
 function hasLocField(spec) {
     return 'locField' in spec;
 }
@@ -25,48 +22,6 @@ export function siblingSidecar(location, suffix) {
     const candidates = sidecarCandidateNames(location, suffix);
     return candidates.find(c => fs.existsSync(c)) ?? candidates[0];
 }
-// The adapters that declare a `densityAdapter` slot, read off the generated
-// manifest `jbrowse validate` uses. The hand-written list missed `GWASAdapter`,
-// which inherits the slot through `bedTabixConfigSchema` instead of spreading
-// `densityAdapterConfigSchemaFields`, so `--density` on a Pan-UKBB file was
-// refused by a message that listed nine adapters and not the tenth.
-const densityAdapterTypes = new Set(Object.entries(configManifest.adapters)
-    .filter(([, entry]) => entry.slots.some(s => s.name === 'densityAdapter'))
-    .map(([name]) => name)
-    .sort());
-/**
- * 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, withDensityAdapter, } from './add-track-utils/adapter-utils.js';
+import { guessTrack, guessTrackType, makeLocationProtocol, } 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';
@@ -59,7 +59,7 @@ export async function run(args) {
         },
         displayDefaults: {
             type: 'string',
-            description: 'Inline JSON merged into the track displayDefaults (labels, mouseover, filter, etc.)',
+            description: 'Inline JSON merged into the track displayDefaults (labels, color, filter, etc.)',
         },
         multiwig: {
             type: 'string',
@@ -104,10 +104,6 @@ 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,
@@ -131,20 +127,13 @@ export async function run(args) {
         'writing JSON. Wrap the value in single quotes and use double quotes inside ' +
         'a jexl callback so nothing needs escaping, e.g. ' +
         '--color \'jexl:feature.strand==1?"blue":"red"\'. --displayDefaults takes ' +
-        'inline JSON for any other appearance setting (labels, mouseover, ' +
+        'inline JSON for any other appearance setting (labels, facet, ' +
         'filter).\n\n' +
         '--multiwig bundles several BigWigs into one MultiQuantitativeTrack, in ' +
         'place of the positional track argument: pass a comma-separated list of ' +
         '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, ' +
+        'subadapter objects (each with 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 ' +
         'multi-genome PAF adapters (MultiGenomePAFAdapter, MultiGenomeIndexedPAFAdapter) it is ' +
@@ -174,11 +163,8 @@ export async function run(args) {
         '# bundle several BigWigs into one MultiQuantitativeTrack (no positional track arg)',
         '$ 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',
+        '# ...or from a sources.json with 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({
@@ -200,7 +186,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: builtAdapter, files, trackType, trackId, } = multiwig
+    const { adapter, files, trackType, trackId } = multiwig
         ? buildMultiWiggleTrack({
             sources: multiwig,
             mapLocation,
@@ -220,15 +206,6 @@ 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,
@@ -267,7 +244,7 @@ export async function run(args) {
     });
     const updatedConfig = { ...configContents, tracks };
     await loadFiles({
-        files: [...files, densityFile],
+        files,
         destDir: configDir,
         mode: load,
         subDir,

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

@@ -14,7 +14,7 @@ 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.`
+            ? `${file} is an alignment file, which make-density cannot read. Count coverage with a tool that reads BAM/CRAM (e.g. bamCoverage or mosdepth) and add its bigWig as a track.`
             : `Cannot tell what kind of file ${file} is. make-density reads GFF3, GTF, BED and VCF, plain or bgzipped.`);
     }
     return hit.format;

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

@@ -7,7 +7,6 @@ import { pipeline } from 'node:stream/promises';
 import { parseArgs } from 'node:util';
 import { printHelp, requirePositional } from '../../utils.js';
 import { describeExit, waitForProcessClose } from '../process-utils.js';
-import { densitySidecarPath } from '../shared/density.js';
 import { validateFileArgument, validateRequiredCommands, } from '../shared/validators.js';
 import { bedGraphLines, chromSizesLines, countFeatureStarts, densityFormat, parseBinSize, resolveChromSizes, } from './density-generator.js';
 export async function run(args) {
@@ -31,7 +30,7 @@ export async function run(args) {
         },
         out: {
             type: 'string',
-            description: 'Where to write the bigWig. Defaults to <file>.density.bw beside the input, which is where add-track looks for it',
+            description: 'Where to write the bigWig. Defaults to <file>.density.bw beside the input',
         },
     };
     const { values: flags, positionals } = parseArgs({
@@ -39,19 +38,17 @@ export async function run(args) {
         options,
         allowPositionals: true,
     });
-    const description = 'Counts feature starts per bin into a bigWig, the density sidecar a track draws where the region is too large to fetch its features';
-    const 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.\n\n' +
-        '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 ' +
+    const description = 'Counts feature starts per bin into a bigWig, which add-track turns into a quantitative track of where the features are';
+    const notes = 'GFF3 counts only top-level features — a line whose attributes have no ' +
+        'Parent= — so a gene is one count rather than one per exon. GTF counts its ' +
+        'transcript rows where it has any, and every row otherwise. BED and VCF ' +
         'have no parent link to follow, so every record counts.\n\n' +
+        'Every base is covered, empty bins as zero, so the zoomed-out summaries a ' +
+        'bigWig keeps average over real counts rather than only the bins that hold ' +
+        'something.\n\n' +
         '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.\n\n' +
+        'tools that compute it (bamCoverage, mosdepth) already write it as a ' +
+        'bigWig or bedGraph.\n\n' +
         'Requires bedGraphToBigWig (UCSC) on the PATH.';
     const examples = [
         '# writes genes.gff3.density.bw beside the input, in 1kb bins',
@@ -86,7 +83,9 @@ export async function run(args) {
         assembly: flags.assembly,
     });
     validateRequiredCommands(['bedGraphToBigWig']);
-    const outputFile = flags.out === undefined ? densitySidecarPath(file) : flags.out;
+    const outputFile = flags.out === undefined
+        ? `${file.replace(/\.b?gz$/i, '')}.density.bw`
+        : flags.out;
     const { bins, records, unknownRefNames } = await countFeatureStarts({
         file,
         format,
@@ -124,16 +123,5 @@ export async function run(args) {
     finally {
         rmSync(tmpDir, { recursive: true, force: true });
     }
-    // The slot lives on the indexed adapters, so a plain text file has to be
-    // bgzipped and tabix-indexed before the track can carry the sidecar
-    const indexed = /\.b?gz$/i.test(file);
-    const preset = format === 'bed' ? 'bed' : format === 'vcf' ? 'vcf' : 'gff';
-    const trackFile = indexed ? file : `${file}.gz`;
-    const indexFirst = indexed
-        ? ''
-        : `  bgzip ${file} && tabix -p ${preset} ${trackFile}\n`;
-    const nextCommand = outputFile === densitySidecarPath(file)
-        ? `Next, add the track it summarizes — a sidecar under this name is picked up automatically:\n${indexFirst}  jbrowse add-track ${trackFile} --load copy`
-        : `Next, add the track it summarizes, naming this sidecar:\n${indexFirst}  jbrowse add-track ${trackFile} --load copy --density ${outputFile}`;
-    console.log(`Created ${outputFile}: ${records} feature start(s) in ${binCount} non-empty ${binSize}bp bin(s)\n\n${nextCommand}`);
+    console.log(`Created ${outputFile}: ${records} feature start(s) in ${binCount} non-empty ${binSize}bp bin(s)\n\nNext, add it as a track of its own:\n  jbrowse add-track ${outputFile} --load copy`);
 }

package/dist/commands/make-pif/index.js

@@ -38,7 +38,7 @@ export async function run(args) {
     });
     const description = 'creates pairwise indexed PAF (PIF), with bgzip and tabix';
     const examples = [
-        '# creates input.pif.gz and input.pif.gz.tbi in the same directory',
+        '# creates input.pif.gz and input.pif.gz.tbi in the current directory',
         '$ jbrowse make-pif input.paf',
         '',
         '# specify the output file, also creates output.pif.gz.tbi',

package/dist/commands/text-index/file-list.js

@@ -31,6 +31,6 @@ export async function indexFileList(flags) {
                 prefixSize,
             }),
         });
-        console.log('Successfully created index for these files. See https://jbrowse.org/storybook/lgv/with-aggregate-text-searching/ for info about usage');
+        console.log('Successfully created index for these files. See https://jbrowse.org/storybook/lgv/aggregate-text-search/ for info about usage');
     }
 }