JBrowse Quick-Start Tutorial

This short guide should hopefully be enough to get you started using JBrowse. If you run into trouble, please visit the GMOD wiki for extended documentation and troubleshooting information, or join the gmod-ajax mailing list and ask a question about it.

Contents

• Download and Uncompress JBrowse
• Run setup.sh
• Reference Sequences
• Features
• Next-gen Reads (BAM support)
• Index Names
• Quantitative Tracks (Wiggle support)
• Troubleshooting

Skip this step if you are reading this page on your own server, since you have already downloaded and uncompressed JBrowse.

Get JBrowse from jbrowse.org.

You will want to put JBrowse under a directory that's served by your web server (e.g. /var/www/ on Debian or Ubuntu systems, /var/www/html on Red Hat, Fedora, or SUSE).

For example, you could make a web-accessible directory to hold your work called /var/www/jbrowse, give your user access to it, and then fetch and uncompress a copy of JBrowse (about 3MB) there:

# make a directory that this user can write to
sudo mkdir /var/www/jbrowse;
sudo chown `whoami` /var/www/jbrowse;
# cd into it
cd /var/www/jbrowse;

# fetch a JBrowse release zip file
curl -O http://jbrowse.org/releases/JBrowse-1.8.0.zip

# unzip it and cd into it
unzip JBrowse-1.8.0.zip
cd JBrowse-1.8.0

Also, please note that JBrowse generates files with links that are relative to the main JBrowse-1.x.x directory (where index.html is located), so you should run all scripts from this directory.

To get started with a working JBrowse running on example Volvox data, on machines running Linux or Mac OS X one can simply run:

If it says the Volvox example data was successfully formatted (even if the WIG or BAM support setup failed) you can navigate to the example Volvox JBrowse. If you see a genome browser with Volvox data in it, congratulations! You have a working JBrowse installation. Read on to Reference Sequences for how to format your own data for use with JBrowse.

If one or more of the setup steps failed, try reading through the setup.log file for details of what went wrong, and consulting the JBrowse Troubleshooting page on the GMOD wiki for what to do. It is always safe to run ./setup.sh again after correcting a problem.

Now, if you can see the Volvox test data, your JBrowse is working.

Reference Sequences

Before loading annotation data, format your reference sequences for JBrowse using bin/prepare-refseqs.pl.

For FASTA format sequence files

bin/prepare-refseqs.pl --fasta docs/tutorial/data_files/volvox.fa

For sequences already stored in a Bio::DB::* database

bin/prepare-refseqs.pl --conf docs/tutorial/conf_files/volvox.json

See the configuration file reference for more details on how these configuration files work.

General-Purpose Features

JBrowse can import feature data from flat files, or from databases that have Bio::DB::* Perl interfaces.

bin/flatfile-to-json.pl

If you have flat files like GFF3 or BED, it is usually best to use bin/flatfile-to-json.pl to import them. bin/flatfile-to-json.pl accepts many different command-line settings that can be used to customize the appearance of the new track. Run bin/flatfile-to-json.pl --help to see a description of the available settings.

bin/flatfile-to-json.pl --gff path/to/my.gff3 --trackType CanvasFeatures --trackLabel mygff

bin/biodb-to-json.pl

If you have a genomic annotation database such as Chado, Bio::DB::SeqFeature::Store, or Bio::DB::GFF, then you can use JBrowse's biodb-to-json.pl. You use bin/biodb-to-json.pl with a configuration file (the format of which is documented here).

bin/biodb-to-json.pl --conf docs/tutorial/conf_files/volvox.json

Next-gen reads (BAM)

JBrowse can display alignments directly from BAM files, with no pre-processing necessary. Simply add a stanza with the relative URL of the file to your data/tracks.conf file, of the form:

# make a section for the new track called tracks.(unique name)
[ tracks.my-bam-track ]

# settings for what data is shown in the track
storeClass     = JBrowse/Store/SeqFeature/BAM
urlTemplate    = ../../raw/volvox/volvox-sorted.bam
baiUrlTemplate = ../../raw/volvox/volvox-sorted.bam.bai

# settings for how the track looks
category = NGS   #< category for this track
type = JBrowse/View/Track/Alignments2
key  = BAM alignments from sample XYZ
        

JBrowse has two main track types that are designed especially for use with BAM data:

Alignments2

Shows individual alignments from the BAM file, as well as insertions, deletions, skipped regions, and SNPs encoded in the BAM's MD or CIGAR fields.

SNPCoverage

Shows a coverage histogram plot, with colored bars showing the locations of base-level mismatches and possible SNPs in the reads.

Index Names

After loading feature data, to let users find features by typing feature names or IDs in the autocompleting search box, a special index of feature names must be generated using bin/generate-names.pl.

Note: You need to re-run bin/generate-names.pl to add new feature names to the index every time you add new annotations to JBrowse using any of the *-to-json.pl scripts.

And that's all, for basic usage. Visit the main page to view the results.

Quantitative tracks (BigWig and Wiggle)

[ tracks.my-bigwig-track ]
storeClass  = JBrowse/Store/SeqFeature/BigWig
urlTemplate = ../../my-bigwig-file.bw

category = Quantitative  # category for this track in the track selector
type     = JBrowse/View/Track/Wiggle/XYPlot
key      = Coverage plot of NGS alignments from XYZ

        

JBrowse has two track types that are designed especially for use with quantitative data:

JBrowse/View/Track/Wiggle/XYPlot

Shows quantitative data as a bar graph. See the JBrowse wiki for configuration options.

JBrowse/View/Track/Wiggle/Density

Shows quantitative data as a "heatmap" plot, which by default draws regions with positive scores as progressively more intense blue, and negative scores as progressively more intense red. See the JBrowse wiki for configuration options, including how to change the color-change point (bicolor_pivot), and the colors.

Wiggle files

For most users, the best way to display a Wiggle (.wig) file is to convert it to BigWig using the tool of their choice, then use the JBrowse BigWig functionality described above to configure JBrowse to display it.

Older versions of JBrowse used a script called wig-to-json.pl to convert Wiggle files into PNG images for display by JBrowse. This older method is still supported for backward-compatibility, and is described on the JBrowse wiki.

Sometimes things just don't go well. It seems like nothing is ever as easy as it should be. Here are several resources you can use if it turns out that this guide is not enough to get JBrowse working for you.

JBrowse on the GMOD wiki

Contains extended documentation on many aspects JBrowse, including troubleshooting tips.

gmod-ajax@lists.sourceforge.net mailing list

Primary mailing list for JBrowse questions and discussion. If asking questions about a problem running ./setup.sh, please attach your setup.log file.