Skip to main content

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

After opening the menu item for 'Open new track' a drawer widget for the 'Add track form' will appear
Figure: After opening the menu item for 'Open new track' a drawer widget for the 'Add track form' will appear

Note: There is also a circular "+" button inside the track selector menu that can also be used to access the "Add track" form.

The orange plus icon in the bottom right of a tracklist can also be used to launch the 'Add track form'
Figure: The orange plus icon in the bottom right of a tracklist can also be used to launch 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-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 share dialog, which gives you a short URL to share your session with other users. It is important to use these URLs generated here rather than simply copying and pasting your URL to other users
Figure: The session share dialog, which gives you a short URL to share your session with other users. It is important to use these URLs generated here rather than simply copying and pasting your URL to other users

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

Screenshot showing how to copy a track. In order to edit detailed configuration of a track, we require that you first make a copy of it, which can be done via the track menu
Figure: Screenshot showing how to copy a track. In order to edit detailed configuration of a track, we require that you first make a copy of it, which can be done via the track menu

After you have copied the track, you can edit the track settings

After copying a track, which puts it in your 'session tracks', you can then edit the track settings, and you have full control over your session tracks
Figure: After copying a track, which puts it in your 'session tracks', you can then edit the track settings, and you have full control over your session tracks

Your new track is a "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
Figure: 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
Figure: 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
Figure: Before and after horizontally flipping

Sequence track#

The sequence track shows the reference sequence and a three-frame translation. If the view is horizontally flipped, the sequence is "reverse complemented" so the bottom three translation frames go to the top, and the top frames go to the bottom.

The sequence track, with a positive strand gene for context, shows the start codon on the first exon in the top-three rows of the translation frame. The bottom panel shows the same view but with the view horizontally flipped, and the gene is now shown reversed and the start codon is in the bottom translation frames.
Figure: The sequence track, with a positive strand gene for context, shows the start codon on the first exon in the top-three rows of the translation frame. The bottom panel shows the same view but with the view horizontally flipped, and the gene is now shown reversed and the start codon is in the bottom translation frames.

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
Figure: 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.
Figure: 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

  1. Open the hamburger menu in the top left of the linear genome view
  2. 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
Figure: 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

  1. Open the track menu for the specific track using the vertical '...' in the track label
  2. 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)
Figure: 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)

Sort, color and filter by tag#

We can now also do things like

  • Sort by tag
  • Filter by tag
  • Color by tag

With these features, we can create very expressive views of alignments tracks

Step-by-step guide showing how to sort and color by haplotype with the HP tag
Figure: Step-by-step guide showing how to sort and color by haplotype with the HP tag

Color by orientation#

JBrowse uses the same color scheme as IGV for coloring by pair orientation. These pair orientations can be used to reveal complex patterns of structural variation

See https://software.broadinstitute.org/software/igv/interpreting_pair_orientations for a good guide on interpreting these pair orientations

This shows an inverted duplication, the tandem duplication can produce green arrows which have reads pointing in opposite directions e.g. <-- and -->, while blue arrows which can indicate an inversion point in the same direction e.g. --> and -->
Figure: This shows an inverted duplication, the tandem duplication can produce green arrows which have reads pointing in opposite directions e.g. <-- and -->, while blue arrows which can indicate an inversion point in the same direction e.g. --> and -->

BigWig tracks#

Visualizing genome signals, whether it is read depth-of-coverage or other signal, can often be done by using BigWig files

A simple wiggle track with the XY plot renderer
Figure: A simple wiggle track with the XY plot renderer

Viewing whole-genome coverage for profiling CNV#

The latest jbrowse also allows refining the resolution of BigWig tracks, and viewing whole genome coverage. This allows us to get detailed global views of CNV for example from whole-genome coverage profiling

Here is a short picture guide to setup a whole-genome view of a BigWig for CNV coverage visualization

  1. Open your BigWig track
  2. Go to the view menu and select "Show all assembly regions"
  3. Adjust the "Autoscale type" to your liking, the new options for "Local +/- 3sd" allows the autoscaling to avoid outliers
  4. Go to the track menu and select "Turn off histogram fill", which then shows only a dot for each point on the graph
  5. Go to the track menu and select "Resolution->Finer resolution" a couple times until resolution looks nice

Also note: all tracks have a drag handle on the bottom of it which you can drag down to make the track taller

A step-by-step guide to view a whole-genome CNV profile of coverage from a BigWig file
Figure: A step-by-step guide to view a whole-genome CNV profile of coverage from a BigWig file

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
Figure: 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

Screenshot showing the variant feature sidebar with a filtered by genotype (with alternative allele '1'). Users can also filter by sample name or other attributes
Figure: Screenshot showing the variant feature sidebar with a filtered by genotype (with alternative allele '1'). Users can also filter by sample name or other attributes

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
Figure: 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
Figure: 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
Figure: 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

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: 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
Example screenshot showing the linear synteny view for grape vs peach
Figure: Example screenshot showing the linear synteny view for grape vs peach

See the linear synteny configuration for more details on manually configuring the synteny view

Opening a synteny view from a dotplot view#

We have designed JBrowse 2 to be able to open up a synteny view from a dotplot view. This is enabled by "display modes" so that the same track can be displayed in different contexts.

Here is a short demo that shows opening a synteny view from a dotplot view selection

Screenshow showing the 'click and drag' selection over the dotplot view prompts you to open up a linear synteny view from the selected region
Figure: Screenshow showing the 'click and drag' selection over the dotplot view prompts you to open up a linear synteny view from the selected region

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
Figure: 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
Figure: 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 of a Hi-C track
Figure: Screenshot of 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
Figure: 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 opening a file locally or using a URL for files in the following formats:

  • VCF or VCF.gz (plain text VCF, or (b)gzipped VCF)
  • BEDPE
  • STAR-fusion result file
The import form for getting started with the SV inspector
Figure: The import form for getting started with the SV inspector

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/

## Example VCF for use in the SV inspector
https://jbrowse.org/genomes/hg19/skbr3/reads_lr_skbr3.fa_ngmlr-0.2.3_mapped.bam.sniffles1kb_auto_l8_s5_noalt.new.vcf

Copy this URL and paste it into the import form and select hg19

The SV inspector with the import form and URL pasted
Figure: The SV inspector with the import form and URL pasted

SV inspector results#

After loading the user's requested file, you will have a tabular view with each row representing a row of the file you opened, along with a whole-genome overview of the SVs on the right

The SV inspector with loaded results
Figure: The SV inspector with loaded results

Now here is where things can become interesting

We can search and filter the table, with filtering and searching being reflected in the circular view as well.

The SV inspector with filter applied
Figure: The SV inspector with filter applied

Launching breakpoint split view#

By clicking on the features in the circular view, or clicking on the triangle drop-down on the leftmost column of the table, 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.

Screenshot of the 'breakpoint split view' which examines the breakpoints of a structural variant, e.g. an interchromosomal translocation, and connects supporting reads (black splines) and the variant call itself (green thicker line, with feet indicating directionality)
Figure: Screenshot of the 'breakpoint split view' which examines the breakpoints of a structural variant, e.g. an interchromosomal translocation, and connects supporting reads (black splines) and the variant call itself (green thicker line, with feet indicating directionality)
Edit this page