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

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
@@ -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,6 +343,14 @@ 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
@@ -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.
@@ -637,16 +654,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 +689,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
 ```