Static image export (@jbrowse/img)

Static exports of JBrowse 2 rendering.

Prerequisites

The tool renders from local or remote files and needs no JBrowse 2 installation. Requirements:

NodeJS v23+

Setup

Install the @jbrowse/img package from npm; with a typical Node setup this puts a jb2export command on your PATH.

npm install -g @jbrowse/img

If you are a developer and want to modify the code, see the source on GitHub

Quickstart

A multi-track human (hg19) view at the IFFO2 / ALDH4A1 locus (NCBI RefSeq genes, ClinGen gene–disease mapping, phyloP conservation, and SKBR3 nanopore reads), rendered straight from public files in a single command (--aliases reconciles the 1 / chr1 / NC_000001.10 refname styles across the files):

A multi-track hg19 view: NCBI RefSeq genes, ClinGen gene-disease mapping, phyloP conservation, and SKBR3 nanopore reads

jb2export --fasta https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz \
  --aliases https://jbrowse.org/genomes/hg19/hg19_aliases.txt \
  --gffgz https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz '{"showOnlyGenes":true}' \
  --bigbed https://jbrowse.org/genomes/hg19/clinGen/clinGenGeneDisease.bb \
  --bigwig https://hgdownload.soe.ucsc.edu/goldenpath/hg19/phyloP100way/hg19.100way.phyloP100way.bw \
  --cram https://s3.amazonaws.com/jbrowse.org/genomes/hg19/reads_lr_skbr3.fa_ngmlr-0.2.3_mapped.cram \
  --loc 1:19,190,000-19,240,000 --width 1200 --out 1.png

The '{"showOnlyGenes":true}' after the GFF is a raw-JSON per-track override (any display setting can be set this way). NCBI RefSeq GFFs have non-gene support features (region, match, biological_region) that would otherwise render as unnamed rows above the genes; showOnlyGenes restricts the track to gene/transcript features.

Basic usage

Local files

This runs on local files as a plain node script with no browser involved, using React SSR to create the SVG

## generate an indexed fasta e.g. fai file
samtools faidx yourfile.fa

## generate an indexed BAM
samtools index yourfile.bam


## simple rendering of a your local files
jb2export --fasta yourfile.fa --bam yourfile.bam --loc chr1:1,000,000-1,001,000 --out file.svg

If --out is not specified it writes SVG to stdout

Remote files

An example with remote files, human hg19 and several tracks. Note the use of --aliases, which smoothes over refname differences e.g. fasta contains 1 for chr1, and bigbed contains chr1, gff contains NC_000001.10

jb2export --fasta https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz \
  --aliases https://jbrowse.org/genomes/hg19/hg19_aliases.txt \
  --bigbed https://hgdownload.soe.ucsc.edu/gbdb/hg19/bbi/clinvar/clinvarMain.bb \
  --gffgz https://jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz \
  --bigwig https://jbrowse.org/genomes/hg19/reads_lr_skbr3.fa_ngmlr-0.2.3_mapped.bam.regions.bw \
  --loc 1:48,683,542-48,907,531 --width 1200 --out remote_files.png

ClinVar variants above NCBI RefSeq genes across a 220 kb window of hg19 chromosome 1, every file streamed from a public URL

Hosted assemblies (genomes.jbrowse.org)

--hub <name> pulls a whole assembly config from genomes.jbrowse.org, supplying the sequence, cytobands (shown in the overview ideogram), and refName aliasing in place of --fasta/--aliases/--cytobands. <name> is either a UCSC database name (hg19, hg38, mm10, ...) or a GenArk accession (GCA_.../GCF_...):

## refName aliasing comes from the hosted config: "1" resolves to chr1
jb2export --hub hg19 --loc 1:1,000,000-1,100,000 --out out.svg

## a GenArk accession
jb2export --hub GCA_964188535.1 --loc <contig>:1-100000 --out out.svg

Every track in the hosted config can be shown by its trackId with --track, which is repeatable and accepts the same display modifiers as the track-type flags (see Track modifiers):

jb2export --hub hg19 --track hg19-ncbiRefSeqCurated --track hg19-clinvarMain \
  --loc chr1:1,020,000-1,040,000 --width 1200 --out hub_tracks.png

NCBI RefSeq genes and ClinVar variants at the start of hg19 chromosome 1, both named by trackId from the hosted hg19 hub

Hosted trackIds are all prefixed with the assembly name (hg19-...), so --track fills that in for you: --track ncbiRefSeqCurated resolves to hg19-ncbiRefSeqCurated. Matching is also case-insensitive and works on a track's display name, and a token that doesn't match anything errors with the closest trackIds:

$ jb2export --hub hg19 --track clinvar ...
Error: --track "clinvar" not found in the config. Did you mean: hg19-clinvarMain,
hg19-clinvarCnv, hg19-dbSnp155ClinVar, ...?

Hosted configs also include a gene text-search index, so --loc accepts a gene name and jumps to it:

jb2export --hub hg19 --track ncbiRefSeqCurated --loc BRCA1 --width 1200 \
  --out gene_name_search.png

The BRCA1 gene, reached by typing its name

--loc still takes ordinary locstrings (chr1:1-10000, 1:1,000,000-1,100,000, or all); a name that isn't a locstring is looked up in the index and the view jumps to the top hit.

The list subcommand prints hub names and trackIds:

## every assembly on genomes.jbrowse.org (name — organism — description)
jb2export list

## every track in a hub (trackId, type, name)
jb2export list hg19

## just the tracks whose id or name matches a filter
jb2export list hg19 refseq

--config also accepts a URL, so you can point at any hosted JBrowse config.json the same way; relative data URIs inside it resolve against the config's location, exactly as they do in JBrowse web.

Output formats

The output format is chosen by the extension of --out: .svg, .png, or .pdf. With no --out, SVG is written to stdout. PNG and PDF use rsvg-convert, so you will need to install it on your system, e.g. with sudo apt install librsvg2-bin.

## SVG (vector)
jb2export --fasta yourfile.fa --bam yourfile.bam --loc chr1:1,000,000-1,001,000 --out file.svg

## PNG
jb2export --fasta yourfile.fa --bam yourfile.bam --loc chr1:1,000,000-1,001,000 --out file.png

## PDF
jb2export --fasta yourfile.fa --bam yourfile.bam --loc chr1:1,000,000-1,001,000 --out file.pdf

By default the pileup, coverage, and hic layers are rasterized into the SVG to keep file sizes down. Pass --noRasterize to render everything as SVG vectors instead (larger files, fully editable in vector tools).

Converting SVG to PNG manually

The tool runs rsvg-convert automatically when --out ends in .png. Alternatively, you can convert an SVG yourself:

## with inkscape

sudo apt install inkscape
inkscape --export-type png --export-filename out.png -w 2048 out.svg

## with librsvg

sudo apt install librsvg2-bin
rsvg-convert -w 2048 out.svg -o out.png

## with imagemagick

sudo apt install imagemagick
convert -size 2048x out.svg out.png

Track gallery

The examples below are reproducible with the bundled volvox data (and a couple of public remote files); see Track modifiers for the full list of per-track options used here.

Alignments tracks

A --bam/--cram track renders a coverage histogram over a read pileup, with mismatches highlighted. Reproducible with the bundled volvox alignments:

jb2export --fasta data/volvox/volvox.fa --bam data/volvox/volvox-sorted.bam \
  --loc ctgA:1-20000 --width 1200 --out alignments_pileup.png

Track modifiers color, sort, and group the reads. sort:base orders the pileup by the base each read has at the center position: here, HG008-T PacBio HiFi reads over the CUZD1 gene, where the sort pulls every read with a ~1.8 kb somatic deletion into one contiguous band so the heterozygous deletion (and its coverage dip) pops out of the pileup:

jb2export --hub hg38 --track hg38-ncbiRefSeqCurated height:55 \
  --bam https://jbrowse.org/demos/cgiab/HG008-T_chr10_CUZD1_deletion.bam sort:base height:420 \
  --loc chr10:122,831,700-122,840,800 --width 1200 \
  --out alignments_readgroup.png

HG008-T PacBio HiFi reads over CUZD1, sorted by the base at the center position so the reads with a ~1.8 kb somatic deletion cluster into one band

facet=tags.HP splits the pileup into one stacked sub-track per haplotype. This HG002 ultralong-ONT example (hg19, streamed from the GIAB FTP) groups and colors by the HP tag: the heterozygous deletion shows in one haplotype and not the other:

jb2export --fasta https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz \
  --bam https://jbrowse.org/demos/hg002/HG002.ONTrel2.HP.hs37d5.demo_slices.bam facet=tags.HP color.field=tags.HP height:400 \
  --loc 1:63,005,675-63,007,432 --width 1200 --out alignments_haplotype.png

Reads grouped and colored by haplotype (HP tag), showing a heterozygous deletion in one haplotype

baseColor:methylation paints per-base CpG methylation calls from a modified-base (MM/ML) BAM/CRAM: methylated cytosines red, unmethylated blue. This COLO829 nanopore CRAM (hg38, streamed from the ONT open-data S3) with the UCSC CpG-island BED on top shows the methylated flanks giving way to the unmethylated island cores, read against the annotated island boundaries. showLegend=true draws the color key, worth adding to any export whose coloring is not the default one: the app leaves it off, where a reader can open the track menu instead.

jb2export --fasta https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
  --aliases https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt \
  --bedgz https://jbrowse.org/ucsc/hg38/cpgIslandExt.bed.gz index:https://jbrowse.org/ucsc/hg38/cpgIslandExt.bed.gz.csi \
  --bam https://jbrowse.org/demos/ont/COLO829_tumor.ht.chr20_18.5Mb.bam baseColor:methylation showLegend=true height:350 \
  --loc chr20:18,503,000-18,509,000 --width 1200 --out methylation.png

COLO829 nanopore reads colored by per-base CpG methylation over a CpG island

