JBrowse 2 combined guide
This document is a collection of all our documentation. It includes our quick start guide, user guide, configuration guide, CLI guide, developer guide, and FAQ. You can browse the other documents individually, but this page is to help simple ctrl+f searching and easy browsing. You can also download a pdf version of these same docs located at https://jbrowse.org/jb2/jbrowse2.pdf
JBrowse web quick start
In this guide, we'll get an instance of JBrowse running on your computer.
Pre-requisites
- Ability to run commands on the command line
- Node.js 10+
caution
If you are using apt as your package manager, we recommend not using it to
install Node.js. Good alternatives include
NodeSource or
NVM.
Download
You can download JBrowse 2 by using the JBrowse CLI or by downloading and unpacking it manually. We recommend using the JBrowse CLI since it also includes utilities to help you configure JBrowse 2 once it is set up.
Downloading using the JBrowse CLI
The JBrowse CLI can help perform many tasks to help you manage JBrowse 2, such as:
- create a new instance of JBrowse 2 automatically
- update an existing instance of JBrowse 2 with the latest released version
- configure your JBrowse 2 instance
Installing the CLI tools
To install the JBrowse CLI, run
After running this command you can then test the installation with
This will output the current version of the JBrowse CLI.
note
If you can't or don't want to globally install the JBrowse CLI, you can also use
the npx command, which
is included with Node.js, to run JBrowse CLI without installing it. Simply
replace jbrowse with npx @jbrowse/cli in any command, e.g.
Using jbrowse create to download JBrowse 2
In the directory where you would like to download JBrowse 2, run this command
Downloading using the JBrowse CLI
You can also download JBrowse 2 manually. Go to the
releases page of the
JBrowse 2 GitHub repository and find the latest release that is tagged
@jbrowse/web. Download the ZIP file from that release. Make sure it is the ZIP
file that starts with jbrowse-web- and not the "Source code" ZIP file. Once
you have downloaded the ZIP file, extract it to the location you would like to
have JBrowse 2.
Checking the download
Whether you used the JBrowse CLI or downloaded manually, the directory where you downloaded JBrowse should look something like this:
Running JBrowse 2
JBrowse 2 requires a web server to run. It won't work if you try to directly
open the index.html in your web browser. We can use a simple server to check
that JBrowse 2 has been downloaded properly. Run
This will start a web server in our JBrowse 2 directory. Navigate to the
location specified in the tool's output. It will look something like
http://localhost:5000. Once at that page, you should see a page that says that
the configuration is not found. That is expected, since we haven't configured
JBrowse 2 yet. It will look something like this:
Go ahead an click on the sample config to see a JBrowse 2 running with a demo configuration. It should look like this:
Congratulations! You're running JBrowse 2.
Next steps
Now that JBrowse 2 is set up, you can configure it with your own genomes and tracks. There are two ways you can configure JBrowse 2: with the JBrowse CLI (guide here) or with JBrowse 2's built-in graphical configuration editing (guide here).
Config editing quick start — command-line interface
In order to display your data, JBrowse 2 needs to know about the reference genome for your organism of interest and needs to have tracks created that reference your data sources. This guide will show you how to set those up using the JBrowse CLI.
note
You can also do this configuration with graphical configuration editing interface built into JBrowse 2. See that guide here.
Pre-requisites
Adding a genome assembly
info
For this step we configure JBrowse to use files being hosted at a URL. For an example of how to use files located on your computer, see the adding a track step.
First we will configure an assembly, or reference genome, for for JBrowse 2. This usually means providing a file that describes the reference sequence for the organism, such as a FASTA or 2BIT file.
You will want to use your own data for your organism, but for this example we provide a small example reference sequence for a simulated organism, volvox mythicus, that you can use.
caution
A FASTA must have an index to work in JBrowse 2. This command assumes that the
index file is the same as the FASTA but with .fai appended to the file name.
This command will generate a config file if one does not exist yet and add an
assembly called "volvox" to the config file with the URLs of the FASTA and FASTA
index files. The name of the assembly was guessed from the file name, but you
can customize that and many other things with various flags passed to the
command. You can run jbrowse add-assembly --help to get a list of all the
options.
JBrowse 2 also supports other assembly file formats, such as bgzip-compressed
indexed FASTA (e.g. .fa.gz, .fa.gz.fai, and .fa.gz.gzi files) and 2BIT
files. See configuring assemblies for more info
on formats supported for the sequence file.
note
If your FASTA is not indexed, you can use the samtools tool to index it.
Or if you want to compress your FASTA, you can use bgzip as well.
For more info about bgzip and samtools, see https://www.htslib.org/.
If you have your JBrowse 2 running as described in the JBrowse web quickstart, you can refresh the page and an add a linear genome view. You will now see your config in the Assembly dropdown.
Adding a track
Now we will show you how to add an alignments track and a variant track to JBrowse 2.
info
For this step we configure JBrowse to use files located on your computer. For an example of how to use files hosted at a URL, see the adding a genome assembly step.
Adding an alignments track
For this example we will use a BAM file to add an alignments track. Again, for this example we provide a small example BAM, but for your data you will replace the file name with the names of your data files.
For this track we will assume the data is on your computer at the locations
/data/volvox.bam and /data/volvox.bam.bai. You can download these file here
if you want to run this example:
BAM and
BAM index.
To add the track, run
This will copy the BAM and BAM index into the JBrowse 2 directory and add a
track pointing at those files to the config file. To see more options adding the
track, such as specifying a name, run jbrowse add-track --help.
If you don't want to copy your BAM file, you can use --move to move the file
into the JBrowse 2 directory or --symlink to add a symlink to the file to the
JBrowse 2 directory. If you want more control over the location, you can use
inPlace to point the track at the file where it is, but be careful with this
option because on a traditional server you will need to ensure that the file is
in a place where the web server is serving it.
note
If your BAM is not indexed, you can use the samtools tool to index it.
For more info about samtools, see https://www.htslib.org/.
If you have your JBrowse 2 running as described in the JBrowse web quickstart, you can refresh the page and an add a linear genome view of the volvox assembly. Then open track selector, and you will see the alignments track.
Adding a variant track
Adding a variant track is similar to adding an alignments track. For this
example, we will use a VCF file for the track. JBrowse 2 expects VCFs to be
compressed with bgzip and indexed. Similar to the above example, we will
assume the files are at /data/volvox.vcf.gz and /data/volvox.vcf.gz.tbi. You
can download these file here:
VCF and
VCF index.
To add the track, run
note
If your VCF is not indexed, you can use the bgzip and tabix tools to
compress index it.
Alternatively, you can do the same thing with the bcftools tool.
For more info about bgzip, tabix, and bcftools, see
https://www.htslib.org/.
If you have your JBrowse 2 running as described in the JBrowse web quickstart, you can refresh the page and an add a linear genome view of the volvox assembly. Then open track selector, and you will see the variant track.
Conclusion
Now that you have JBrowse configured with an assembly and a couple of tracks, you can start customizing it further. Check out the rest of the docs for more information, especially the JBrowse CLI docs for more details on some of the steps shown here.
Config editing quick start — graphical interface
In order to display your data, JBrowse 2 needs to know about the reference genome for your organism of interest and needs to have tracks created that reference your data sources. This guide will show you how to set those up using the JBrowse 2's graphical configuration editing.
note
You can also do this configuration with JBrowse CLI. See that guide here.
Pre-requisites
This tutorial requires having the following software installed
Starting JBrowse 2 admin server
The JBrowse CLI contains a tool called admin-server. This will act as a web
server for JBrowse 2 and will write any changes made in JBrowse 2 to a config
file. The admin-server is meant to be run only temporarily to help you set up
your config, it is not used for serving your jbrowse instance in production.
The admin-server launches an instance of JBrowse 2 in "admin mode", which then
lets you
- Add and edit assemblies with the "Assembly manager"
- Add tracks and edit tracks
- Add and edit connections
All of these changes will be written by the server to the JBrowse config file
(usually config.json) located in the JBrowse instance. This is something that
can only be done while the admin-server is running, which again, is only meant
to be temporary!
To start the admin-server, navigate into your JBrowse 2 directory and run
This will then generate a link that you can visit in your web browser
warning
Note: the admin-server is meant to be used temporarily for configuration, not in production
Adding a genome assembly
A key first step in configuring a genome browser is adding an assembly to view.
In order to do this, use the navigation bar to open up the Assembly Manager
(Admin > Open Assembly Manager).
This opens up a table which can be used to create, edit, and delete assemblies in your application
Let's add the hg38 human reference genome to our JBrowse 2 application.
Press the "Add New Assembly" button, and enter hg38 as the assembly name in
the text field
Click on "Create New Assembly". Great, we've added an assembly! Now, in the configuration editor, add an alias, and configure the adapter to point the hg38 genome hosted by JBrowse:
- fasta:
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz - fasta index:
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai - gzi:
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi
Figure showing the settings
After clicking the back arrow to return to the table of assemblies, we see that we have successfully added the hg38 assembly.
Figure showing the assembly manager
The assembly can be edited or deleted, but for now we will return to the application.
Editing a genome assembly
After you've added a genome assembly, you can use the pencil icon button in the Assembly manager to edit that assembly. You can also delete assemblies from the assembly manager.
Adding a track
To add a new track or connection, you can use the menu bar in the app to open
the form for adding a track File > Open Track:
Alternatively, you can use the action button (circular "+") inside the track selector to access the "Add track" form.
In the "Add track" form, you can provide a URL to a file to load. Opening files from your local machine is not supported currently in the JBrowse 2 web app (JBrowse desktop does allow this, though, and this functionality may be added in some form in the future)
Paste a URL to a file and optionally provide an index file URL too. The following file formats are supported
tabix-indexed VCFtabix-indexed BEDtabix-indexed GFF- indexed BAM
- indexed CRAM
- BigWig
- BigBed
- Hi-C (Juicebox)
For tabix files, TBI or CSI indexes are allowed. CSI or BAI is allowed for BAM. Only CRAI is allowed for CRAM. The index will be inferred for BAI or TBI files as e.g. filename+'.bai'. If it is different from this, make sure to specify the index file explicitly.
Editing a track
First we will open a Linear Genome View using the navigation bar
(File > Add > Linear Genome View), and click on the "Select Tracks" button.
The configuration settings are accessible by clicking on the ellipses by each track.
Figure showing the configuration editor
Open the configuration editor for the track by clicking on the "Settings" button shown above. You can use the configuration editor to live-edit any configurable value for a given track.
Additional resources
There are a number of additional features for configuring JBrowse 2. Make sure to refer to the config guide for topics such as adding tracks or adding an assembly with the CLI
Conclusion
This quickstart showed how to launch the admin-server in the JBrowse CLI to
perform graphical configuration of your application. Specifically, we looked at
how to access and use the assembly manager, as well as how to access the
configuration editor for tracks. Importantly, all tracks have different
configuration options available in the configuration editor.
Make sure to take a look at any tracks you add to JBrowse 2 that you might want to further configure!
Quick start for JBrowse desktop
Important note on JBrowse desktop
We do not have downloads of JBrowse 2 Desktop yet, it is expecting a release in late 2020
Installing JBrowse desktop
This guide will walk you through installing jbrowse 2 on the desktop
JBrowse 2 desktop does not require any pre-requisites for your installation, so we can jump right in
Installing on Linux
Visit http://github.com/gmod/jbrowse-components/releases/latest
Download the latest release artifact with linux in the name
Unzip the file, open the directory, and run the file named "JBrowse 2" in the terminal with
Installing on MacOS
Visit http://github.com/gmod/jbrowse-components/releases/latest and find the latest MacOS release artifact in our latest builds
You can then unzip this download and the "JBrowse 2" app will be unzipped to this folder. You can then run JBrowse 2 from clicking this file.
Finder window showing the downloaded zip file and unzipped contents
To run JBrowse 2, you can launch the unzipped app, however if you double click on the file it may give you a warning about running a program from an unauthorized developer since JBrowse 2 isn't registered with Mac's app store
In order to properly launch JBrowse 2
- Right-click or hold control and click "JBrowse 2" app in the Finder
- Select "Open" from the context menu
- The warning will pop up again but with the option to run icon
Reference https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac
The \"open app from unauthorized developer\" after right-clicking and selecting \"open\"
Installing on Windows
Visit http://github.com/gmod/jbrowse-components/releases/latest
You can then unzip this file and run the file that comes from unzipping it. Moving this file to the Applications folder is also equivalent to "installing" JBrowse 2
Then open up the Windows Explorer in the unzipped directory and run "JBrowse 2.exe". This may give a "Windows protected your PC" warning, but select "More info..." and then "Run anyway"
User guide
Navigating the UI
Linear genome view usage
To start a linear genome view, use the menu bar
File->Add->Linear genome view
Using the location search box
- Use the search box in the LGV
- Enter syntax chr1:1-100 or chr1:1..100
- You can also specify an assembly name with the locstring {hg19}chr1:1-100
Note: searching by gene name is not yet available but will be added soon!
Scrolling
Mouse wheel can scroll side to side, as well as click and drag. The pan buttons also exist in the header of the linear genome view
Zooming
The zoom buttons exist in the header of the linear genome view, and there is also a slider bar to zoom in and out.
Note: You can also hold the "Ctrl" key and use your mousewheel or trackpad to scroll and this will zoom in and out
Re-ordering tracks
There is a drag handle on the track labels indicating by the six dots, clicking and dragging on this part of the track label can reorder tracks
Adding tracks
To add a new track or connection, you can use the menu bar in the app to open the form for adding a track:
File->Open Track
The \"Add track form\"
Note: There is also a circular "+" button inside the track selector menu that can also be used to access the "Add track" form.
The \"Add track button\" in the tracklist
In the "Add track" form, you can provide a URL to a file to load. Opening files from your local machine is not supported currently in the jbrowse-web app (jbrowse-desktop does allow this though, and may be added to jbrowse-web in the future)
Paste a URL to a file and optionally provide an index file URL too. The following file formats are supported
- Tabixed VCF
- Tabixed BED
- Tabixed GFF
- BAM
- CRAM
- BigWig
- BigBed
- .hic file (Juicebox)
For tabix files, TBI or CSI indexes are allowed. CSI or BAI is allowed for BAM. Only CRAI is allowed for CRAM. The index will be inferred for BAI or TBI files as filename+'.bai' for example, but if it is different than this, make sure to specify the index file explicitly.
Note: If you are an administrator, you can add tracks with the command line or with the admin server add-track or admin-server guide
Sharing sessions
The main menu bar has a "Share" button to enable users to share their sessions with other people. The share button generates a URL that can be sent to other users. It is not possible to copy your URL bar and send this to another user currently, because sessions can become too large for the address bar in many cases.
Note that you can copy and paste URLs between different tabs in your local browser though
The session URL will contain
- what views are on the screen, and settings for the views (e.g. track labels overlapping or offset)
- what tracks are in the view
- extra tracks that you added with the "Add track workflow"
- for the alignments track, the show soft clipping and sort settings on the pileup
- etc
All this stuff gets included in the session
This means you can share links with your custom tracks with other users, without being a JBrowse admin!
Editing track configs
Currently, in order to edit a track config, you have to make a copy of the track
Figure showing how to copy a track, note that settings button is disabled
because we don't \"own this track\" as a non-privileged user
After you have copied the track, you can edit the track settings
Figure showing the settings button is now enabled on the session track, and you
have full control over your session tracks
Your new track is a so-called "session track" and can be shared with other users with the "Share" button
Rubberband selection
The scale bars accept a click and drag action to select a region
Rubberband selection can be performed on both the region and overview scale bars
Track label positioning
Track labels can be positioned on their own row or overlapping the data to save vertical screen space. They can also be hidden. This is done by clicking on the hamburger menu for a specific view.
Example of using the overlap and offset track label positioning options
Horizontally flip
The view can be horizontally flipped, or reverse complemented, to make the coordinates go from right to left instead of left to right
We use triangles pointing in the direction of the orientation in the overview bar to help indicate whether the app is horizontally flipped or not
Here is an example of before and after horizontally flipping the view
Before and after horizontally flipping
Alignments tracks
Visualizing alignments is an important aspect of genome browsers. This guide will go over the main features of the "Alignments track"
The alignments track is a combination of a pileup and a coverage visualization
Pileup visualization
The pileup is the lower part of the alignments track and shows each of the reads as boxes positioned on the genome.
By default the reads are colored red if they aligned to the forward strand of the reference genome, or blue if they aligned to the reverse strand.
Coverage visualization
The coverage visualization shows the depth-of-coverage of the reads at each position on the genome, and also draws using colored boxes any occurrence of mismatches between the read and the reference genome, so if 50% of the reads had a T instead of the reference A, half the height of the coverage histogram would contain a 'red' box
Screenshot showing the alignments track, which contains both a
coverage view at the top and a pileup view at the bottom
Show soft clipping
If a read contains bases that do not map the the genome properly, they can either be removed from the alignment (hard clipping) or can be included, and not shown by default (soft clipping)
JBrowse 2 also contains an option to "show the soft clipping" that has occurred. This can be valuable to show the signal around a region that contains structural variation or difficult mappability
Shows what turning on soft-clipping enables for a simulated long-read
dataset. There is a simulated structural variant, a deletion, at this position,
so the read has bases that map to the other side of the deletion being revealed
by this.
Sort by options
The alignments tracks can also be configured to "sort by" a specific attribute for reads that span the center line.
By default the center line is not shown, but by showing it (Go to the view's hamburger menu->Select "Show center line") then you will obtain a better idea of what the "sort by" option is doing
Showing the center line
Here is how to turn on the center line
- Open the hamburger menu in the top left of the linear genome view
- Select "Show center line"
Illustrates before and after turning on the center line. The center line is an
indicator that shows what base pair underlies the center of the view. Note that
this is used in the \"Sort by\" option discussed below; the sort is performed
using properties of the feature or even exact base pair underlying the center
line
Sorting by base
Sorting by base will re-arrange the pileup so that the reads that have a specific base-pair mutation at the position crossing the center line (which is 1bp wide) will be arranged in a sorted manner. To enable Sort by base
- Open the track menu for the specific track using the vertical '...' in the track label
- Select 'Sort by'->'Base pair'
Illustrating the pileup re-ordering that happens when turning on the Sort by->Base pair. The sorting is done by specifically what letter of each
read underlies the current center line position (the center line is 1bp wide,
so sorted by that exact letter)
There are other sorting options available and more to come. If you have any requests please drop us a line via github here
BigWig tracks
Visualizing genome signals, whether it is read depth-of-coverage or other signal, can often be done by using BigWig files
This figure shows a BigWig using the XY plot renderer
Line plot version of a BigWig
There are many options for controlling the BigWig which can be accessed from the UI. See the bigwig configuration guide
Linear synteny and dotplot views
The dotplot view is a 2D comparative view that can display alignments between different genome assemblies, or even compare a long-read or NGS short-read versus the genome
Opening a dotplot view
Currently the workflow for launching a dotplot is done by navigating in the header bar to the File->Add->Dotplot view
This will let you select the genome assemblies of interest
Then you can also provide a synteny file in the form of PAF via the Add track workflow
Then currently you must configuration edit the PAFAdapter to indicate the two assemblies in the PAFAdapter
Adding a new dotplot or synteny view via the menubar
Example of the import form for a dotplot or synteny view. Allows you to select
two different assemblies and a PAF file can be supplied via a URL
Example of a dotplot visualization of the grape vs the peach genome
See the dotplot configuration for more detailed descriptions
Opening a linear synteny view
Use the main menu bar to select
File->Add->Linear synteny view
Adding a new linear-synteny-view via the menubar
Example of the import form for a synteny view allowing you to select two
different assemblies and optionally adding a PAF file via a URL
Figure showing grape vs peach synteny
See the linear synteny configuration for more details on manually configuring the synteny view
Long read vs reference plots
One can also launch a dotplot view that compares a long read to the reference genome by
- Right clicking an alignment
- Select "Dotplot read vs ref" or "Linear read vs ref" in the context menu
Example of a dotplot of a long read vs the reference genome
Example of a \"synteny\" view of a long read vs the reference genome
Hi-C tracks
Visualizing Hi-C data can be performed with .hic files which are generated by the Juicebox software suite. It uses the hic-straw module developed by the juicebox/igv.js team to visualize it in jbrowse.
Currently configuration options are basic for Hi-C tracks, see configuration for info about configuring Hi-C
tracks
Screenshot showing a Hi-C track
SV inspector
The SV inspector is a "workflow" that is designed to help users inspect structural variant calls
Opening the SV inspector
We can start the SV inspector by launching it from the App level menu bar
The SV inspector can be launched from the main menu bar
This will bring up an "import form" that asks you for your SV evidence. This can be provided using a URL in these formats:
- VCF (plain text VCF, not tabix VCF)
- BEDPE
- STAR-fusion result file
- or other formats
SV inspector import form
Example SV inspector workflow
We can start the SV inspector workflow by opening up this file containing translocation events called from a breast cancer cell line SKBR3, based on these published data http://schatz-lab.org/publications/SKBR3/
Copy this URL and paste it into the import form and select hg19
SV inspector import form with URL
SV inspector results
After loading the user's requested file, you will have a spreadsheet with each row representing a row of the file you opened, along with a whole-genome overview of the SVs on the right
SV inspector with loaded results
Now here is where things can become interesting
We can perform searching and filtering on the table, which can filter down the number of rows being displayed, and then this dynamically filters the circos view on the right also.
SV inspector with filter applied
Launching breakpoint split view
By clicking on the features in the Circos, or clicking on the triangle drop-down on the leftmost column of the spreadsheet, we can dynamically launch a new view of the data that is called the "split view" or the "breakpoint split view"
This allows us to inspect the breakpoints of the structural variant, and compare each side to the alignments.
Variant tracks
Visualizing variant tracks from the VCF format alongside the original alignment evidence track is a common workflow for validating your results. In JBrowse 2 we can open a variant track and an alignments track as shown below
Variant track indicating a SNP alongside the alignment track evidence
Variant widget
The variant features have a specialized widget that contains a table indicating all the calls that were made in a multi-sample VCF. Some VCF files, like the 1000 genomes VCF, can contain thousands of samples in a single file. This table can display the details
Future additions
We anticipate adding more features to the variant track in the future including
- Ability to visualize individual samples in a multi-sample VCF as subtracks of a variant track
- Ability to use FILTER the VCF column via the track menu
Config guide
Intro to the config.json
A JBrowse 2 configuration file, a config.json, is structured as follows
The most important thing to configure are your assemblies and your tracks
Configuring assemblies
An assembly configuration includes the "name" of your assembly, any "aliases" that might be associated with that assembly e.g. GRCh37 is sometimes seen as an alias for hg19, and then a "sequence" configuration containing a reference sequence track config. This is provides a special "track" that is outside the normal track config
Here is a complete config.json file containing only a hg19
Configuring reference name aliasing
Reference name aliasing is a process to make chromosomes that are named slightly differently but which refer to the same thing render properly
The refNameAliases in the above config provides this functionality
The hg19_aliases then is a tab delimited file that looks like this
The first column should be the names that are in your FASTA sequence, and the rest of the columns are aliases
Adding an assembly with the CLI
Generally we add a new assembly with the CLI using something like
See our CLI docs for the add-assembly for more details here -- add-assembly
Note: assemblies can also be added graphically using the assembly manager when you are using the so-called admin-server. See the quickstart guide for more details.
Assembly config
Because JBrowse 2 can potentially have multiple assemblies loaded at once, it needs to make sure each track is associated with an assembly.
To do this, we make assemblies a special part of the config, and make sure each track refers to which genome assembly it uses
Example config with hg19 genome assembly loaded
Here is a complete config.json that has the hg19 genome loaded
The top level config is an array of assemblies
Each assembly contains
name- a name to refer to the assembly by. each track that is related to this assembly references this namealiases- sometimes genome assemblies have aliases like hg19, GRCh37, b37p5, etc. while there may be small differences between these different sequences, they often largely have the same coordinates, so you might want to be able to associate tracks from these different assemblies together. The assembly aliases are most helpful when loading from a UCSC trackHub which specifies the genome assembly names it uses, so you can connect to a UCSC trackHub if your assembly name or aliases match.sequence- this is a complete "track" definition for your genome assembly. we specify that it is a track of type ReferenceSequenceTrack, give it a trackId, and an adapter configuration. an adapter configuration can specify IndexedFastaAdapter (fasta.fa and fasta.fai), BgzipFastaAdapter (fasta.fa.gz, fasta.fa.gz.fai, fasta.gz.gzi), ChromSizesAdapter (which fetches no sequences, just chromosome names)
ReferenceSequenceTrack
Example ReferenceSequenceTrack config, which as above, is specified as the child of the assembly section of the config
BgzipFastaAdapter
A bgzip FASTA format file is generated by
These are loaded into a BgzipFastaAdapter as follows
IndexedFastaAdapter
An indexed FASTA file is similar to the above, but the sequence is not compressed
These are loaded into a IndexedFastaAdapter as follows
TwoBitAdapter
The UCSC twoBit adapter is also supported. Note however that the 2bit format has a longer startup time than other adapters because there is a larger upfront parsing time.
Track configurations
All tracks can contain
- trackId - internal track ID, must be unique
- name - displayed track name
- assemblyNames - an array of assembly names a track is associated with, often just a single assemblyName
- category - (optional) array of categories to display in a hierarchical track selector
Example config.json containing a track config
AlignmentsTrack config
Example AlignmentsTrack config
BamAdapter configuration options
- bamLocation - a 'file location' for the BAM
- index: a subconfiguration schema containing
- indexType: options BAI or CSI. default: BAI
- location: a 'file location' of the index
Example BamAdapter config
CramAdapter configuration options
- cramLocation - a 'file location' for the CRAM
- craiLocation - a 'file location' for the CRAI
Example CramAdapter config
HicTrack config
Example Hi-C track config
HicAdapter config
We just simply supply a hicLocation currently for the HicAdapter
HicRenderer config
baseColor- the default baseColor of the Hi-C plot is red #f00, you can change it to blue so then the shading will be done in blue with #00fcolor- this is a color callback that adapts the current Hi-C contact feature with the baseColor to generate a shaded block. The default color callback function isfunction(count, maxScore, baseColor) { return baseColor.alpha(Math.min(1,counts/(maxScore/20))).hsl().string() }where it receives the count for a particular block, the maxScore over the region, and the baseColor from the baseColor config
VariantTrack config
- defaultRendering - options: 'pileup' or 'svg'. default 'svg'
- adapter - a variant type adapter config e.g. a VcfTabixAdapter
Example config
VcfTabixAdapter configuration options
- vcfGzLocation - a 'file location' for the BigWig
- index: a subconfiguration schema containing
- indexType: options TBI or CSI. default TBI
- location: the location of the index
Example VcfTabixAdapter adapter config
WiggleTrack config
Example WiggleTrack config
General WiggleTrack options
- scaleType - options: linear, log, to display the coverage data. default: linear
- adapter - an adapter that returns numeric signal data, e.g. feature.get('score')
Autoscale options for WiggleTrack
Options for autoscale
- local - min/max values of what is visible on the screen
- global - min/max values in the entire dataset
- localsd - mean value +- N stddevs of what is visible on screen
- globalsd - mean value +/- N stddevs of everything in the dataset
Score min/max for WiggleTrack
These options overrides the autoscale options and provides a minimum or maximum value for the autoscale bar
- minScore
- maxScore
WiggleTrack drawing options
- inverted - draws upside down
- defaultRendering - can be density, xyplot, or line
- summaryScoreMode - options: min, max, whiskers
WiggleTrack renderer options
- filled - fills in the XYPlot histogram
- bicolorPivot - options: numeric, mean, none. default: numeric
- bicolorPivotValue - number at which the color switches from posColor to negColor. default: 0
- color - color or color callback for drawing the values. overrides posColor/negColor. default: none
- posColor - color to draw "positive" values. default: red
- negColor - color to draw "negative" values. default: blue
- clipColor - color to draw "clip" indicator. default: red
BigWigAdapter options
- bigWigLocation - a 'file location' for the bigwig
Example BigWig adapter config
SyntenyTrack config
Example SyntenyTrack config
We can add a SyntenyTrack from PAF with the CLI e.g. with
DotplotView config
The configuration of a view is technically a configuration of the "state of the
view" but it can be added to the defaultSession
An example of a dotplot config can help explain. This is relatively advanced so let's look at an example
Note that configuring the dotplot involves creating a "defaultSession"
Users can also open synteny views using the File->Add->Dotplot view workflow, and create their own synteny view outside of the default configuration
LinearSyntenyView config
Currently, configuring synteny is made by pre-configuring a session in the view and adding synteny tracks
Configuring the theme
Color
The color scheme as well as some sizing options can be configured via the theme. This is done via a top-level configuration in the config file. For example:
JBrowse uses 4 colors that can be changed. For example, this is the default theme:
Example of the default theme
Example of a customized theme
The customized theme screenshot uses the below configuration
| Color code | Color | |
|---|---|---|
| Primary | #311b92 | Deep purple |
| Secondary | #0097a7 | Cyan |
| Tertiary | #f57c00 | Orange |
| Quaternary | #d50000 | Red |
Sizing
You can also change some sizing options by specifying the "typography" (to change font size) and "spacing" (to change the amount of space between elements) options:
Advanced
JBrowse uses Material-UI for its theming. You can read more about Material-UI
themes here. Generally, most
options you could pass to Material-UI's
createMuiTheme
should work in the theme configuration.
Disabling analytics
This is done via adding a field in the global configuration in the config file. For example:
Command line tools
This document covers the CLI tools.
Installation
The command line tools can be installed using npm as follows
You can test your installation with
It is also possible to do one-off executions using npx, e.g.
It is likely preferable in most cases to install the tools first however
Commands
jbrowse add-assembly SEQUENCEjbrowse add-connection CONNECTIONURLORPATHjbrowse add-track TRACKjbrowse add-track-json TRACKjbrowse admin-serverjbrowse create LOCALPATHjbrowse help [COMMAND]jbrowse set-default-sessionjbrowse upgrade [LOCALPATH]
jbrowse add-assembly SEQUENCE
Add an assembly to a JBrowse 2 configuration
See code: src/commands/add-assembly.ts
jbrowse add-connection CONNECTIONURLORPATH
Add a connection to a JBrowse 2 configuration
See code: src/commands/add-connection.ts
jbrowse add-track TRACK
Add a track to a JBrowse 2 configuration
See code: src/commands/add-track.ts
jbrowse add-track-json TRACK
Add a track configuration directly from a JSON hunk to the JBrowse 2 configuration
See code: src/commands/add-track-json.ts
jbrowse admin-server
Start up a small admin server for JBrowse configuration
See code: src/commands/admin-server.ts
jbrowse create LOCALPATH
Downloads and installs the latest JBrowse 2 release
See code: src/commands/create.ts
jbrowse help [COMMAND]
display help for jbrowse
See code: @oclif/plugin-help
jbrowse set-default-session
Set a default session with views and tracks
See code: src/commands/set-default-session.ts
jbrowse upgrade [LOCALPATH]
Upgrades JBrowse 2 to latest version
See code: src/commands/upgrade.ts
Debugging
Debug logs (provided by debug) can be
printed by setting the DEBUG environment variable. Setting DEBUG=* will
print all debug logs. Setting DEBUG=jbrowse* will print only logs from this
tool, and setting e.g. DEBUG=jbrowse:add-assembly will print only logs from
the add-assembly command.
Developer guide
In this Developer Guide, will introduce the JBrowse 2 ecosystem from the developer's point of view. We'll examine the core concepts of how code is packaged and structured, and then go over how to create new plugins and pluggable elements.
Introduction and overview
Let's get a high-level view of the JBrowse 2 ecosystem.
Products and plugins
The JBrowse 2 ecosystem has two main type of top-level artifacts that are published on their own: products and plugins.
Architecture diagram of JBrowse 2, showing how plugins encapsulate views (e.g. LinearGenomeView, DotplotView etc.), tracks (AlignmentsTrack, VariantTrack, etc.), data adapters (BamAdapter, VcfTabixAdapter, etc.) and other logic like mobx state tree autoruns that add logic to other parts of the app (e.g. adding context menus)
A "product" is an application of some kind that is published on its own (a web
app, an electron app, a CLI app, etc). jbrowse-web, jbrowse-desktop, and
jbrowse-cli are products.
A "plugin" is a package of functionality that is designed to "plug in" to a product at runtime to add functionality. These can be written and published by anyone, not just the JBrowse core team. Not all of the products use plugins, but most of them do.
Also, most of the products are pretty standard in the way they are constructed. For example, jbrowse-web is a React web application that is made with Create React App (CRA), and jbrowse-cli is a command-line tool implemented with OCLIF.
This figure summarizes the general architecture of our state model and React
component tree
What's in a plugin
A plugin is an independently distributed package of code that is designed to "plug in" to a JBrowse application.
It's implemented as a class that extends @jbrowse/core/Plugin. It gets
instantiated by the application that it plugs into, and it has an install
method and a configure method that the application calls. This class is
distributed as a webpack bundle that exports it to a namespace on the browser's
window object specifically for JBrowse plugins1.
It's common for a plugin to use have its configure method set up mobx
autoruns or reactions that react to
changes in the application's state to modify its behavior.
Plugins often also have their install method add "pluggable elements" into
the host JBrowse application. This is how plugins can add new kinds of views,
tracks, renderers, and so forth.
Pluggable elements
Pluggable elements are basic "extension points" that you can customize in JBrowse 2 plugins
The pluggable types that we have in JBrowse 2 are
- Data adapters
- Track types
- Renderer types
- Widgets
- RPC calls
- View types
In additional to creating plugins that create new data adapters, track types, etc. note that you can also wrap the behavior of another track so these elements are composable
For example we can have adapters that perform calculations on the results of another adapter, views that contains other subviews, and tracks that contain other tracks, leading to a lot of interesting behavior. Details and examples below
Data adapters
Data adapters basically are parsers for a given data format. We will review what data adapters the alignments plugin has (to write your own data adapter, see creating data adapters)
Example data adapters: the @jbrowse/plugin-alignments plugin creates
multiple data adapter types
BamAdapter- This adapter uses the@gmod/bamNPM module, and adapts it for use by the browser.CramAdapter- This adapter uses the@gmod/cramNPM module. Note that CramAdapter also takes a sequenceAdapter as a subadapter configuration, and uses getSubAdapter to instantiate itSNPCoverageAdapter- this adapter takes aBamAdapterorCramAdapteras a subadapter, and calculates feature coverage from it
Renderers
Renderers are a new concept in JBrowse 2, and are related to the concept of server side rendering (SSR), but can be used not just on the server but also in contexts like the web worker (e.g. the webworker can draw the features to an OffscreenCanvas). For more info see creating renderers
Example renderers: the @jbrowse/plugin-alignments exports several
renderer types
PileupRenderer- a renderer type that renders Pileup type display of alignments fetched from theBamAdapter/CramAdapterSNPCoverageRenderer- a renderer that draws the coverage. Note that this renderer derives from the wiggle renderer, but does the additional step of drawing the mismatches over the coverage track
Track types
Track types are a high level type that controls how features are drawn. In most cases, a track combines a renderer and an adapter, and can do additional things like
- Control what widget pops up on feature click
- Add extra menu items to the track menu
- Create subtracks (See
AlignmentsTrack) - Choose "static-blocks" rendering styles, which keeps contents stable while the user scrolls, or "dynamic-blocks" that update on each scroll
Example tracks: the @jbrowse/plugin-alignments exports multiple track
types
SNPCoverageTrack- this track type actually derives from the WiggleTrack typePileupTrack- a track type that draws alignment pileup resultsAlignmentsTrack- combinesSNPCoverageTrackandPileupTrackas "subtracks"
Widgets
Widgets are custom info panels that can show up in side panels, modals, or other places in an app
Widgets can do multiple types of things including
- Configuration widget
- Feature detail widget
- Add track widget
- Add connection widget
- etc.
These widgets can be extended via plugins, so for example, the
@jbrowse/plugin-alignments extends the BaseFeatureDetailWidget to
have custom display of the alignments
AlignmentsFeatureDetailWidget- this provides a custom widget for viewing the feature details of alignments features that customizes the basic feature detail widget
View types
Creating view types is one of the most powerful features of JBrowse 2, because it allows us to put entirely different visualizations in the same context as the standard linear-genome-view.
We have demonstrated a couple new view types in JBrowse 2 already including
LinearGenomeView- the classic linear view of a genomeCircularView- a Circos-style whole genome viewDotplotView- a comparative 2-D genome viewSvInspectorView- superview containingCircularViewandSpreadsheetViewsubviews- And more!
We think the boundaries for this are just your imagination, and there can also be interplay between view types e.g. popup dotplot from a linear view, etc.
RPC methods
Plugins can register their own RPC methods, which can allow them to offload
custom behaviors to a web-worker or server side process. The Wiggle track for
example registers WiggleGetGlobalStats and WiggleGetMultiRegionStats
MenuItems
You can add menus or add items to existing menus in several places.
A MenuItem object defines the menu item's text, icon, action, and other attributes.
Types of MenuItems:
- Normal: a standard menu item that performs an action when clicked
- Checkbox: a menu item that has a checkbox
- Radio: a menu item that has a radio button icon
- Divider: a horizontal line (not clickable) that can be used to visually divide menus
- SubHeader: text (not clickable) that can be used to visually label a section of a menu
- SubMenu: contains menu items, for making nested menus
| Name | Description |
|---|---|
| type | Options are 'normal', 'radio', 'checkbox', 'subMenu', 'subHeader', or 'divider'. If not provided, defaults to 'normal', unless a subMenu attribute is present, in which case it defaults to 'subMenu'. |
| label | The text for the menu item. Not applicable to 'divider', required for all others. |
| subLabel | Additional descriptive text for the menu item. Not applicable to 'divider' or 'subHeader', optional for all others. |
| icon | An icon for the menu item. Must be compatible with Material-UI's Icons. Not applicable to 'divider' or 'subHeader', optional for all others. |
| disabled | Whether or not the menu item is disabled (meaning grayed out and not clickable). Not applicable to 'divider' or 'subHeader', optional for all others. |
| checked | Whether or not the checkbox or radio button are selected. Only applicable to 'radio' and 'checkbox' |
| onClick | Callback of action to perform on click. Function signature is (session) => undefined. Required for 'normal', 'radio', and 'checkbox', not applicable to any others. |
| subMenu | An array of menu items. Applicable only to 'subMenu'. |
As an example, the here is an array of MenuItems and the resulting menu:
Figure showing all the options for track menus, generated by the code listing
Adding a top-level menu
These are the menus that appear in the top bar of JBrowse Web and JBrowse
Desktop. By default there are File and Help menus. You can add your own menu,
or you can add menu items or sub-menus to the existing menus and sub-menus.
In the above screenshot, the File menu has several items and an Add
sub-menu, which has more items. You can have arbitrarily deep sub-menus.
You add menus in the configure method of your plugin. Not all JBrowse products
will have to-level menus, though. JBrowse Web and JBrowse Desktop have them, but
something like JBrowse Linear View (which is an just a single view designed to
be embedded in another page) does not. This means you need to check whether or
not menus are supported using isAbstractMenuManager in the configure method.
This way the rest of the plugin will still work if there is not a menu. Here's
an example that adds an "Open My View" item to the File -> Add menu.
This example uses rootModel.appendToSubMenu. These are all the
menu-manipulation methods available on the root model:
appendMenu
Add a top-level menu
Parameters
| Name | Description |
|---|---|
| menuName | Name of the menu to insert. |
Return Value
The new length of the top-level menus array
insertMenu
Insert a top-level menu
Parameters
| Name | Description |
|---|---|
| menuName | Name of the menu to insert. |
| position | Position to insert menu. If negative, counts from the end, e.g. insertMenu('My Menu', -1) will insert the menu as the second-to-last one. |
Return Value
The new length of the top-level menus array
appendToMenu
Add a menu item to a top-level menu
Parameters
| Name | Description |
|---|---|
| menuName | Name of the top-level menu to append to. |
| menuItem | Menu item to append. |
Return Value
The new length of the menu
insertInMenu
Insert a menu item into a top-level menu
Parameters
| Name | Description |
|---|---|
| menuName | Name of the top-level menu to insert into. |
| menuItem | Menu item to insert. |
| position | Position to insert menu item. If negative, counts from the end, e.g. insertMenu('My Menu', -1) will insert the menu as the second-to-last one. |
Return Value
The new length of the menu
appendToSubMenu
Add a menu item to a sub-menu
Parameters
| Name | Description |
|---|---|
| menuPath | Path to the sub-menu to add to, starting with the top-level menu (e.g. ['File', 'Insert']). |
| menuItem | Menu item to append. |
Return Value
The new length of the sub-menu
insertInSubMenu
Insert a menu item into a sub-menu
Parameters
| Name | Description |
|---|---|
| menuPath | Path to the sub-menu to add to, starting with the top-level menu (e.g. ['File', 'Insert']). |
| menuItem | Menu item to insert. |
| position | Position to insert menu item. If negative, counts from the end, e.g. insertMenu('My Menu', -1) will insert the menu as the second-to-last one. |
Return Value
The new length of the sub-menu
Adding menu items to a custom track
If you create a custom track, you can populate the track menu items in it using
the trackMenuItems property in the track model. For example:
Adding track context menu items
When you right-click in a linear track, a context menu will appear if there are
any menu items defined for it. It's possible to add items to that menu, and you
can also have different menu items based on if the click was on a feature or
not, and based on what feature is clicked. This is done by adding a callback
that takes the feature and track and returns a list of menu items to add based
on those. This has to be done via a mobx autorun because it needs to add the
callback to tracks after they are created. Here is an example:
Monorepo code organization
JBrowse 2 code is organized as a monorepo using lerna
and yarn workspaces. Using a
monorepo means that instead of separate GitHub repositories for each piece of
JBrowse, they are all in a single place and can share code easily. In the top
level of the repository there are two directories, packages/ and products/
that each contain multiple packages.
Each "package" is an npm-style (i.e. contains package.json) package. The
packages in packages/ are core code, development tools, etc. The packages in
plugins/ are JBrowse plugins. Most of JBrowse is written as plugins, so that
is where most of the code is. The packages in products/ are user-facing
products, such as JBrowse Web, JBrowse Desktop, JBrowse CLI, etc.
Monorepo packages
The following is a summary of some of the individual packages in the monorepo. It's not a comprehensive list, but will hopefully help familiarize you with how the code is organized.
products/jbrowse-web
This is the full JBrowse Web app. It is built using create-react-app.
It includes many other packages as core plugins, can load other plugins at runtime, and more.
It also currently holds the "integration tests" that we use for our code in
products/jbrowse-web/src/tests.
products/jbrowse-desktop
JBrowse Desktop is our essentially the same as JBrowse Web, but packaged with electron into a desktop app. This gives it the ability to easily load and save tracks based on files on your local filesystem. It also has save sessions locally, and works offline.
products/website
This provides the docusaurus website with docs, blog, and pdf documentation
plugins/alignments
This package provides the "alignments" related features including
- BamAdapter - our BAM parser that wraps @gmod/bam NPM module
- CramAdapter - our CRAM parser that wraps the @gmod/cram NPM module
- PileupTrack type - draws alignments as boxes in a "pileup" style view
- SNPCoverageTrack - draws calculated coverage with mismatches drawn over the coverage
- AlignmentsTrack - a "supertrack" which contains a PileupTrack and SNPCoverageTrack "subtracks"
- AlignmentsFeatureWidget for alignments features
plugins/variants/
Provides variant features including
- VCF tabix parser
- VariantFeatureWidget
- VariantTrack that is basically just a normal track, but has logic to popup the VariantFeatureWidget on feature click
plugins/hic
This provides a HicAdapter based on the .hic file format (ref)
Also a track type and renderer to visualize these
plugins/bed
Provides two bed related data adapters
- BigBedAdapter
- BedTabixAdapter
These can be used with the SvgFeatureRenderer
plugins/wiggle
Provides wiggle track types with different types of rendering formats including
- XYPlotRenderer
- LinePlotRenderer
- DensityRenderer
The WiggleTrack type can swap out these different rendering types, and calculates stats such as max and min score over a region before the region is rendered
plugins/svg
This is the main gene glyphs, which are rendered using SVG
General usage of this involves referencing the SvgFeatureRenderer
plugins/spreadsheet-view
This provides a spreadsheet-in-the-browser that can be used as a data backend to power other views
plugins/circular-view
This provides our 'Circos-style' whole-genome overview of data, especially genomic translocations
plugins/sv-inspector
This is a "superview" type that contains a circular and spreadsheet view as child views
Plugin Build system
Plugins may be built as separate packages that can be distributed on NPM. In
order to streamline development and avoid having to build every plugin before
developing on e.g. JBrowse Web, however, the package.json's "main" entry by
default points to the un-built code (e.g. src/index.ts). JBrowse Web then
takes care of building the plugins itself (see
products/jbrowse-web/rescripts/yarnWorkspacesRescript.js).
When you want to use a built plugin, you can run yarn useDist in the plugin's
package.json, and then run yarn useSrc to restore it when you're done. As an
example, the root-level yarn build that builds all the packages does this to
build all the plugins and then build JBrowse Web and JBrowse Desktop using the
built plugins.
Configuration model concepts
Configuration slot types
Our configuration system is "typed" to facilitate graphical editing of the configuration. Each configuration has a "schema" that lists what "configuration slots" it has. Each configuration slot has a name, description, a type, and a value.
Here is a mostly comprehensive list of config types
- stringEnum - allows assigning one of a limited set of entries, becomes a dropdown box in the GUI
- color - allows selecting a color, becomes a color picker in the GUI
- number - allows entering any numeric value
- string - allows entering any string
- integer - allows entering a integer value
- boolean
- frozen - an arbitrary JSON can be specified in this config slot, becomes textarea in the GUI
- fileLocation - refers to a URL, local file path on desktop, or file blob object in the browser
- text - allows entering a string, becomes textarea in the GUI
- stringArray - allows entering a list of strings, becomes a "todolist" style editor in the GUI where you can add or delete things
- stringArrayMap - allows entering a list of key-value entries
Let's examine the PileupRenderer configuration as an example.
Example config with multiple slot types
This PileupRenderer config contains an example of several different slot types
Accessing config values
So instead of accessing config.displayMode, we say
You might also see in the code like this
Which would be equivalent to calling
Using config callbacks
Config callbacks allow you to have a dynamic color based on some function logic you provide. All config slots can actually become config callback. The arguments that are given to the callback are listed by the 'functionSignature' but must be provided by the calling code (the code reading the config slot). To pass arguments to the a callback we say
That implies the color configuration callback will be passed a feature, so the config callback can be a complex function determining the color to use based on various feature attributes
Example of a config callback
If you had an variant track in your config, and wanted to make a custom config callback for color, it might look like this
This draws all SNV (single nucleotide variants) as green, and other types as purple (insertion, deletion, other structural variant). Note that JSON format doesn't allow fancy multiline
Configuration internals
A configuration is a type of mobx-state-tree model, in which leaf nodes are ConfigSlot types, and other nodes are ConfigurationSchema types.
Configurations are all descendants of a single root configuration, which is
root.configuration.
Configuration types should always be created by the ConfigurationSchema
factory, e.g.
An example of a config schema with a sub-config schema is the BamAdapter, with the index sub-config schema
Reading the sub-config schema is as follows
Creating data adapters
What is a data adapter
A data adapter is essentially a class that parses your data type and returns features that jbrowse will draw
Sometimes, a data adapter can be implemented by itself, e.g. if you are adapting a storeclass that returns genes, then you can use our standard track types for that. If you are making a data adapter for some custom type of data that also needs a custom type of drawing, you may need to implement a data adapter along with a track type and/or renderer
Skeleton of a data adapter
So we see basically something like this, this is stripped down for simplicity
So to make a data adapter, you implement the getRefNames function (optional), the getFeatures function (returns an rxjs observable stream of features, discussed below) and freeResources (optional)
Example data adapter
To take this a little slow let's look at each function individually
This is a more complete description of the class interface that you can implement
What is needed from a data adapter
getRefNames
Returns the refNames that are contained in the file, this is used for "refname renaming" and is optional but highly useful in scenarios like human chromosomes which have, for example, chr1 vs 1.
Returning the refNames used by a given file or resource allows JBrowse to automatically smooth these small naming disparities over. See reference renaming
getFeatures
A function that returns features from the file given a genomic range query e.g. getFeatures(region, options), where region is an object like
The region contains
The options can contain any number of things
- bpPerPx - number: resolution of the genome browser when the features were fetched
- signal - can be used to abort a fetch request when it is no longer needed, from AbortController
- statusCallback - not implemented yet but in the future may allow you to report the status of your loading operations
- headers - set of HTTP headers as a JSON object
We return an rxjs Observable. This is similar to a JBrowse 1 getFeatures call, where we pass each feature to a featureCallback, tell it when we are done with finishCallback, and send errors to errorCallback, except we do all those things with the Observable
Here is a "conversion" of JBrowse 1 getFeatures callbacks to JBrowse 2 observable calls
featureCallback(new SimpleFeature(...))->observer.next(new SimpleFeature(...))finishCallback()->observer.complete()errorCallback(error)->observer.error(error)
freeResources
This is uncommonly used, so most data adapters make this an empty function
Most data adapters in fact use an LRU cache to make resources go away over time instead of manually cleaning up resources
Creating a new plugin
JBrowse 2 plugins can be used to add new pluggable elements (views, tracks, data adapters, etc), and to modify behavior of the application by adding code that watches the application's state. For the full list of what kinds of pluggable element types plugins can add, see the pluggable elements page.
We will go over creating an example plugin. The first thing that we have is a
src/index.js which exports a default class containing the plugin registration
code
src/index.js
src/UCSCAdapter/index.ts
Adding this track to our configuration
We can create a track.json like this
track.json
Then use the jbrowse CLI tool add-track-json
This will automatically add this track to the tracks array of our config.json
Alternatively, we can manually edit this JSON into the config.json.
When we open this track, we should see the GeneHancer regions are drawn as orange blocks.
Creating a custom renderer type
Let's say we want to create a track that connects a gene to it's enhancer. On UCSC the GeneHancer tracks do exactly this. An instance of the UCSC with the GeneHancer tracks is here.
We can see data that we can get for the GeneHancer interactions from the UCSC API like this
Given that the functionality of rendering arcs is so distinct from UCSC API adaptation, we can actually make this a new plugin. Let's imagine starting a new plugin from scratch again
src/index.js
src/ArcRenderer/index.js
The above code is relatively simple but it is fairly quirky. Here are some notes:
- renderers can be run in offscreen or even a node.js canvas, so we do not
assume the
document.createElementexists to create our canvas, instead using a utility function that makes a OffscreenCanvas or node-canvas (depends on context, e.g. webworker or node.js) - the "rendering" component contains the results of our renderer. in this case
it delegates to the
PrerenderedCanvascomponent, a component we use in other places throughout the codebase
Bringing the two together
We can bring these two contexts together with a new track in our config.json. Remember our previous track.json? Now we can edit it to use our own ArcRenderer
track.json
Then add the track
Creating custom renderers
What is a renderer
In JBrowse 1, a track type typically would directly call the data parser and do it's own rendering. In JBrowse 2, the data parsing and rendering is offloaded to a web-worker or other RPC. This allows things to be faster in many cases. This is conceptually related to "server side rendering" or SSR in React terms.
Conceptual diagram of how a track calls a renderer using the RPC
Important note: you can make custom tracks types that do not use this workflow, but it is a built in workflow that works well for the core track types in JBrowse 2.
How to create a new renderer
The fundamental aspect of creating a new renderer is creating a class that implements the "render" function. A renderer is actually a pair of a React component that contains the renderer's output, which we call the "rendering" and the renderer itself
In the above simplified example, our renderer creates a canvas using width and height that are supplied via arguments, and draw a rectangle. We then return a React.createElement call which creates a "rendering" component that will contain the output
Note that the above canvas operations use an OffscreenCanvas for Chrome, or in other browsers serialize the drawing commands to be drawn in the main thread
What are the props passed to the renderer
The typical props that a renderer receives
The layout is available on BoxRendererType renderers so that it can layout things in pileup format, and has an addRect function to get the y-coordinate to render your data at
The features argument is a map of feature ID to the feature itself. To iterate over the features Map, we can use an iterator or convert to an array
Adding custom props to the renderer
Note that track models themselves can extend this using their renderProps function
For example the WiggleTrack has code similar to this, which adds a scaleOpts prop that gets passed to the renderer
Rendering SVG
Our SVG renderer is an example, where it extends the existing built in renderer type with a custom ReactComponent only
Then, we have our Rendering component just be plain React code. This is a highly simplified SVG renderer just to illustrate
Notes:
- The above SVG renderer is highly simplified but serves an example, but it shows that you can have a simple React component that leverages the existing BoxRendererType, so that you do not have to necessarily create your own renderer class
- The renderers receive an array of regions to render, but if they are only equipped to handle one region at a time then they can select only rendering to regions[0]
Overriding the renderer's getFeatures method
Normally, it is sufficient to override the getFeatures function in your dataAdapter
If you want to drastically modify the feature fetching behavior, you can modify the renderer's getFeatures call
The base ServerSideRendererType class has a built-in getFeatures function that, in turn, calls your data adapter's getFeatures function, but if you need tighter control over how your data adapter's getFeatures method is called then your renderer. The Hi-C renderer type does not operate on conventional features and instead works with contact matrices, so the Hi-C renderer has a custom getFeatures function
Creating custom track types
At a high level the track types are just "ReactComponents" that contain rendered track contents. Oftentimes, for custom drawing, we create a renderer instead of a track, but here are some reasons you might want a custom track
- Drawing custom things over the rendered content (e.g. drawing the Y-scale bar in the wiggle track)
- Implementing custom track menu items (e.g. Show soft clipping in the alignments track)
- Adding custom widgets (e.g. custom VariantFeatureWidget in variant track)
- You want to bundle your renderer and adapter as a specific thing that is automatically initialized rather than the BasicTrack (which combines any adapter and renderer)
What does creating a track look like
When you create your plugin, you will add a cCreating a custom track is basically looks like this
You have your config schema
What are the details of configSchema and stateModel
- stateModel - a mobx-state-tree object that manages track logic
- configSchema - a combination of a "stateModel" and a "configSchema"
The state model is often implemented as a composition of the "base track" and some custom logic
This custom track type is fairly silly, but it shows us that our "track" can really be any React component that we want it to, and that we can control some logical state of the track by using mobx-state-tree
Putting it all together
Here is a complete plugin that creates it's ReactComponent, configSchema, stateModel, and Plugin class in a single file. You are of course welcome to split things up into different files in your own plugins :)
src/index.js
FAQ
General
What technologies does JBrowse 2 use
- React
- mobx-state-tree
- web-workers
- Typescript
- Electron (for desktop specifically)
What is special about JBrowse 2
One thing that makes JBrowse 2 special is that we can create new view types via our plugin system, e.g. circular, dotplot, etc. Anything you want can be added as a view, and can be shown alongside our other views
This makes JBrowse 2 more than just a genome browser-- it is really a platform that can be built on.
What are new features in jbrowse 2
- Uses webworkers for data parsing and rendering tracks
- Use ctrl+scroll to zoom in and out quickly
- Status updates while track is loading (e.g. Downloading BAM index...)
- Hi-C visualization from .hic format files
- Can display multiple chromosomes or discontinuous regions on a single linear genome view
- Can connect to UCSC trackhubs
- Alignments track has both coverage and pileup display integrated in a single track
- Read pileups can be sorted by various attributes
- Has ability to show soft clipped bases on reads
- Interactively edit the configuration using the GUI
- Circular, dotplot, stacked synteny views
- SV inspector, that gives spreadsheet and circos overview of data in a single view
- Linear genome view can be reverse complemented
Can the linear genome view be reverse complemented
Yes! See here
Setup
How can I start the JBrowse 2 app as a developer
We recommend that you have the following
- Node v10+
- Git
- Yarn
Then you can follow steps from our README
It basically boils down to git cloning our repo, and running yarn start which
creates a development server on port 3000
You can use PORT=8080 yarn start to manually specify a different port
Note that this is a development server that gets started up. To install jbrowse 2 in production on your webserver, see below
Do you have any tips for learning React and mobx-state-tree
Here is a short guide to React and mobx-state-tree that could help get you oriented
https://gist.github.com/cmdcolin/94d1cbc285e6319cc3af4b9a8556f03f
How can I setup JBrowse 2 in production
We recommend following the steps in the quickstart web guide
How can I setup JBrowse 2 without the CLI tools
The jbrowse CLI tools are basically a convenience, and are not strictly required
Simple tasks can be done without it
For example, for jbrowse create, you can visit the blog and download the latest jbrowse-web release tag, and unzip it into your web directory
For other things, like add-assembly and add-track, you can manually edit the config.json, reviewing the config docs and sample configs will be valuable
Understanding the config basics will come in handy also because you can manually edit in advanced configs after your tracks are loaded however be careful because corrupt configs can produce hard to understand errors, because our config system is strongly typed
Feel free to message the team if you encounter these
How can I setup JBrowse 2 with the CLI tools
See the quickstart guide
How do I load a track into JBrowse 2
If you have followed the above steps and installed jbrowse 2 on your webserver and loaded the assembly, and have the CLI tools installed
This will setup a bigwig track on the hg19 assembly in your config.json. Make sure to run the command inside your current jbrowse2 folder e.g. /var/www/html/jbrowse2 or wherever you are currently setting up a config.json (you can have multiple configs)
Note that you can also use remote URLs
The add-track command will do as much as possible to infer from the file extension how to configure this track, and automatically infer the index to be myfile.bam.bai
Curiosities
Why do all the tracks need an assembly specified
We require that all tracks have a specific genome assembly specified in their config. This is because jbrowse 2 is a multi-genome-assembly browser (and can compare genomes given the data). This may be different to using say jbrowse 1 where it knows which genome assembly you are working with at any given time
How are the menus structured in the app
In JBrowse 1, the app level menu operated on the single linear genome view, but with JBrowse 2, the top level menu only performs global operations and the linear genome view has it's own hamburger menu. Note that each track also has it's own track level menu.
- This means it's only possible to have one version of a particular plugin loaded on any given webpage, even if multiple products are loaded and using it on the same page.↩