# 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

## Download and Uncompress JBrowse

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

Once you finish running that, you should try to read this tutorial (which is included in the JBrowse zip file) on your own web server by navigating to something like http://your.machine.address/jbrowse/JBrowse-1.8.0/docs/tutorial/index.html.

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.

## Run `setup.sh`

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

./setup.sh
which tries to automatically install the Perl prerequisites, format the Volvox example data, and install JBrowse legacy WIG and old-style BAM-to-JSON conversion support (which require additional dependencies and compilation that can be a bit tricky, and which most users don't need anyway).

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

Note: BAM files are required to be sorted and indexed (i.e. have a corresponding .bai file).

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.

To use them, set type = Alignments2 or type = SNPCoverage in the track configuration.

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

bin/generate-names.pl -v

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)

JBrowse can display alignments directly from BigWig 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:

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

To use them, set type = JBrowse/View/Track/Wiggle/XYPlot or type = JBrowse/View/Track/Wiggle/Density in the track configuration.

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

## Troubleshooting

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.