sashimi:auto overlays splice-junction arcs on the coverage band, sized by the number of reads spanning each junction: the standard RNA-seq splice view. coverageHeight= makes the coverage/sashimi band tall so the arcs are legible, and scales.y.type=log is what puts every exon on the plot: RNA-seq depth here spans three orders of magnitude, so on a linear axis the tallest exon is the only one with any height and the arcs land over a flat line. This strand-specific paired-end RNA-seq (hg19, public) over B2M shows the long first intron as one big arc and the closely-spaced downstream exons as smaller arcs, with the spliced read pairs (green mate lines) below:

jb2export --hub hg19 --track hg19-ncbiRefSeqCurated height:90 \
  --bam https://s3.amazonaws.com/jbrowse.org/genomes/hg19/paired_end_rnaseq/Pairend_StrandSpecific_51mer_Human_hg19.bam sashimi:auto coverageHeight=170 scales.y.type=log featureHeight:super-compact height:420 \
  --loc B2M --width 1400 --out sashimi_junctions.png

RNA-seq sashimi plot over B2M: splice-junction arcs on the coverage band sized by junction read depth, over the spliced read pileup

This 1000 Genomes ONT sample (HG00151, long reads streamed from the 1000G-ONT S3) over a ~1.2 kb inversion on chr1 draws the same event three ways:

arcs:up / arcs:down draws a read-connection arc for every split (supplementary) read, linking its two alignment segments, the arc color encoding the junction's orientation: here the two breakpoints joined by purple inversion-junction arcs, where a read's two halves map in opposite orientations.
unit=chain chains each read's split segments, so the same inversion reads in the pileup itself: a blue reverse-strand core between red forward-strand flanks, spanning breakpoint to breakpoint.
facet=split puts those reads in their own labelled section above the flat background pileup.

jb2export --hub hg38 \
  --bam https://jbrowse.org/demos/ont/HG00151-ONT-hg38.chr1_inversion.bam arcs:down unit=chain facet=split coverageHeight=80 height:560 \
  --loc chr1:197,786,900-197,789,700 --width 1400 --out sv_read_arcs.png

HG00151 ONT long reads over a ~1.2 kb chr1 inversion, grouped on SA-tag presence: the split reads sit in a separate section under the purple junction arcs, chained so a blue reverse-strand core runs between red forward-strand flanks

Breakpoint split views

Both sides of a junction, stacked, with a curve per read that leaves one panel and arrives in the other. Everything above draws an SV in reference coordinates; this draws the two loci it joins.

Repeating --loc stacks a panel; whitespace inside one --loc adds a window to that panel — the meaning a space already has for a linear view. So the two-breakend case is two bare --loc flags with no shell quoting, and a quoted --loc is how a panel takes two windows.

A connector is drawn dashed when the read holding it has a supplementary alignment at a locus that is not on screen: the view is reporting an incomplete picture, and the fix is to give it the missing panel. COLO829's der(3) is a closed cycle over three chromosomes, so the junction below needs a chr10 panel between the two it appears to join, and with it every connector in the figure is solid.

One render per sample, and the control is the other render. A somatic call is the difference between the tumour and its matched normal, so the figure that argues it is two of these side by side: the same --loc list and the same --width, one --track each. The connecting curves are drawn per track, so they fill the tumour render and the normal render has none.

jb2export breakpoint --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829_tumor_ont height:130 force:true featureHeight:super-compact \
  --loc chr3:25,358,511-25,359,711 --loc chr10:58,716,962-58,718,162 \
  --loc chr12:72,272,512-72,273,712 --width 1000 --out sv_review_tumor.png

The three loci of the COLO829 melanoma line's der(3), chr3 then chr10 then chr12, in the tumour nanopore reads. Every connecting curve is solid

Then the same command with the other sample's track:

jb2export breakpoint --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly hg38 \
  --track COLO829BL_normal_ont height:130 force:true featureHeight:super-compact \
  --loc chr3:25,358,511-25,359,711 --loc chr10:58,716,962-58,718,162 \
  --loc chr12:72,272,512-72,273,712 --width 1000 --out sv_review_normal.png

The three der(3) loci in the matched normal, with no connecting curves in any panel

Both commands take these two modifiers:

force:true is there because the chr3 panel is 1.2 kb of 200x nanopore, which is over the byte gate; without it that panel draws the gate's message instead of reads.
featureHeight:super-compact draws each read 1 px tall, which is what keeps six pileups on one screen.

A reconstructed allele is an assembly, so it is a third render. Once the junctions have been resolved into a derivative contig, the three loci above stop needing three panels: they are one axis, in order. That contig is an assembly in the same config, so the only thing that changes is which --assembly is named.

jb2export --config https://jbrowse.org/demos/cancer_sv/config.json \
  --assembly der3_RARB_BICC1_TRHDE --track der3_segments height:128 \
  --track reads_vs_der3 height:440 --loc der3_RARB_BICC1_TRHDE:1-39,549 \
  --width 1000 --out sv_review_derivative.png

The COLO829 der(3) allele as a single 39.5 kb contig: 32.7 kb of chr3, 199 bp of chr10 and 183 bp of chr12 end to end, with the spanning reads running through every junction

Putting the three beside each other is your docs' job; jb2export does not compose them.

To do that for a whole callset rather than one junction, jb2export batch renders one image per row of a BEDPE. See the SV callset review tutorial, and jb2export batch --help.

More alignment recipes (see Track modifiers for all options):

## color by splice strand (XS tag), sort by haplotype (HP tag)
jb2export --fasta ref.fa --bam reads.bam color.field=tags.XS sort:tag:HP --loc chr1:1-10000

## color by base modifications (MM/ML tags) in super-compact layout
jb2export --fasta ref.fa --bam reads.bam baseColor:modifications featureHeight:super-compact \
  --loc chr1:1-10000

## methylation over reads tinted by haplotype, in two quiet colors
jb2export --fasta ref.fa --bam reads.bam color.field=tags.HP color.domain=1,2 color.range=#d9c9a3,#b7c4b1 \
  baseColor:methylation showLegend=true --loc chr1:1-10000

## color by insert size + orientation to highlight structural variants
jb2export --fasta ref.fa --bam reads.bam color:insertSizeAndOrientation --loc chr1:1-10000

## read-cloud SV view — the read cloud overlays the coverage band, so use
## coverageHeight to make the panel tall (NOT readConnectionsHeight, which only sizes
## the regular up/down arcs panel). The read cloud disappears if showCoverage=false.
jb2export --fasta ref.fa --bam reads.bam arcs:cloud coverageHeight=300 \
  readConnectionsLineWidth=2 height:600 --loc chr1:1-50000

## view as pairs / link supplementary alignments: mates and split segments of one
## read share a row, joined by a connecting line. showBezierConnections=true is
## the separate curved-connector overlay and leaves the layout an ordinary pileup.
## Add both to curve the connectors that cross between displayed regions, which
## the per-region line pass cannot draw.
jb2export --fasta ref.fa --bam linked.bam unit=chain --loc chr1:1-50000

BigWig / quantitative tracks

--loc all shows the full assembly, and several bigwig plotting options help draw a bigwig genome-wide.

This logscale, manual-minmax example plots the SKBR3 breast-cancer cell line's read coverage genome-wide (hg19, public bigwig), where the amplifications and deletions of the cancer karyotype stand out:

jb2export --loc all --fasta https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz \
  --bigwig https://jbrowse.org/genomes/hg19/reads_lr_skbr3.fa_ngmlr-0.2.3_mapped.bam.regions.bw scales.y.type=log mark=point resolution=100 height:400 color:purple scales.y.domainMin=1 scales.y.domainMax=1024 \
  --width 1900 --out skbr3_cov.png

SKBR3 cell-line read coverage genome-wide, log scale, showing cancer amplifications and deletions

The axis clips outliers by default, stopping short of a spike that would flatten the rest of the view; scales.y.domainQuantile=1 follows the extremes instead:

jb2export --loc all \
  --bigwig coverage.bw scales.y.domainQuantile=1 mark=point resolution=100 height:400 color:purple \
  --assembly hg19 \
  --config data/config.json

MultiWiggle (many BigWigs in one track)

--multiwig aggregates many BigWig files into a single multi-row MultiQuantitativeTrack, where each subtrack shares one autoscale so the rows are directly comparable. Its argument is either a comma-separated list of BigWig files (local paths or URLs), or a .json file holding an array (of plain BigWig paths/URLs, or of subadapter objects that give each row its own name, color, and group):

## quick shorthand: a comma-separated file list, one row per file
jb2export --hub hg38 --multiwig a.bw,b.bw,c.bw height:300 --loc GAPDH --out multi.png

## curated rows: a JSON sources file (name/color/group per subtrack)
jb2export --hub hg38 --multiwig sources.json height:520 --loc GCG --out multi.png

This example renders the CATlas single-cell ATAC accessibility-by-cell-type data (Zhang et al 2021): 16 human cell types, each a BigWig, wired up with per-row labels/colors/groups in data/scatac_catlas.json, over the GCG (glucagon) locus. The Alpha (glucagon) row (the pancreatic cell type that expresses GCG) shows strong open chromatin across the gene while the other 15 cell types stay quiet on the shared scale, a clean readout of cell-type-specific chromatin accessibility at a marker gene:

jb2export --hub hg38 --track hg38-ncbiRefSeqCurated height:60 \
  --multiwig data/scatac_catlas.json 'name:CATlas single-cell ATAC (accessibility by cell type)' height:440 \
  --loc chr2:162,000,000-162,300,000 --width 1400 --out scatac_multiwiggle.png

CATlas single-cell ATAC accessibility across 16 cell types over the GCG locus, with the Alpha (glucagon) row showing cell-type-specific open chromatin

Variant tracks

A --vcfgz track draws each variant with its reference-to-alternate change. Reproducible with the bundled volvox VCF:

jb2export --fasta data/volvox/volvox.fa \
  --vcfgz data/volvox/volvox.filtered.vcf.gz --loc ctgA:1-20000 --width 1200 \
  --out variants.png

