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
You can also use the search box to search by gene name (if it is configured)

In order to enable name searching, you or the admin on the instance will need to create a "text index". See the quickstart guide for more info.
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

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

In the "Add track" form, you can provide a URL to a file to load, or you can also open files from your local machine. In some cases, you need to provide an index (bigwig files for example have no index, but BAM/CRAM or tabix filetypes like VCF/GFF/BED tabix do). In some cases we can automatically infer the index e.g. if you provide a URL for a BAM and the index filename is bamfilename +'.bai' but you may need to manually supply it in some cases (index inference can't be done with files from your local machine)
The following file formats are supported
- Tabixed VCF
- Tabixed BED
- Tabixed GFF
- BAM
- CRAM
- BigWig
- BigBed
- .hic file (Juicebox)
- PAF
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
On JBrowse Web, 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.
Note: Share sessions is not available on JBrowse Desktop.
Also note: you can't copy the literal URL in your address bar and send it to other users, you must use the "Share" button to do that, but you can copy and paste the URL in your URL bar 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!
Track menu
Users can access track-specific functions by using the track menu, which is accessible from the track selecter itself ("..." icon) or on the track label (vertical "..."). Some functions are only available when the track is open e.g. from the track label, but more basic options like "About track" are available from the track menu on the track selector.

About track dialog
Using the track menu as described above, you can access the "About track" dialog

Editing track configs
As a non-admin user, in order to edit a track config, you have to make a copy of the track. This will copy it to your "session tracks", which you can edit freely

Rubberband selection
The scale bars accept a click-and-drag action to select a region. Rubberband selection can be performed on both the main (lower) and overview (upper) 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.

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

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.

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

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

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"

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'

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. For example, in the below step-by-step guide, it shows how to color and sort the reads by the HP tag.

Color by modifications/methylation
If you have data that marks DNA/RNA modifications using the MM tag in BAM/CRAM format, then the alignments track can use these to color these. It uses two modes
- Modifications mode - draws the modifications as they are
- Methylation mode - draws both unmodified and modifified CpGs (unmodified positions are not indicated by the MM tag and this mode considers the sequence context)



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

Sashimi-style arcs
The alignments track will draw sashimi-track style arcs across spliced alignments (indicated by N in the CIGAR string). If the reads additionally are tagged with XS tags, it will try to draw the arcs using the strand indicated by the alignment

Note that you can disable these by clicking on the track menu (vertical ... next to track label, then hovering over SNPCoverage options, and unchecking "Draw arcs")
Insertion and clipping indicators
The alignments track will also draw a upside-down histogram of insertion and soft/hard clipped read counts at all positions, and mark significant positions (covering 30% of the reads) with a colored triangle.

Also, insertions that are larger than 10bp are marked with a special larger purple rectangle, seen in the below screenshot. Generally, long reads span larger insertions better, so this feature is more prominant with large reads.

Note that you can disable these by clicking on the track menu (vertical ... next to track label, then hovering over SNPCoverage options, and unchecking "Draw insertion/clipping indicators" and "Draw insertion/clipping counts")
Quantitative tracks
Visualizing genome signals, whether it is read depth-of-coverage or other signal, can often be done by using BigWig or other quantitative feature files

Example use case: 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:
- Open your BigWig track
- Go to the view menu and select "Show all assembly regions"
- Adjust the "Autoscale type" to your liking, the new options for "Local +/- 3sd" allows the autoscaling to avoid outliers
- Go to the track menu and select "Turn off histogram fill", which then shows only a dot for each point on the graph
- 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.

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

Comparative 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 against 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



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


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

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


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

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

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

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

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

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.

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.

Getting the protein sequence for features
If you have a track with gene or transcript level features, then the feature detail sidebar will automatically stitch together the sequence for that feature. The options include:
- CDS - the coding sequences, spliced together
- Protein - performs protein translation on the CDS, currently assuming the default codon translation table
- cDNA - the CDS plus UTR, or just all exons if a non-coding gene
- Gene w/ introns - the entire gene region sequence with the introns included
- Gene w/ 10bp of introns - the spliced gene sequence with 10bp around the splice sites shown
- Gene w/ 500 up+down stream - the entire gene region with 500bp upstream and downstream (shown in light red)
- Gene w/ 500 up+down stream + 10bp of introns - the spliced gene sequence with 10bp around the splice sites shown and the up/down stream shown
Some of the params such as 500bp and 10bp are arbitrarily chosen, if you are interested in adjusting these parameters let us know

Using the plugin store
Users can add plugins to their session using the in-app plugin store. The plugin will be added to your "session" which can be shared with the share button (or if you are an admin running the admin-server, then it will be added to the config file).
This can add extra functions or tracks or many other interesting features. For example, if you add the CIVIC plugin, it will automatically add a track that contains the CIVIC cancer gene annotations to hg19.
Note that not all plugins are directly useful from being added (sometimes it needs extra work on the part of the plugin developer to make them useful in the GUI, some plugins require hand editing of configuration files).

Using the bookmark widget
JBrowse Web and JBrowse Desktop come with a "bookmark widget" that you can use to store lists of interesting regions that would would like to easily revisit.

The bookmark stores a list of single regions (chromosome, start, and end coordinate), and clicking on the regions in the bookmark widget will launch a linear genome view at that region.
You can also import a list of regions from a BED file

Note also that you can add "notes" for your list of regions, allowing a simple way to "annotate" your datasets

Finally, you can export your list of regions to a BED file or TSV