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
• Perl Prerequisites
• 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.

Change into a directory that's served by your web server (e.g. /var/www/), and extract JBrowse there. For example:

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 the WIG support failed to install,

Skip this step if setup.sh was successful at installing the Perl prerequisites, it has already done this for you.

The server-side scripts for formatting data have some Perl module prerequisites from the CPAN. setup.sh tries to install these Perl dependencies for you, but in case you need to run the installation independently, they can be installed by the command:

Reference Sequences

Tell JBrowse about your reference sequences with 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.

Features

There are two options for loading your feature data into JBrowse.

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 (documented here).

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

bin/flatfile-to-json.pl

On the other hand, if you mainly deal with flat files like GFF or BED, it may be more convenient to use JBrowse's flatfile-to-json.pl. bin/flatfile-to-json.pl doesn't use a configuration file; instead, per-track settings are given as command-line arguments. Run bin/flatfile-to-json.pl --help to see a description of the available settings. Most of them correspond to track settings in the config file used by biodb-to-json.pl, so see the track settings section in the config file documentation for more details.

Next-gen reads (BAM format)

If you have data in BAM format, you can import it into a JBrowse instance using bam-to-json.pl. For example:

bin/bam-to-json.pl                                              \
   --bam docs/tutorial/data_files/volvox-sorted.bam             \
   --tracklabel bam_simulated                                   \
   --key "Simulated next-gen reads"                             \
   --cssClass basic                                             \
   --clientConfig                                               \
        '{ "featureCss": "background-color: #66F; height: 8px",
           "histCss": "background-color: #88F"
        }'

Index Names

To let users find features by typing feature names or IDs in the search box, do two things:

1. specify autocomplete for the tracks whose features you want to be searchable (see the track settings section in the config file documentation for details about the autocomplete setting). When you do this, a file with a list of names and locations will be generated for each track that has the autocomplete setting.
2. run bin/generate-names.pl to collect those per-track files together into the structure that JBrowse uses to search

Note: You need to rerun bin/generate-names.pl to re-index feature names time you add new annotations to JBrowse.

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

Quantitative tracks (Wiggle support)

If you want to create quantitative ("wiggle") tracks for JBrowse, you need to compiled a C program called wig2png, included with JBrowse. If setup.sh reported being successful at installing wiggle format support, this has already been done for you. Otherwise, if setup.sh had trouble, read on to see how to manually build wig2png.

Manually building wig2png

Skip this step if setup.sh reported being successful at installing Wiggle support; this has already been done for you!

Prerequisites

libpng must be installed, along with corresponding development header files (see "System-specific tips for building" below).

Compile the wiggle-processing program by running configure and then make in the wig2png/ subdirectory of the JBrowse root directory.

Formatting Wiggle Data

Once wig2png has been built, use the wig-to-json.pl script to load wiggle files:

Sometimes things just don't go well. It seems like nothing's 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.