A variant track drawing each SNV with its reference-to-alternate change

Multi-sample variant matrix

A VCF with many samples renders as a genotype matrix (one row per sample, each alt genotype painted over the reference background) with the display:multivariant modifier (the LinearMultiSampleVariantDisplay); display:multivariantmatrix draws the same display in equal-width columns. This example draws the 1000 Genomes phase 3 chr11 callset (2,504 samples) over the HBB β-globin locus, with the NCBI RefSeq gene track (via --hub/--track) for context. Common variants read as solid vertical bands, rarer ones as sparse speckle:

jb2export --hub hg19 --track hg19-ncbiRefSeqCurated \
  --vcfgz https://jbrowse.org/genomes/hg19/1000genomes/ALL.chr11.phase3_v5b.HBB_5.2-5.3Mb.vcf.gz display:multivariant height:450 force:true \
  --loc chr11:5,246,000-5,251,000 --width 1200 --out multisample_variants.png

The 1000 Genomes phase 3 chr11 callset (2,504 samples) as a multi-sample genotype matrix over the HBB locus, with the NCBI RefSeq gene track above

Hi-C tracks

A --hic track draws the contact matrix as a triangular heatmap. This example streams the public hg19 demo .hic and shows the TAD structure along chr1, with the NCBI RefSeq gene track (via --hub/--track) on top for context:

jb2export --hub hg19 --track hg19-ncbiRefSeqCurated \
  --hic https://jbrowse.org/genomes/hg19/intra_nofrag_30.hic height:400 \
  --loc 1:2,500,000-12,500,000 --width 1200 --out hic.png

Hi-C contact matrix as a triangular heatmap showing TAD structure along hg19 chr1

color:viridis on a --hic track names the ramp the counts run across, any scheme HicColor takes, and color.scale=log places them on it by their log2.

Gene tracks and the reference sequence

Feature tracks (--gffgz, --bigbed, --bedgz, or a hosted --track) render their glyphs with labels, and --refseq adds the assembly's reference-sequence track. Zoomed to base level, it shows the DNA bases and the six-frame translation (green start codons, red stops). This human example zooms into a TP53 intron/CDS boundary so the gene track's structure reads at base level: the intron thins to a connector line, the coding exon begins as a solid CDS block, and that block edge lines up with a specific reference base and reading frame. showOnlyGenes keeps the RefSeq track to its gene features:

jb2export --hub hg38 \
  --track hg38-ncbiRefSeqCurated height:60 '{"showOnlyGenes":true,"geneGlyphMode":"longestCoding"}' \
  --refseq --loc chr17:7,675,018-7,675,098 --width 1500 --out gene_track.png

A TP53 intron/CDS boundary at base level: the reference sequence's DNA bases and six-frame translation above the NCBI RefSeq gene track, whose CDS exon block begins where the intron connector ends

Themes

--themeName selects a palette — default, stock or minimal — and --themeMode draws it light or dark. The names from before those were separate — darkStock, lightMinimal and the rest — still work.

jb2export --hub hg38 --track hg38-ncbiRefSeqCurated height:100 \
  --track hg38-phyloP100way height:140 --loc chr10:87,860,000-87,975,000 \
  --themeName stock --themeMode dark --width 1200 --out dark_theme.png

The hg38 PTEN locus: NCBI RefSeq genes over phyloP conservation, rendered with the stock palette drawn dark

Track modifiers

Per-track settings use a colon-based syntax that follows the track file argument, e.g. --bam reads.bam color:strand height:400. This is the full list of named modifiers. Any other display setting is a slot write in the slot's own spelling.

Modifiers are grouped below by the track types they apply to. Passing one to a track type it does not apply to (say sashimi:up on a BigWig) prints a warning naming the types it does work on. A track whose display none of these target (GWAS, MAF, LD, marks, synteny, sequence) takes only the all-tracks modifiers and slot writes.

A modifier value the modifier can't use — arcs:upp, height:8o, force:ture — is an error, not a warning: the tool writes one figure and exits, so a warning would scroll past and leave you with a wrong image. The force modifier also reads bare, so force on its own means force:true.

All tracks

Modifier	Example	Description
`height:N`	`height:400`	Track height in pixels
`force:true`	`force:true`	Render even if region is too large
`display:value`	`display:multivariant`	Pick a non-default display for the track (see below)
`name:label`	`name:"Tumor"`	Track label (defaults to the filename)
`index:path`	`index:reads.bam.csi`	Index file, when it isn't a sibling of the data file

A track is identified by its filename, so two inputs sharing one — --bam tumor/sample.bam --bam normal/sample.bam — would both be labelled sample.bam. Both render, but pass name: to tell them apart in the figure.

With no index:, a local file's index is whichever of these siblings is actually there, opened as the type it is:

Spelling	Written by
`<file>.tbi`, `<file>.bai`, `<file>.crai`	samtools, tabix
`<file>.csi`	htslib, for a reference over 512 Mb and on request at any size
`reads.bai` beside `reads.bam`	Picard, GATK

A remote file is not probed, since checking costs a request, so a hosted .csi still wants an explicit index:.

By default each track uses its primary display. display:value selects an alternate one. These friendly aliases are recognized (any other value is passed through verbatim as a display state-model name):

`display:` value	Selected display	Use
`marks`	`LinearMarkDisplay`	bars, points, spans, text and links you declare
`multivariant`	`LinearMultiSampleVariantDisplay`	multi-sample VCF genotype matrix (rows)
`multivariantmatrix`	`LinearMultiSampleVariantDisplay`, `variantLayout: 'columns'`	the same, one equal-width column per variant

Alignment tracks (BAM/CRAM)

Reads & coloring:

Modifier	Example	Description
`color:field`	`color:strand`	Color reads by a field (see fields below), or paint them all one CSS color
`baseColor:field`	`baseColor:methylation`	Draw a per-base layer over the reads, whatever `color:` fills them with (see fields below)
`sort:type` or `sort:type:tag`	`sort:strand`, `sort:tag:RG`	Sort reads (`position`, `strand`, `basePair`, or `tag:<TAG>`)

Which reads are drawn. These filter before the coverage pipeline as well as before layout, so a filter that removes reads removes them from the coverage band too.

The last four name a read category and take one vocabulary: only keeps that category, exclude drops it, and omitting the modifier leaves it alone. They are AND-ed with each other and with the masks above. The SV export is svSignal:only. Passing all is accepted and stores nothing, which lets a script pass a category through from a variable that may be empty. The properPairs: modifier of 5.0 betas is an error naming svSignal:only.

Modifier	Example	Description
`flags:include:exclude`	`flags::SECONDARY,DUP`	SAM flag masks, `samtools -f` then `-F`. Each half is a number or samtools' flag names, comma-separated (`PAIRED`, `PROPER_PAIR`, `UNMAP`, `MUNMAP`, `REVERSE`, `MREVERSE`, `READ1`, `READ2`, `SECONDARY`, `QCFAIL`, `DUP`, `SUPPLEMENTARY`). Either half may be empty to leave that mask as the track's config set it
`mapq:N`	`mapq:20`	Keep only reads with a mapping quality of at least N, `samtools -q`. A read whose mapping quality is unavailable (255) is dropped
`filterTag:TAG:value`	`filterTag:HP:1`	Keep only reads whose tag has this value. Repeatable, and every one must pass
`svSignal:only\|exclude`	`svSignal:only`	SV evidence, and the rest of the read's pair in the same window: a split read, an insertion or deletion of 50 bp or more, or a paired read the aligner did not call concordant (no 0x2, a mate unmapped or on another chromosome, or a pair not facing FR). `mapq:` judges each read alone
`split:only\|exclude`	`split:only`	Reads the aligner gave a supplementary segment (SAM flag 0x800), read off the SA tag
`singletons:only\|exclude`	`singletons:exclude`	Reads whose mate and supplementary segments are all outside the window
`spliced:only\|exclude`	`spliced:only`	Reads whose CIGAR has a reference skip (N) — an intron, in RNA-seq

Overlays & subtracks:

Modifier	Example	Description
`arcs:mode`	`arcs:cloud`	Read-connection arcs / read-cloud panel (`off`, `up`, `down`, `cloud`)
`sashimi:mode`	`sashimi:up`	Sashimi splice-junction arcs (`off`, `up`, `down`, `auto`)

Layout & sizing:

Modifier	Example	Description
`featureHeight:preset\|N`	`featureHeight:super-compact`, `featureHeight:4`	Per-read height (spacing between reads is derived from it). Presets: `normal` (7px), `compact` (3px), `super-compact` (1px)

Settings written as slots, in the display's own spelling:

Write	Description
`facet=strand`	Group reads into in-track stacked sections: `strand`, `firstOfPairStrand`, `pairOrientation`, `pairing`, `split`, `spliced`, `mapq`, `tags.HP`
`unit=chain`	What one row stands for: a `read`, or its mate and split segments chained
`showLegend=true`	Draw the color key. Off by default in the app, where the reader can open the track menu instead
`showSoftClipping=true`	Show soft-clipped bases
`showCoverage=false`	Hide the coverage subtrack
`showPileup=false`	Hide the pileup; with `coverageHeight`, a coverage-only view
`coverageHeight=200`	Height of the coverage subtrack (also the height of the read-cloud overlay)
`readConnectionsHeight=120`	Height of the paired-arcs panel, only for `arcs:up` / `arcs:down`
`readConnectionsLineWidth=2`	Stroke width for read-connection arcs and lines
`sashimiArcsHeight=120`	Height of the sashimi arc band
`minSashimiScore=3`	Minimum reads a splice junction needs before its arc is drawn
`arcColor=insertSize`	Read-connection arc coloring (`insertSizeAndOrientation`, `insertSize`, `pairOrientation`)
`maxHeight=4000`	Row cap for the pileup, in pixels. Raise it when the export shows the "Max height reached" notice

