@jbrowse/img

@jbrowse/img

Static exports of JBrowse 2 rendering.

The output is currently SVG which should be loadable in Adobe Illustrator or Inkscape. The output can also be manually converted to PNG if needed.

Screenshot

More examples EXAMPLES.md

Setup

Note that this is not yet published to NPM but when it is you can install via

npm install -g @jbrowse/img

Then you will have a command jb2export that can be used.

To use it now, see developer guide for details

Example usages

This will show some example usages

Use with local files

We can call this script on local files, and it doesn't require a web browser, not even a headless webbrowser, it just runs a node script and React SSR is used 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 1:1,000,000-1,001,000

The file out.svg is created by default, use --out to customize

Use with remote files

This example shows using remote files, e.g. with human hg19 and several tracks

Note the use of --aliases to smooth 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

Customizing track

In addition to possibly specifying custom track configuration files, sometimes specializing specifically track state is helpful. This example helps color and sort by the read group (RG) tag

jb2export --fasta data/volvox/volvox.fa \
  --bam data/volvox/volvox-rg.bam color:tag:RG sort:tag:RG height:400 \
  --loc ctgA:609..968

You can see that instead of adding extra dash dash --flags, it is a colon based syntax that follows a track definition.

The color and sort are specific to pileup, and height can apply to any track. More options may be described here soon

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 --config data/config.json \
  --loc 1:1,100,000-1,200,000 \
  --assembly hg19 \
  --configtracks hg00096_lowcov force:true

Render the sequence track

If you are using the fasta argument, the refseq will be named "refseq" and can be specified with the --configtracks tag. If you are using a pre-loaded config.json then you can find the trackId to pass to --configtracks in there

jb2export --fasta data/volvox/volvox.fa --configtracks refseq --loc ctgA:1-100

Use with a jbrowse config.json (remote files in the config.json)

A config.json can be specified, and then we just refer to trackIds in this file, and extra tracks can also be supplied that are outside of the config e.g. with --bam

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

Respects the order of the files you input

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. This requires us to use a custom command line parser instead of an off-the-shelf one like yargs

Use a session file exported from jbrowse

If you use jbrowse-web, you can select File->Export session which produces a session.json file, and then use the --session parameter. Make sure to specify the assembly also, it currently does not infer the assembly from the session

jb2export --config data/skbr3/config.json \
  --session session.json \
  --assembly hg19

Plot whole-genome overview of bigwig

The special flag --loc all shows the full assembly, and there are a number of custom bigwig plotting options that can help draw the bigwig genome wide

Example with logscale, manual setting of minmax score

jb2export --loc all \
  --bigwig coverage.bw scaletype:log fill:false resolution:superfine height:400 color:purple minmax:1:1024 \
  --assembly hg19 \
  --config data/config.json

Example with linearscale, autoscore adjusted to "localsd" or mean plus/minus three standard deviations

jb2export --loc all \
  --bigwig coverage.bw autoscale:localsd fill:false resolution:superfine height:400 color:purple \
  --assembly hg19 \
  --config data/config.json

Use with a jbrowse config.json (local files in the config.json)

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"
  }

Then you can call it like above

jb2export --config data/volvox/config.json \
  --assembly volvox
  --configtracks volvox_sv \
  --loc ctgA:1-50,000

The localPaths will be resolved relative to the file that is supplied so in this example we would resolve data/volvox/volvox.dup.vcf.gz if "localPath": "volvox.dup.vcf.gz" is used, and --config data/volvox/config.json is passed

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

Parameters

Assembly params

• --fasta - filename or http(s) URL for a indexed or bgzip indexed FASTA file
• --aliases - tab separated "refName aliases" with column 1 matching the FASTA, and other columns being aliases

Track params

Specify these with a filename (local to the computer) or a http(s) URL. Can specify it multiple times e.g. --bam file1.bam --bam file2.bam

• --bigbed
• --gffgz
• --bedgz
• --vcfgz
• --bigwig
• --bam
• --cram
• --hic (wip)

Config file params (optional)

• --assembly - path to a JSON file containing a jbrowse 2 assembly config e.g. data/assembly.json, can be used in place of --fasta
• --tracks - path to a JSON file containing a list of jbrowse 2 track configs e.g. data/tracks.json
• --session - path to a JSON file containing a jbrowse 2 session config e.g. data/session.json
• --config - path to a JSON file containing a full jbrowse 2 config e.g. data/config.json

Other

• --loc - a locstring to navigate to
• --out - file to write the svg to
• --noRasterize - the canvas based tracks such as wiggle, read pileups, and hic are rasterized to a PNG inside the svg by default. if you want it in all SVG then use this flag but note that filesize may be much larger

Convert to PNG

The PNG above was made with inkscape. Most methods for converting from SVG to PNG should be OK, but imagemagick may produce some somewhat weird formatting. Here are a couple methods you can try

## 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