Skip to main content

JBrowse CLI with Desktop

JBrowse v5 beta

The tutorials target the JBrowse v5 beta, and the v4.3.0 release on the download page lacks some of what they show. To install the beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then jbrowse create jbrowse2 --branch v5.0.0-beta.13. Desktop beta builds are coming soon.

We build a genome browser configuration from the command line with @jbrowse/cli: a few commands produce one folder, a config.json next to your data files, which then opens in JBrowse Desktop and serves on the web. The CLI records each file by a path relative to config.json, so Desktop resolves the paths against the folder on disk and a web server resolves them against the served config's URL.

Prerequisites

  • Node.js 18 or newer
  • JBrowse Desktop, or a web server if you want to serve the same folder

Install the CLI

Install Node.js from NodeSource or NVM; the apt packages tend to be old.

npm install -g @jbrowse/cli
jbrowse --version

To avoid a global install, replace jbrowse with npx @jbrowse/cli in any command below.

Prepare indexed, compressed data files

The CLI copies or references your data files as they are, and JBrowse reads indexed, compressed files, so prepare each input first: a bgzipped and faidx-indexed FASTA, a sorted and indexed BAM or CRAM, a bgzipped and tabixed VCF, GFF3, or BED. The web quickstart has the samtools / htslib recipe per format, and the commands below assume you have already run them.

Build a config directory with add-assembly and add-track

Point every command at the same output directory with --out, which the CLI creates if needed. The first add-assembly writes myproject/config.json, and each later command edits that file in place:

jbrowse add-assembly GRCh38.fa.gz --name hg38 --load copy --out myproject
jbrowse add-track sample.bam --load copy --out myproject --name "My reads"
jbrowse add-track variants.vcf.gz --load copy --out myproject --name "My variants"

--name hg38 is the assembly name the session and the assembly selector use. --name on a track is its label in the track list.

--load sets how the CLI places a local file relative to the config:

--loadWhat it does
copyCopy the file (and its index) into the config directory.
moveMove it into the config directory.
symlinkSymlink it into the config directory (no data duplicated).
inPlaceReference a file already staged in the directory, no file ops.
(omit)For a remote https://… URL, referenced directly, nothing copied.

myproject/ is now self-contained:

myproject/
├── config.json
├── GRCh38.fa.gz  (+ .fa.gz.fai, .fa.gz.gzi)
├── sample.bam    (+ .bam.bai)
└── variants.vcf.gz  (+ .vcf.gz.tbi)
What the CLI wrote into config.json: each file by its bare relative name 
"adapter": {
  "type": "BamAdapter",
  "bamLocation": { "uri": "sample.bam", "locationType": "UriLocation" },
  "index": {
    "location": { "uri": "sample.bam.bai", "locationType": "UriLocation" },
    "indexType": "BAI"
  }
}

Open the folder on a default view with a session

A config with tracks but no session displays nothing until you launch a view and tick tracks in the selector. To open the folder ready to read, write a session and hand it to the CLI. In the session:

  • assembly is the --name you gave add-assembly
  • tracks takes the trackIds the CLI derived from your filenames; jq '.tracks[].trackId' myproject/config.json prints them
{
  "name": "myproject",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:1-100,000",
      "tracks": ["sample", "variants.vcf"]
    }
  ]
}
jbrowse set-default-session --session session.json --out myproject

session.json stays outside the folder, and the CLI copies its contents into config.json. jbrowse validate myproject/config.json reports a misspelled key that JBrowse would otherwise ignore.

Open the CLI-built folder in JBrowse Desktop

Choose File → Session → Open config.json or .jbrowse file... in JBrowse Desktop (or use the Open file or link button on the start screen) and pick myproject/config.json. Desktop resolves each relative path against the config's folder and loads the copied files from local disk, with no web server.

You can also hand the config straight to Desktop:

jbrowse-desktop myproject/config.json

(On macOS: open -a "JBrowse 2" myproject/config.json. See launching from the command line.)

A CLI-built folder opened in JBrowse Desktop by path, with no start screen and no Add track form. The session name and the track labels come from the commands above, run on the volvox test genome.

Desktop autosaves your work to a separate session file, and a .jbrowse file, which Desktop itself writes, saves in place.

Serve the config folder on the web

JBrowse Web is a separate app, so a served myproject/ needs a JBrowse Web instance alongside it, set up either way:

  • Build into a JBrowse Web install: run jbrowse create jbrowse2 first and pass --out jbrowse2 on the commands above, so the app and your config sit in one served folder. The web quickstart takes this route.
  • Point an existing deployment at your config: host myproject/ anywhere (e.g. npx serve myproject) and open your JBrowse Web instance with its URL appended: https://your-jbrowse/?config=http://localhost:3000/config.json.

The project above has no gene track yet, so add one first:

jbrowse add-track genes.gff3.gz --load copy --out myproject

jbrowse text-index then indexes the gene names into the same directory, and the location box finds a gene by name:

jbrowse text-index --out myproject

See also