Available color: fields, except tags.<TAG>, which is a color.field= write. Anything else is a CSS color, painting every read with it:

Field	Description
`strand`	Forward/reverse strand
`firstOfPairStrand`	Strand of the first read in the pair
`mapq`	MAPQ
`insertSize`	Paired-end insert size
`pairOrientation`	Paired-end orientation
`insertSizeAndOrientation`	Combined insert size + orientation
`mateRefName`	Reference the mate landed on
`tags.<TAG>`	Color by any BAM tag, as `color.field=tags.HP`

Available baseColor: fields:

Field	Description
`modifications`	Base modifications via MM/ML tags
`methylation`	CpG methylation via MM/ML tags
`bisulfite`	Methylation from C→T conversion, no MM/ML tags needed
`baseQuality`	Per-base quality
`base`	Per-base letters

Feature tracks (GFF3/BED/BigBed) and VCF tracks

These share one display base, so every modifier below applies to both. facet=<field> stacks the track into one labelled section per value: strand, an attribute, or a dotted path such as INFO.SVTYPE. color.field=<attribute> colors by one.

Modifier	Example	Description
`color:value`	`color:magenta`	Glyph fill: any CSS color, or `strand` to color by feature strand (tomato forward, cornflowerblue reverse)
`featureHeight:preset`	`featureHeight:compact`	Display mode (`normal`, `compact`, `super-compact`)
`heightMode:<fixed\|grow\|fit>[:N]`	`heightMode:fit:200`	Track-height strategy: `fixed` scrolls to see all features, `grow` resizes the track to fit every feature, `fit` shrinks glyphs so every row fits without scrolling; an optional number sets the track height too

BigWig tracks

A BigWig's score axis is the scales.y setting, which also applies to a BAM/CRAM track's coverage band, where scales.y.type=log is usually what an RNA-seq figure wants. mark names how the scores draw: bar, point, line or span.

Write	Description
`scales.y.domainMin=0` `scales.y.domainMax=100`	Manual score range
`scales.y.type=log`	Scale type (`linear`, `log` or `symlog`)
`scales.y.grid=true`	Draw gridlines
`mark=point`	`bar`, `point`, `line` or `span`
`resolution=100`	BigWig resolution multiplier
`color:purple`	Fill color (any CSS color)

Two tracks read against each other need one axis, and an image has no menu to open, so give both the same scales.y.autoscaleGroup and they share a domain:

jb2export --fasta ref.fa \
  --bigwig tumor.bw scales.y.autoscaleGroup=cov height:120 \
  --bigwig normal.bw scales.y.autoscaleGroup=cov height:120 \
  --loc chr17:7,660,000-7,690,000 --out pair.svg

Any display setting (`slot.path=value`)

A modifier written slot.path=value sets that slot of the track's display, so every setting in the config docs is reachable without a modifier of its own. Paths nest with dots. A path into a setting, such as color.domain, changes that one member and keeps the rest of what the track's config or a named modifier gave the setting, in whatever order the modifiers come:

## a numeric tag on a color ramp
jb2export --fasta ref.fa --bam reads.bam color.field=tags.NM color.scale=linear \
  color.range=white,darkred --loc chr1:1-10000 --out out.svg

## haplotype in two declared colors, methylation over it, a log coverage axis
jb2export --fasta ref.fa --bam reads.bam color.field=tags.HP color.domain=1,2 \
  color.range=#d9c9a3,#b7c4b1 baseColor:methylation scales.y.type=log \
  --loc chr1:1-10000 --out out.svg

true and false are booleans and a number is a number
a comma makes a list, and a trailing comma a list of one: color.range=tan,
a digit segment indexes a list, so color.range.0=tan changes the first color of a range and marks.1.encoding.color.value=red the second mark of a declared plot, where color.range=tan,teal says what the whole range is. An index has to be one the list already reaches, so fill 0 before 1. A list written from nothing reads better as one JSON modifier than as a path per member
a jexl: item keeps the commas inside its own brackets and quotes: filter=jexl:get(feature,'score')>5, is a list of one filter
a location keeps the commas grouping its digits: clusterRegion=chr2:135,787,850-135,876,467 is one region
a slot the display does not declare, or a key its object refuses, fails the export with the display's own message

Declaring what to draw (`display:marks`)

display:marks opens the track's mark display, which draws the marks you declare instead of the glyphs its track type would: a list of bars, points, spans, text or links, each naming which feature fields feed which channel. It opens over a BAM, CRAM, VCF, GFF3, BED, BigBed, BigWig or MultiWiggle track — everything but --hic — so what differs between them is only which fields answer. A read's score is its MAPQ; a variant has its quality as QUAL and no score at all, so a mark over a VCF names the field it wants; a BigWig past its raw section answers a zoom level's mean as score, with minScore and maxScore beside it.

A whole plot is a list of objects, so state it as one JSON modifier — the same shape the track's config or a session spec would hold. Here one BigWig draws three marks in one plot: each bin's mean as bars, and its least and greatest value as points.

jb2export --fasta ref.fa --bigwig conservation.bw display:marks height:300 \
  '{"marks":[{"mark":"bar","encoding":{"y":"score","color":{"value":"#9aa89a"}}},{"mark":"point","encoding":{"y":"minScore","color":{"value":"#3c7ea8"}}},{"mark":"point","encoding":{"y":"maxScore","color":{"value":"#c1553b"}}}]}' \
  --loc chr1:1-100000 --out out.svg

A mark has a transform list run before it draws, which nests the same way — a binned count is two steps, and the aggregate's ops a list inside the second:

jb2export --fasta ref.fa --gffgz genes.gff.gz display:marks height:160 \
  '{"marks":[{"mark":"bar","encoding":{"y":"count"},"transform":[{"type":"bin","step":100000},{"type":"aggregate","groupby":["start","end"],"ops":[{"op":"count"}]}]}]}' \
  --loc chr1:1-10,000,000 --out density.svg

A path changes one mark of a list, where the JSON states the list whole. So a track whose config already declares the plot takes marks.1.encoding.color.value=red to repaint its second mark and leave the rest alone, the way color.domain= edits one member of a color object — and marks.2 before anything has written marks.0 and marks.1 is an error rather than a list with holes in it.

A mark the display cannot draw as declared — a bar naming no y, or a y the data does not have — fails the export with the rule the display itself states, rather than writing a picture of an empty plot.

Raw display settings (JSON)

