Introduction to JBrowseR

JBrowseR renders the JBrowse 2 linear genome view as an htmlwidget. JBrowse 2 is a fast, GPU-accelerated genome browser; JBrowseR lets you drive it entirely from R and embed it in R Markdown documents, Shiny apps, or the interactive console.

The API is declarative. You describe the browser with plain values — a genome, a list of tracks, a location — and helper constructors assemble the config. You never build JSON by hand.

library(JBrowseR)

The one-liner

The fastest way in is to name a genome hub hosted at jbrowse.org. This gives you the assembly, reference-name aliases, cytobands, and gene-name search with no further setup:

JBrowseR("hg38", location = "BRCA1")

location accepts a region string like "chr1:1-10000" or, because the hub ships a search index, a gene name like "BRCA1". Other hubs work the same way — "hg19", "mm10", or a GenArk accession such as "GCF_000001405.40".

Adding tracks

Add tracks by URL with track(). The track type and its index files (.bai/.crai/.tbi) are inferred from the file extension, so a data URL is usually all you need. tracks() gathers several together.

JBrowseR(
  "hg38",
  tracks = tracks(
    track(
      "https://jbrowse.org/genomes/GRCh38/alignments/NA12878/NA12878.alt_bwamem_GRCh38DH.20150826.CEU.exome.cram",
      name = "NA12878 Exome"
    )
  ),
  location = "17:43,044,295..43,048,000"
)
NA12878 exome CRAM at BRCA1
NA12878 exome CRAM at BRCA1

Recognized extensions cover the common genomics types:

Extension Track Adapter
.bam, .cram alignments BamAdapter, CramAdapter
.vcf.gz variants VcfTabixAdapter
.gff.gz, .gff3.gz, .gtf.gz, .bed.gz features Gff3TabixAdapter, GtfTabixAdapter, BedTabixAdapter
.bb, .bigBed features BigBedAdapter
.bw, .bigWig quantitative BigWigAdapter
.hic Hi-C contact matrix HicAdapter

The list isn’t hard-coded in R — the view infers the adapter with JBrowse’s own format plugins, so any format a bundled plugin recognizes works. Anything the inference gets wrong, or a track needing a specific adapter, is a plain config list (the full JBrowse track JSON); extra arguments to track() (e.g. type = "AlignmentsTrack") ride onto the track and override the inferred defaults.

When you only need the defaults, a bare URL string is a track — track() is just the same thing with room for name= and extra config. So a whole browser can skip the constructor entirely:

JBrowseR(
  "hg38",
  tracks = list(
    "https://hgdownload.soe.ucsc.edu/goldenPath/hg38/phyloP100way/hg38.phyloP100way.bw",
    "https://jbrowse.org/genomes/GRCh38/ncbi_refseq/GCA_000001405.15_GRCh38_full_analysis_set.refseq_annotation.sorted.gff.gz"
  ),
  location = "BRCA1"
)

Index files (.bai/.crai/.tbi) default to the conventional sibling of the data URL. When yours lives elsewhere — or is a .csi index — name it with index=, or as the second element of a c(url, index) pair in tracks:

track("https://example.com/reads.bam", index = "https://example.com/reads.bai")

Where to next

  • A genome that isn’t on a hub? See the custom browser tutorial.
  • Files on your own machine? See serving local data.
  • Need full control? Pass a whole JBrowse config with the config escape hatch.
  • Embedding in Shiny? Use JBrowseROutput() and renderJBrowseR(), and read the selected feature back with input$selectedFeature.