A modifier that starts with { is parsed as JSON. Each key states its setting whole, the way a session spec does, so a color object here replaces the one the track's config wrote — which is what makes it the readable way to state a list of objects such as marks, and the only way to write a value a path cannot, such as a color with commas of its own. Use compact JSON (a single shell token, no spaces):

jb2export --fasta ref.fa --bam reads.bam '{"color":{"range":["rgb(217,201,163)"]}}' \
  color.field=tags.HP --loc chr1:1-10000 --out out.svg

Comparative views

Compare two assemblies (dotplot / synteny)

Two assemblies can be compared with the dotplot and synteny subcommands. The primary assembly is supplied with --fasta/--loc (as usual) and the second with --fasta2/--loc2. The alignment between them is a comparison track (--paf, --delta, --chain, or --blasttab); the query side of that file is the first assembly and the target side is the second.

The examples below use the public yeast comparison (S. cerevisiae R64 vs the YJM1447 strain) and reproduce as-is with network access.

A whole-genome dotplot: every query contig on x, every target contig on y. --autoDiagonalize reorders the target contigs so the main alignment forms a clean diagonal:

jb2export dotplot \
  --fasta https://s3.amazonaws.com/jbrowse.org/genomes/yeast/r64_vs_yjm1447/yjm1447.fa \
  --fasta2 https://s3.amazonaws.com/jbrowse.org/genomes/yeast/r64_vs_yjm1447/r64.fa \
  --paf https://s3.amazonaws.com/jbrowse.org/genomes/yeast/r64_vs_yjm1447/r64_vs_yjm1447.paf \
  --autoDiagonalize --width 1100 --out yeast_dotplot.png

Whole-genome dotplot of two yeast assemblies (R64 vs the YJM1447 strain)

A linear synteny ribbon between one chromosome in each assembly (here YJM1447 chr I vs R64 chr I, accession NC_001133.9). --drawCurves renders the ribbon as a smooth bezier instead of straight trapezoids:

jb2export synteny \
  --fasta https://s3.amazonaws.com/jbrowse.org/genomes/yeast/r64_vs_yjm1447/yjm1447.fa \
  --loc I \
  --fasta2 https://s3.amazonaws.com/jbrowse.org/genomes/yeast/r64_vs_yjm1447/r64.fa \
  --loc2 NC_001133.9 \
  --paf https://s3.amazonaws.com/jbrowse.org/genomes/yeast/r64_vs_yjm1447/r64_vs_yjm1447.paf \
  --drawCurves --width 1400 --out yeast_synteny.png

Linear synteny ribbon between YJM1447 chr I and R64 chr I

Omitting --loc/--loc2 shows the whole assembly on that axis (note: dotplot ignores --loc and always shows the whole genome). --autoDiagonalize and --drawCurves are the CLI shortcuts for the busiest-comparison knobs; the full set is available via --spec (see the table below). Run jb2export dotplot --help for the full list of comparative options.

Multi-way synteny (three or more assemblies)

Stack any number of assemblies straight from the command line: repeat the assembly flag for each one and place each alignment file between the two assemblies it compares. Assemblies stack top-to-bottom in the order written, and each synteny file becomes the ribbon for the gap it sits in. No config or spec JSON is required.

Use --chromSizes instead of --fasta for a whole-genome comparison: it builds the assembly from a chrom.sizes file (two tab-separated columns, name<TAB>length), skipping the multi-GB sequence a genome-wide dotplot never draws.

So the flags alternate, and each one's position is what it means:

--chromSizes a.chrom.sizes    assembly 1, the top row
--paf        a_vs_b.paf       the ribbon between rows 1 and 2
--chromSizes b.chrom.sizes    assembly 2
--paf        b_vs_c.paf       the ribbon between rows 2 and 3
--chromSizes c.chrom.sizes    assembly 3, the bottom row

which as a command is:

jb2export synteny \
  --chromSizes a.chrom.sizes \
  --paf a_vs_b.paf \
  --chromSizes b.chrom.sizes \
  --paf b_vs_c.paf \
  --chromSizes c.chrom.sizes \
  --out synteny.svg

Per-assembly options ride on the assembly flag as key:value modifiers, e.g. --fasta a.fa loc:chr1 aliases:a.aliases.txt. The busy-comparison knobs are flags:

Flag	Effect
`--autoDiagonalize`	Reorders each lower assembly's chromosomes for least overlap
`--minAlignmentLength`	Hides alignments shorter than N bp — the main de-spaghetti knob
`--colorBy query`	Tints each ribbon by its query chromosome
`--opacity`	Ribbon opacity (0–1); lower values reveal overlap density
`--drawCurves`	Bezier ribbons instead of straight trapezoids
`--levelHeights`	Per-level pixel height (comma-separated, e.g. `300,300`)

Query vs. target orientation. PAF/BLAST list the query first, so the assembly written above the alignment is the query. A chain/delta liftover maps target→query (a UCSC targetToQuery.over.chain), so there the assembly above is the target. jb2export handles this per format automatically: just write the assemblies in stacked order.

Alternatively, drive the view from a session-spec JSON with --spec (assemblies and comparison tracks supplied via --config). The spec is the same shape used by the JBrowse Web URL &session=spec- parameter, so JSON copied out of a browser URL works directly: see URL query parameter API for the full format. tracks is one sub-array per level (the gap between adjacent views); the subcommand is optional since the render mode comes from the spec's view type.

jb2export --config jbrowse.json --spec spec.json --out synteny.svg

Without a --spec, synteny --config stacks the config's assemblies in the order they are listed and places each SyntenyTrack by its assemblyNames: a pairwise track lands in the one gap between the two genomes it names, and a track listing three or more (a MultiGenomePAFAdapter or MCScanBlocksAdapter file covering N genomes, as built in the all-vs-all and multiway synteny tutorials) backs every band whose pair it covers. A track covering no adjacent pair — an A-vs-C alignment in an A/B/C stack — is reported and skipped rather than drawn between the wrong two genomes.

A whole-genome example (peach vs grape, the chrom.sizes come from this repo and the alignment PAF from S3):

jb2export synteny --chromSizes data/comparative/peach.chrom.sizes \
  --paf https://s3.amazonaws.com/jbrowse.org/genomes/synteny/peach_grape.paf.gz \
  --chromSizes data/comparative/grape.chrom.sizes --autoDiagonalize \
  --colorBy query --opacity 0.4 --levelHeights 350 --drawCurves --width 1400 \
  --out grape_peach_synteny.png

Whole-genome synteny, grape vs peach, with autoDiagonalize and colorBy query

A mammalian-scale test: human (hs1/T2T) vs mouse (mm39) liftOver, where the --minAlignmentLength 500000 filter is what keeps the plot from turning into spaghetti. --chromSizes means no multi-GB sequence is downloaded (whole-genome synteny draws none); the chrom.sizes are committed and the liftOver chain streams from the web, so this reproduces with only the public chain:

jb2export synteny --chromSizes data/comparative/hs1.chrom.sizes \
  --chain https://jbrowse.org/demos/hs1ToMm39/hs1ToMm39.over.chain.gz \
  --chromSizes data/comparative/mm39.chrom.sizes --minAlignmentLength 500000 \
  --autoDiagonalize --colorBy query --opacity 0.4 --levelHeights 350 \
  --drawCurves --cigarMode matches --width 1400 --out hs1_mm39_synteny.png

Mammalian-scale synteny, human (hs1) vs mouse (mm39)

A three-level stack: hg38, hs1 (T2T), and mm39, with one ribbon per adjacent pair: the conserved hg38↔hs1 build liftover on top (near-vertical bands) and the diverged hs1↔mm39 human–mouse synteny below. Each UCSC liftOver .chain sits between the two assemblies it relates (hg38ToHs1 between hg38 and hs1, hs1ToMm39 between hs1 and mm39):

jb2export synteny --chromSizes data/comparative/hg38.chrom.sizes \
  --chain data/comparative/hg38ToHs1.over.chain.gz \
  --chromSizes data/comparative/hs1.chrom.sizes \
  --chain https://jbrowse.org/demos/hs1ToMm39/hs1ToMm39.over.chain.gz \
  --chromSizes data/comparative/mm39.chrom.sizes --minAlignmentLength 500000 \
  --autoDiagonalize --colorBy query --opacity 0.4 --levelHeights 300,300 \
  --drawCurves --cigarMode matches --width 1400 --out hg38_hs1_mm39_synteny.png

Three-level synteny stack: hg38, hs1, and mm39

All-vs-all alignments (PGGB, minimap2 -X)

The stacks above take one alignment file per gap. An all-vs-all PAF — every genome aligned against every other, from PGGB or from minimap2 -X over PanSN-named contigs — already holds every pair, so it is instead one track that backs every band: the file is read once, and each band asks the adapter for its own pair of assemblies.

That makes it a --config case. --paf builds a pairwise PAFAdapter, which reads the whole file as a single query-vs-target comparison, so repeating the same all-vs-all file across the gaps fails every band past the first with AssemblyNotInAdapterError — the PanSN prefixes that say which genome each record belongs to mean nothing to that adapter. The adapter that reads them is MultiGenomePAFAdapter (or MultiGenomeIndexedPAFAdapter for a make-pif index), named in a config:

Config file

Goes in the tracks array of config.json. See Tracks.

{
  "type": "SyntenyTrack",
  "trackId": "ecoli_ava",
  "name": "E. coli pangenome (all-vs-all PAF)",
  "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
  "adapter": {
    "type": "MultiGenomePAFAdapter",
    "uri": "all_vs_all.paf.gz",
    "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"]
  }
}

CLI (add-track)

jbrowse add-track all_vs_all.paf.gz \
  --trackId ecoli_ava \
  --name "E. coli pangenome (all-vs-all PAF)" \
  --assemblyNames K12,Sakai,CFT073,NCTC86,IAI39 \
  --adapterType MultiGenomePAFAdapter \
  --load copy

In the app

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:

{
  "type": "SyntenyTrack",
  "trackId": "ecoli_ava",
  "name": "E. coli pangenome (all-vs-all PAF)",
  "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
  "adapter": {
    "type": "MultiGenomePAFAdapter",
    "uri": "all_vs_all.paf.gz",
    "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"]
  }
}

all_vs_all.paf.gz is relative to a config.json. Replace it with its URL or its path on this computer.

That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.

synteny --config then places that one track on every gap whose pair its assemblyNames cover, which for a file covering the whole stack is all of them. The all-vs-all synteny tutorial builds this track and the five strain assemblies it names.

Where a config holds more than one such track, --spec says which one each band uses. The hosted demo below is that case — it has the same five strains aligned four ways (minimap2, pggb/wfmash, cactus, and untangle) — and its spec is where the repetition is, one entry per band:

{
  "type": "LinearSyntenyView",
  "views": [
    { "assembly": "K12" },
    { "assembly": "Sakai" },
    { "assembly": "CFT073" },
    { "assembly": "NCTC86" },
    { "assembly": "IAI39" }
  ],
  "tracks": [["ecoli_ava"], ["ecoli_ava"], ["ecoli_ava"], ["ecoli_ava"]],
  "minAlignmentLength": 10000,
  "levelHeights": [130, 130, 130, 130]
}

Five rows means four bands, so tracks has four entries and every one of them is the same trackId. minAlignmentLength drops minimap2's short alignments, which otherwise bury the shared backbone under a noise band.

jb2export --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --spec data/comparative/ecoli_ava.spec.json --width 1400 \
  --out ecoli_ava_synteny.png

Five E. coli strains stacked from one all-vs-all PAF, every band served by the same track

The unbroken ribbons are the backbone shared by all five strains and the gaps are where they differ; the crossings in the bottom band are IAI39's inversions against the others.

All the example images in this README (including the comparative ones above) are regenerated by pnpm screenshots --filter jbrowse-img from the repo root: see the CliSpec entries in website/scripts/screenshot-specs.ts.

Circular view (chord plot)

The circular subcommand renders one assembly's chord tracks (e.g. a VCF of structural variants) as a circular ideogram with chords drawn between the two breakends of each rearrangement. It is single-assembly and shows the whole genome (no --loc); each track picks its chord display automatically.

The tracks it draws are the ones the track flags and --track name. Name them over a --hub or a large --config, whose hundreds of tracks would otherwise all be opened — which is what a run naming none still means.

Display modifiers do not apply here, and a run that passes one says so: the modifiers name slots on the LINEAR displays, and this view draws a variant track as chords instead. Settings for a circular view go in the config the track comes from, or in a --spec.

jb2export circular --fasta ref.fa --vcfgz sv.vcf.gz --out circular.svg

This example uses SKBR3 (a breast-cancer cell line) long-read Sniffles SV calls on hg19: each inter-chromosomal chord is a translocation, the classic dense rearranged-cancer-genome view. --fasta reads only the .fai for chromosome names and lengths (the circular view fetches no sequence):

jb2export circular --fasta https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz \
  --vcfgz https://jbrowse.org/genomes/hg19/SKBR3/reads_lr_skbr3.fa_ngmlr-0.2.3_mapped.bam.sniffles1kb_auto_l8_s5_noalt.filtered.vcf.gz \
  --width 800 --out circular_chords.png

Circular chord plot of SKBR3 structural variants on hg19, inter-chromosomal chords marking translocations

Run jb2export circular --help for the full list of options.

Two genomes on one circle come from a config and a session spec, the way the comparative views do. This one is the circular synteny tutorial's hosted config: human and mouse liftOver blocks as ribbons, inside a ring of genes per 100 kb for both genomes. The spec names the pair of assemblies and opens the ring with its density rendering:

jb2export --config https://jbrowse.org/demos/circular_synteny/config.json \
  --spec data/comparative/hg38_mm39_circular.spec.json --width 800 \
  --out circular_synteny.png

Human chromosomes 1, 2 and X against their mouse counterparts on one circle, liftOver ribbons inside a gene density ring for both genomes

Configs and sessions

Use with a jbrowse config.json

A config.json can be specified with extra tracks supplied outside the config e.g. with --bam. Files referenced in the config can be remote (uri) or local (localPath).

jb2export --config data/config.json \
  --assembly hg19 \
  --bam custom_bam.bam \
  --loc 1:1,000,000-1,100,000

The jbrowse CLI tool (e.g. npm install -g @jbrowse/cli) refers to "uri" paths by default, but you replace them with localPath like this


  //replace this:
  "vcfGzLocation": {
    "uri": "volvox.dup.vcf.gz"
  },

  //with this:
  "vcfGzLocation": {
    "localPath": "volvox.dup.vcf.gz"
  }

jb2export --config data/volvox/config.json --assembly volvox --track volvox_sv \
  --loc ctgA:1-50,000 --width 1200 --out volvox_config.png

Structural-variant calls over 50 kb of volvox ctgA, read from a config whose VCF is a localPath

localPaths resolve relative to the config file supplied, so with --config data/volvox/config.json and "localPath": "volvox.dup.vcf.gz" this example resolves data/volvox/volvox.dup.vcf.gz

See data/volvox/config.json for a config that contains localPaths, or data/config.json for a config that just contains URLs

A mark display (LinearMarkDisplay) loads a marks list whose slots disagree with each other, and the app says what it cannot draw in the track's corner chip. jb2export prints each of those problems to stderr, and fails without writing an image on one the display's rule list calls an error, such as a bar naming no y. jbrowse validate checks a config file against the same rules.

Use a session file exported from jbrowse

In jbrowse-web, File->Export session produces a session.json file for the --session parameter. Specify the assembly as well, it currently does not infer the assembly from the session

jb2export --config data/config.json --session data/skbr3/session.json \
  --assembly hg19 --width 1400 --out skbr3_session.png

SKBR3 whole-genome read coverage, restored from a saved session file

The session names its tracks by trackId, so the --config you pass has to be the one those ids come from — data/config.json here, which defines hg19 and the ngmlr_cov coverage track that data/skbr3/session.json opens.

data/skbr3/session.json is also worth reading as the short way to write one by hand. A view says where to go and what to open with settings written directly on it, and each track entry has its own display settings inline:

{
  "session": {
    "name": "SKBR3 whole-genome coverage",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "hg19",
        "tracks": [
          {
            "trackId": "ngmlr_cov",
            "height": 275,
            "mark": "point"
          }
        ]
      }
    ]
  }
}

Omitting loc shows the whole genome. Those inline track keys are the same vocabulary as the track's config — anything the track menu can set, a session can ask for here.

Track order on the command line

Example:

jb2export --bam file1.bam --bigwig file.bw --bam file2.bam

This will respect the order of the tracks and list file1.bam, file.bw, and file2.bam in that order, which is why the command line parser is a custom one

Overriding render defaults

Force render a large region

Some jbrowse track types (alignments, gene tracks, etc) will not display if zoomed too far out. Add force:true to make it render

jb2export --bam file.bam force:true --loc 1:1,100,000-1,200,000 --fasta hg19.fa

Render only the SNPCoverage track of an alignments track

showPileup=false collapses the alignments display down to coverage-only; size the coverage band with coverageHeight=N to match height:N, the overall track height. Reproducible with the bundled volvox alignments:

jb2export --fasta data/volvox/volvox.fa \
  --bam data/volvox/volvox-sorted.bam showPileup=false coverageHeight=200 height:200 \
  --loc ctgA:1-20000 --width 1200 --out snpcov.png

The bundled volvox alignments as a coverage histogram alone, with the read pileup hidden

Parameters

Flags take their value as the next argument (--width 1200) or inline with an equals sign (--width=1200).

Assembly params

--fasta — path or http(s) URL to an indexed FASTA (.fa, .fa.gz)
--aliases — tab-separated refname aliases; column 1 matches the FASTA, other columns are aliases (e.g. maps 1 → chr1)
--cytobands — path or URL to a cytoband BED file for the assembly
--hub — a genomes.jbrowse.org assembly to pull the whole config from: a UCSC db name (hg19, mm10) or GenArk accession (GCA_.../GCF_...); supplies sequence, cytobands, and refName aliasing (see Hosted assemblies)

Track params

Specify a filename (local) or http(s) URL. Can be repeated for multiple tracks of the same type, e.g. --bam file1.bam --bam file2.bam

--bam
--cram
--bigwig
--multiwig — many BigWigs as one multi-row MultiQuantitativeTrack; its argument is a comma-separated BigWig file list (local paths or URLs) or a .json sources file (an array of BigWig paths/URLs, or of subadapter objects with per-row name/color/group) — see MultiWiggle
--vcfgz
--gffgz
--bigbed
--bedgz
--hic

Config file params (optional)

--assembly — path to a JBrowse 2 assembly JSON (e.g. data/assembly.json), or the name of an assembly in --config; can be used in place of --fasta
--tracks — path to a JSON file containing an array of JBrowse 2 track configs (e.g. data/tracks.json)
--session — path to a JBrowse 2 session JSON exported from File → Export session
--config — path or URL to a full JBrowse 2 config.json (e.g. data/config.json)
--track — show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated; repeatable, and accepts the same display modifiers as the track-type flags
--defaultSession — use the defaultSession embedded in --config

Output params

--loc — location string to render, e.g. chr1:1-10000 or all; also a gene name when the config has a text-search index (e.g. from --hub)
--out — output file path; .svg, .png, or .pdf
--width — view width in pixels (default: 1500)
--noRasterize — render everything as SVG vectors instead of rasterizing canvas layers (pileup, coverage, hic); results in larger files

Appearance params

--themeName — theme to use for rendering: default, lightStock, lightMinimal, darkStock, or darkMinimal
--showGridlines — draw genomic coordinate gridlines
--trackLabels — label position: offset, overlapping, left, or hidden

Full command-line help

Run jb2export --help for the full option list, or jb2export <subcommand> --help (e.g. jb2export dotplot --help) for a subcommand's options. The complete output:

Usage: jb2export [options]
       jb2export <dotplot|synteny|circular|breakpoint> [options]
       jb2export batch --vcf <file> [options]
       jb2export list [hub] [filter]

Options:
  --fasta           Path to indexed FASTA file
  --chromSizes      Path to a chrom.sizes file (whole-genome assembly, no sequence). Repeat for each assembly in a comparative view
  --aliases         Path to reference name aliases file
  --assembly        Path to assembly JSON (or "-" for stdin) or name in config
  --hub             Pull a whole config from genomes.jbrowse.org: a UCSC db name (hg19, mm10) or GenArk accession (GCA_/GCF_...). Gives cytobands, refName aliasing, and hosted trackIds (see --track)
  --track           Show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated (the hg19- prefix is optional). Repeatable; accepts the same display modifiers as track flags (height:, color:, ...)
  --config          Path to JBrowse config.json (path, URL, or "-" for stdin)
  --session         Path to session JSON (or "-" for stdin)
  --loc             Location to render (e.g., chr1:1-1000 or "all"), or a gene name when the config has a text-search index (e.g. from --hub)
  --out             Output file path (SVG, PNG, or PDF by extension). Omit it to write the SVG to stdout, which pipes into rsvg-convert for other formats
  --width           Width of output in pixels [default: 1500]
  --noRasterize     Disable rasterization of pileup/coverage [default: false]
  --defaultSession  Use default session from config [default: false]
  --tracks          Path to JSON file with an array of track configs (or "-" for stdin); added to the config's tracks, replacing any with the same trackId
  --cytobands       Path to cytoband file for the assembly
  --themeName       Palette for rendering: default, stock, or minimal
  --themeMode       Draw that palette light or dark
  --fontFamily      Font family for all text (serif, sans-serif, monospace, or a named family) [default: serif]
  --showGridlines   Show genomic coordinate gridlines in the output [default: false]
  --trackLabels     Track label position: offset, overlapping, left, or hidden
  --refseq          Show the reference sequence track [default: false]
  --spec            Session-spec JSON (inline, path to .json, or "-" for stdin) describing the view; see urlparams.md. Drives N-way comparative views from a --config
  --help            Show help
  --version         Print version

Examples:
  jb2export --fasta ref.fa --bam reads.bam --loc chr1:1-10000 --out out.svg
      Render BAM alignments to SVG
  jb2export --fasta ref.fa --vcfgz variants.vcf.gz --loc chr1:1-50000 --out out.png
      Render VCF variants to PNG
  jb2export --fasta ref.fa --bam reads.bam height:80 color:strand --loc chr1:1-10000 --out out.svg
      Custom track height and strand coloring
  jb2export --hub hg19 --track hg19-ncbiRefSeqCurated --loc chr1:1-100000 --out out.svg
      Pull the hg19 config from genomes.jbrowse.org and show a hosted track
  jb2export --config jbrowse.json --assembly hg38 --tracks tracks.json --loc chr1:1-100000 --out out.svg
      Render from config with a JSON tracks file
  jb2export --fasta ref.fa.gz --cytobands cytobands.bed --bigwig signal.bw --loc chr1 --out out.svg
      Render BigWig with cytobands

Track options: --bam, --cram, --bigwig, --multiwig, --vcfgz, --gffgz, --hic, --bigbed, --bedgz

Comparative subcommands (run "jb2export dotplot --help"): dotplot, synteny, circular, breakpoint

Whole callsets: "jb2export batch --vcf calls.vcf.gz" writes one image per record (run "jb2export batch --help")

Discovery: "jb2export list" lists genomes.jbrowse.org assemblies; "jb2export list <hub> [filter]" lists a hub's tracks

Usage: jb2export dotplot [options]

Options:
  --fasta               Path to indexed FASTA file
  --chromSizes          Path to a chrom.sizes file (whole-genome assembly, no sequence). Repeat for each assembly in a comparative view
  --aliases             Path to reference name aliases file
  --assembly            Path to assembly JSON (or "-" for stdin) or name in config
  --hub                 Pull a whole config from genomes.jbrowse.org: a UCSC db name (hg19, mm10) or GenArk accession (GCA_/GCF_...). Gives cytobands, refName aliasing, and hosted trackIds (see --track)
  --track               Show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated (the hg19- prefix is optional). Repeatable; accepts the same display modifiers as track flags (height:, color:, ...)
  --config              Path to JBrowse config.json (path, URL, or "-" for stdin)
  --session             Path to session JSON (or "-" for stdin)
  --loc                 Location to render (e.g., chr1:1-1000 or "all"), or a gene name when the config has a text-search index (e.g. from --hub)
  --out                 Output file path (SVG, PNG, or PDF by extension). Omit it to write the SVG to stdout, which pipes into rsvg-convert for other formats
  --width               Width of output in pixels [default: 1500]
  --noRasterize         Disable rasterization of pileup/coverage [default: false]
  --defaultSession      Use default session from config [default: false]
  --tracks              Path to JSON file with an array of track configs (or "-" for stdin); added to the config's tracks, replacing any with the same trackId
  --cytobands           Path to cytoband file for the assembly
  --themeName           Palette for rendering: default, stock, or minimal
  --themeMode           Draw that palette light or dark
  --fontFamily          Font family for all text (serif, sans-serif, monospace, or a named family) [default: serif]
  --showGridlines       Show genomic coordinate gridlines in the output [default: false]
  --trackLabels         Track label position: offset, overlapping, left, or hidden
  --refseq              Show the reference sequence track [default: false]
  --spec                Session-spec JSON (inline, path to .json, or "-" for stdin) describing the view; see urlparams.md. Drives N-way comparative views from a --config
  --fasta2              Second assembly indexed FASTA (shorthand)
  --aliases2            Reference name aliases for fasta2
  --loc2                Location on the second assembly
  --autoDiagonalize     Reorder the next assembly's chromosomes for least overlap (a clean diagonal) [default: false]
  --minAlignmentLength  Hide alignments shorter than N bp (de-spaghetti a busy plot)
  --colorBy             Color synteny ribbons by: strand, query, target, reference, track, identity, mapq, dnds, or syntenicDepth. "query" gives each query chromosome its own color; "reference" needs a stack of three or more genomes and "track" more than one alignment file

Examples:
  jb2export dotplot --fasta a.fa --fasta2 b.fa --paf a_vs_b.paf --out out.svg
      Whole-genome dotplot of two assemblies via a PAF
  jb2export synteny --fasta a.fa loc:chr1 --paf a_vs_b.paf --fasta b.fa loc:chr1 --out out.svg
      Linear synteny of a region in each assembly (loc: rides on the assembly flag)
  jb2export synteny --chromSizes a.sizes --paf a_b.paf --chromSizes b.sizes --chain b_c.chain --chromSizes c.sizes --out out.svg
      Multi-way (3+) synteny: repeat the assembly flag, put each alignment between the pair it compares
  jb2export synteny --config jbrowse.json --spec spec.json --out out.svg
      N-way synteny from a config + session-spec JSON (see urlparams.md)

Comparison track options: --paf, --blasttab, --chain, --delta

Usage: jb2export synteny [options]

Options:
  --fasta               Path to indexed FASTA file
  --chromSizes          Path to a chrom.sizes file (whole-genome assembly, no sequence). Repeat for each assembly in a comparative view
  --aliases             Path to reference name aliases file
  --assembly            Path to assembly JSON (or "-" for stdin) or name in config
  --hub                 Pull a whole config from genomes.jbrowse.org: a UCSC db name (hg19, mm10) or GenArk accession (GCA_/GCF_...). Gives cytobands, refName aliasing, and hosted trackIds (see --track)
  --track               Show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated (the hg19- prefix is optional). Repeatable; accepts the same display modifiers as track flags (height:, color:, ...)
  --config              Path to JBrowse config.json (path, URL, or "-" for stdin)
  --session             Path to session JSON (or "-" for stdin)
  --loc                 Location to render (e.g., chr1:1-1000 or "all"), or a gene name when the config has a text-search index (e.g. from --hub)
  --out                 Output file path (SVG, PNG, or PDF by extension). Omit it to write the SVG to stdout, which pipes into rsvg-convert for other formats
  --width               Width of output in pixels [default: 1500]
  --noRasterize         Disable rasterization of pileup/coverage [default: false]
  --defaultSession      Use default session from config [default: false]
  --tracks              Path to JSON file with an array of track configs (or "-" for stdin); added to the config's tracks, replacing any with the same trackId
  --cytobands           Path to cytoband file for the assembly
  --themeName           Palette for rendering: default, stock, or minimal
  --themeMode           Draw that palette light or dark
  --fontFamily          Font family for all text (serif, sans-serif, monospace, or a named family) [default: serif]
  --showGridlines       Show genomic coordinate gridlines in the output [default: false]
  --trackLabels         Track label position: offset, overlapping, left, or hidden
  --refseq              Show the reference sequence track [default: false]
  --spec                Session-spec JSON (inline, path to .json, or "-" for stdin) describing the view; see urlparams.md. Drives N-way comparative views from a --config
  --fasta2              Second assembly indexed FASTA (shorthand)
  --aliases2            Reference name aliases for fasta2
  --loc2                Location on the second assembly
  --autoDiagonalize     Reorder the next assembly's chromosomes for least overlap (a clean diagonal) [default: false]
  --drawCurves          Draw synteny ribbons as bezier curves instead of trapezoids [default: false]
  --minAlignmentLength  Hide alignments shorter than N bp (de-spaghetti a busy plot)
  --colorBy             Color synteny ribbons by: strand, query, target, reference, track, identity, mapq, dnds, or syntenicDepth. "query" gives each query chromosome its own color; "reference" needs a stack of three or more genomes and "track" more than one alignment file
  --opacity             Ribbon opacity 0-1 (lower reveals density)
  --levelHeights        Comma-separated pixel height per level, e.g. 300,300 (one value applies to all)
  --cigarMode           CIGAR indels in synteny ribbons: 'full' (colored), 'matches' (see-through), or 'off' (one solid block per alignment, so overlapping blocks run together) [default: full]

Examples:
  jb2export dotplot --fasta a.fa --fasta2 b.fa --paf a_vs_b.paf --out out.svg
      Whole-genome dotplot of two assemblies via a PAF
  jb2export synteny --fasta a.fa loc:chr1 --paf a_vs_b.paf --fasta b.fa loc:chr1 --out out.svg
      Linear synteny of a region in each assembly (loc: rides on the assembly flag)
  jb2export synteny --chromSizes a.sizes --paf a_b.paf --chromSizes b.sizes --chain b_c.chain --chromSizes c.sizes --out out.svg
      Multi-way (3+) synteny: repeat the assembly flag, put each alignment between the pair it compares
  jb2export synteny --config jbrowse.json --spec spec.json --out out.svg
      N-way synteny from a config + session-spec JSON (see urlparams.md)

Comparison track options: --paf, --blasttab, --chain, --delta

Usage: jb2export circular [options]

Options:
  --fasta           Path to indexed FASTA file
  --chromSizes      Path to a chrom.sizes file (whole-genome assembly, no sequence). Repeat for each assembly in a comparative view
  --aliases         Path to reference name aliases file
  --assembly        Path to assembly JSON (or "-" for stdin) or name in config
  --hub             Pull a whole config from genomes.jbrowse.org: a UCSC db name (hg19, mm10) or GenArk accession (GCA_/GCF_...). Gives cytobands, refName aliasing, and hosted trackIds (see --track)
  --track           Show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated (the hg19- prefix is optional). Repeatable; accepts the same display modifiers as track flags (height:, color:, ...)
  --config          Path to JBrowse config.json (path, URL, or "-" for stdin)
  --session         Path to session JSON (or "-" for stdin)
  --loc             Location to render (e.g., chr1:1-1000 or "all"), or a gene name when the config has a text-search index (e.g. from --hub)
  --out             Output file path (SVG, PNG, or PDF by extension). Omit it to write the SVG to stdout, which pipes into rsvg-convert for other formats
  --width           Width of output in pixels [default: 1500]
  --noRasterize     Disable rasterization of pileup/coverage [default: false]
  --defaultSession  Use default session from config [default: false]
  --tracks          Path to JSON file with an array of track configs (or "-" for stdin); added to the config's tracks, replacing any with the same trackId
  --cytobands       Path to cytoband file for the assembly
  --themeName       Palette for rendering: default, stock, or minimal
  --themeMode       Draw that palette light or dark
  --fontFamily      Font family for all text (serif, sans-serif, monospace, or a named family) [default: serif]
  --showGridlines   Show genomic coordinate gridlines in the output [default: false]
  --trackLabels     Track label position: offset, overlapping, left, or hidden
  --refseq          Show the reference sequence track [default: false]
  --spec            Session-spec JSON (inline, path to .json, or "-" for stdin) describing the view; see urlparams.md. Drives N-way comparative views from a --config

Examples:
  jb2export circular --fasta ref.fa --vcfgz sv.vcf.gz --out out.svg
      Circular (chord) view of structural variants

Usage: jb2export breakpoint [options]

Options:
  --fasta           Path to indexed FASTA file
  --chromSizes      Path to a chrom.sizes file (whole-genome assembly, no sequence). Repeat for each assembly in a comparative view
  --aliases         Path to reference name aliases file
  --assembly        Path to assembly JSON (or "-" for stdin) or name in config
  --hub             Pull a whole config from genomes.jbrowse.org: a UCSC db name (hg19, mm10) or GenArk accession (GCA_/GCF_...). Gives cytobands, refName aliasing, and hosted trackIds (see --track)
  --track           Show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated (the hg19- prefix is optional). Repeatable; accepts the same display modifiers as track flags (height:, color:, ...)
  --config          Path to JBrowse config.json (path, URL, or "-" for stdin)
  --session         Path to session JSON (or "-" for stdin)
  --loc             Location to render (e.g., chr1:1-1000 or "all"), or a gene name when the config has a text-search index (e.g. from --hub)
  --out             Output file path (SVG, PNG, or PDF by extension). Omit it to write the SVG to stdout, which pipes into rsvg-convert for other formats
  --width           Width of output in pixels [default: 1500]
  --noRasterize     Disable rasterization of pileup/coverage [default: false]
  --defaultSession  Use default session from config [default: false]
  --tracks          Path to JSON file with an array of track configs (or "-" for stdin); added to the config's tracks, replacing any with the same trackId
  --cytobands       Path to cytoband file for the assembly
  --themeName       Palette for rendering: default, stock, or minimal
  --themeMode       Draw that palette light or dark
  --fontFamily      Font family for all text (serif, sans-serif, monospace, or a named family) [default: serif]
  --showGridlines   Show genomic coordinate gridlines in the output [default: false]
  --trackLabels     Track label position: offset, overlapping, left, or hidden
  --refseq          Show the reference sequence track [default: false]
  --spec            Session-spec JSON (inline, path to .json, or "-" for stdin) describing the view; see urlparams.md. Drives N-way comparative views from a --config

Examples:
  jb2export breakpoint --fasta ref.fa --bam tumor.bam --loc chr1:1,000,000-1,001,000 --loc chr5:2,000,000-2,001,000 --out sv.png
      Both sides of one breakend, with the reads that cross it drawn between
  jb2export breakpoint --hub hg38 --bam tumor.bam --loc chr3:25,358,000-25,361,000 --loc chr10:58,716,500-58,718,500 --loc chr12:72,272,000-72,275,000 --out chain.png
      A multi-hop chain: one panel per locus, in the order the reads cross them
  jb2export breakpoint --fasta ref.fa --bam tumor.bam --loc "chr9:28,030,000-28,032,000 chr9:28,058,000-28,060,000" --loc chr9:28,059,000-28,061,000 --out fb.png
      Quote one --loc to put several windows in a single panel

Usage: jb2export batch --vcf <file> [options]

Renders one image per record, a contig a row. Loci on one contig are a
linear view, their windows side by side: the two ends of a deletion, a
duplication or an inversion, or one window where --flank reaches from one
end to the other. Loci on several contigs are a breakpoint split view of
one panel a contig. A row holds four windows at most, and a contig of
more wraps.

The reads joining an image's windows are drawn between them, as arcs in
a linear view and as curves in a breakpoint view, and the manifest counts
them. Each alignments track lays out its SV evidence first: split reads,
then reads carrying an insertion or deletion of 50 bases or more, then
discordant pairs, unless the track sets arcs: or sort= itself.

Where a record on one contig spells out its alleles, or is a symbolic
<DEL> or <INS>, the manifest also counts the reads with the ALT at its
variant: an SNV at its base, a deletion at its first deleted base, an
insertion at the base after it, and an insertion of 50 bases or more
wherever in the window the aligner placed it. A deletion of 50 bases or
more is a gap of half its length or more. In an image of one window
every alignments track with no sort: of its own is sorted there and a
band marks the bases the record changes. Such a track also grows to hold
its pileup, up to 250 px, so rows are the same height on every image and
a deep pileup stops there with its carriers on top; a height:,
heightMode: or growMaxHeight= of its own wins.

The module graph loads once for the whole callset, so this is much faster
than a shell loop over "jb2export breakpoint".

Options:
  --fasta           Path to indexed FASTA file
  --chromSizes      Path to a chrom.sizes file (whole-genome assembly, no sequence). Repeat for each assembly in a comparative view
  --aliases         Path to reference name aliases file
  --assembly        Path to assembly JSON (or "-" for stdin) or name in config
  --hub             Pull a whole config from genomes.jbrowse.org: a UCSC db name (hg19, mm10) or GenArk accession (GCA_/GCF_...). Gives cytobands, refName aliasing, and hosted trackIds (see --track)
  --track           Show a trackId already in the config (from --hub/--config), e.g. --track hg19-ncbiRefSeqCurated (the hg19- prefix is optional). Repeatable; accepts the same display modifiers as track flags (height:, color:, ...)
  --config          Path to JBrowse config.json (path, URL, or "-" for stdin)
  --width           Width of output in pixels [default: 1500]
  --noRasterize     Disable rasterization of pileup/coverage [default: false]
  --defaultSession  Use default session from config [default: false]
  --tracks          Path to JSON file with an array of track configs (or "-" for stdin); added to the config's tracks, replacing any with the same trackId
  --cytobands       Path to cytoband file for the assembly
  --themeName       Palette for rendering: default, stock, or minimal
  --themeMode       Draw that palette light or dark
  --fontFamily      Font family for all text (serif, sans-serif, monospace, or a named family) [default: serif]
  --showGridlines   Show genomic coordinate gridlines in the output [default: false]
  --trackLabels     Track label position: offset, overlapping, left, or hidden
  --refseq          Show the reference sequence track [default: false]
  --vcf             VCF (plain or bgzipped) of variants to render, one image per record
  --bedpe           BEDPE to render, one image per row; the format for anything a VCF cannot express (a LINX TSV reshaped by awk)
  --outDir          Directory to write the images to [default: jb2export-batch]
  --flank           bp of context around each locus [default: 50 for a variant whose alleles are under 50 bp, 500 otherwise]
  --limit           Render only the first N rows
  --format          Output format: png, svg, or pdf [default: png]
  --passOnly        Skip VCF records whose FILTER is neither PASS nor "." [default: false]
  --resume          Skip a record whose image is already in --outDir, so an interrupted run picks up where it stopped [default: false]
  --manifest        Also write manifest.tsv to --outDir: one row per image with its file, loci, name, line in the input, EVENT, the reads joining its windows, the reads with the ALT at its variant, the view as a session spec and status [default: false]
  --dryRun          Print the file and loci each record would render, and render nothing [default: false]
  --jobs            Processes to render in, each about a gigabyte. The default is half the cores, up to 4 and to what memory allows; 1 renders in this process

Examples:
  jb2export batch --vcf calls.vcf.gz --fasta ref.fa --bam tumor.bam --outDir figs --flank 1000
      A contact sheet of every junction in a callset
  jb2export batch --vcf calls.vcf.gz --hub hg38 --bam tumor.bam --limit 20
      The first 20, to check the framing before committing to the whole run
  jb2export batch --vcf snvs.vcf.gz --hub hg38 --bam tumor.bam --passOnly
      Small variants at base resolution, carriers of each sorted to the top
  jb2export batch --bedpe linx_links.bedpe --hub hg38 --bam tumor.bam
      The same from a BEDPE, for a caller whose output is not a VCF

The ALT grammar is parsed by @gmod/vcf, so inserted sequence at the
junction and upper-cased mate contigs are handled; reciprocal breakend
pairs collapse, so each junction is queued once.

Every track is drawn as if given force:true, since a window is only a flank
wide and a "Region too large" panel cannot be clicked through on an image;
force:false on a track restores its size limit.

Records a caller files under one VCF EVENT are also drawn together, as
event_<n>_<label>, when the event visits more than two loci, its contigs
in the order the VCF header lists them.

Troubleshooting

`ENOENT: ... .fa.fai` (or `.bai` / `.tbi` / `.crai`)

Data files are read alongside their index, so generate the index next to the file first:

samtools faidx yourfile.fa     # -> yourfile.fa.fai
samtools index yourfile.bam    # -> yourfile.bam.bai
tabix -p vcf yourfile.vcf.gz   # -> yourfile.vcf.gz.tbi

`unknown reference sequence name in location ...`

The refname in --loc doesn't match the FASTA. Use the name exactly as it appears in the FASTA, or pass --aliases to reconcile differing naming styles (e.g. 1 vs chr1 vs NC_000001.10) across the assembly and track files. See Remote files.

A track renders empty when zoomed far out

Some track types (alignments, genes) refuse to render past a feature-density limit. Add force:true after the track to override it. See Force render a large region.

Static image export (@jbrowse/img)

Prerequisites#

Setup#

Quickstart#

Basic usage#

Local files#

Remote files#

Hosted assemblies (genomes.jbrowse.org)#

Output formats#

Converting SVG to PNG manually#

Track gallery#

Alignments tracks#

Breakpoint split views#

BigWig / quantitative tracks#

MultiWiggle (many BigWigs in one track)#

Variant tracks#

Multi-sample variant matrix#

Hi-C tracks#

Gene tracks and the reference sequence#

Themes#

Track modifiers#

Any display setting (slot.path=value)#

Declaring what to draw (display:marks)#

Raw display settings (JSON)#

Comparative views#

Compare two assemblies (dotplot / synteny)#

Multi-way synteny (three or more assemblies)#

All-vs-all alignments (PGGB, minimap2 -X)#

Circular view (chord plot)#

Configs and sessions#

Use with a jbrowse config.json#

Use a session file exported from jbrowse#

Track order on the command line#

Overriding render defaults#

Force render a large region#

Render only the SNPCoverage track of an alignments track#

Parameters#

Assembly params#

Track params#

Config file params (optional)#

Output params#

Appearance params#

Full command-line help#

Troubleshooting#

ENOENT: ... .fa.fai (or .bai / .tbi / .crai)#

unknown reference sequence name in location ...#

A track renders empty when zoomed far out#

See also#