Difference between revisions of "JBrowse Tutorial 2013"

From GMOD
Jump to: navigation, search
m (Features)
Line 135: Line 135:
 
             "CDS" : "transcript-CDS",
 
             "CDS" : "transcript-CDS",
 
             "UTR" : "transcript-UTR"
 
             "UTR" : "transcript-UTR"
       },
+
       }
      "arrowheadClass" : "arrowhead"
+
 
     },
 
     },
 
   ...
 
   ...
Line 183: Line 182:
 
  $ <span class="enter">bin/flatfile-to-json.pl --trackLabel repeatmasker \
 
  $ <span class="enter">bin/flatfile-to-json.pl --trackLabel repeatmasker \
 
     --type match:repeatmasker --getType --getSubfeatures --key RepeatMasker \
 
     --type match:repeatmasker --getType --getSubfeatures --key RepeatMasker \
     --arrowheadClass arrowhead --className generic_parent \
+
     --className generic_parent \
 
     --subfeatureClasses '{"match_part" : "feature"}' --gff ../repeats.gff</span>
 
     --subfeatureClasses '{"match_part" : "feature"}' --gff ../repeats.gff</span>
  
Line 190: Line 189:
 
  $ <span class="enter">bin/flatfile-to-json.pl --trackLabel repeatrunner \
 
  $ <span class="enter">bin/flatfile-to-json.pl --trackLabel repeatrunner \
 
     --type protein_match:repeatrunner --getType --getSubfeatures \
 
     --type protein_match:repeatrunner --getType --getSubfeatures \
     --key RepeatRunner --arrowheadClass arrowhead --className generic_parent \
+
     --key RepeatRunner --className generic_parent \
 
     --subfeatureClasses '{"match_part" : "feature"}' --gff ../repeats.gff</span>
 
     --subfeatureClasses '{"match_part" : "feature"}' --gff ../repeats.gff</span>
  

Revision as of 22:32, 19 July 2013

This JBrowse tutorial was presented by Robert Buels at the 2013 GMOD Summer School in July 2013.

Prerequisites

These have already been set up on the VM image.

Optional, for generating images from Wiggle files:

  • libpng12-0
  • libpng12-dev
  • a C++ compiler

Optional, for BAM files (setup.sh tries to install these for you in the JBrowse directory):

  • samtools, and its dependency libncurses5-dev
  • perl module: Bio::DB::SAM

Other prerequisites are installed by JBrowse automatically.

This is how they were installed: (don't do this yourself)

$ sudo apt-get install libpng12-0 libpng12-dev build-essential libncurses5-dev

Make sure you can copy/paste from the wiki.

It's also very useful to know how to tab-complete in the shell.

JBrowse Introduction

How and why JBrowse is different from most other web-based genome browsers, including GBrowse.

More detail: paper

JBrowse presentation

Setting up JBrowse

Getting JBrowse

  • prepare a directory for JBrowse
$ cd /var/www
$ sudo mkdir jbrowse_demo
$ sudo chown ubuntu.ubuntu jbrowse_demo
$ cd jbrowse_demo
  • download the demo bundle from jbrowse.org and unzip it
$ wget http://jbrowse.org/info/GMOD_Summer_School_2013_JBrowse.zip
$ unzip GMOD_Summer_School_2013_JBrowse.zip
$ unzip JBrowse-1.9.8.zip
$ mv JBrowse-1.9.8 jbrowse
  • run setup.sh to configure this copy of JBrowse
$ cd jbrowse
$ ./setup.sh

Starting Point

Visit in web browser: http://ec2-##-##-##-##.compute-1.amazonaws.com/jbrowse_demo/jbrowse/

You should see a "Congratulations" page.

Basic Steps

Setting up a JBrowse instance with feature data goes in three basic steps:

  1. Specify reference sequences
  2. Format data for tracks
  3. Configure direct-access tracks
  4. Index feature names


Features from a directory of files

Here, we'll use the Bio::DB::SeqFeature::Store adaptor in "memory" mode to read a directory of files. There are adaptors available for use with many other databases, such as Chado and Bio::DB::GFF.

Config file: pythium-1.conf

{
  "description": "GMOD Summer School 2013 P. ultima Example",
  "db_adaptor": "Bio::DB::SeqFeature::Store",
  "db_args" : {
      "-adaptor" : "memory",
      "-dir" : ".."
   },
...

Specify reference sequences

The first script to run is bin/prepare-refseqs.pl; that script is the way you tell JBrowse about what your reference sequences are. Running bin/prepare-refseqs.pl also sets up the "DNA" track.

Run this from within the jbrowse directory (you could run it elsewhere, but you'd have to explicitly specify the location of the data directory on the command line).

$ cd /var/www/jbrowse_demo/jbrowse
$ bin/prepare-refseqs.pl --gff ../scf1117875582023.gff

Refresh it in your web browser, you should new see the JBrowse UI and a sequence track, which will show you the DNA base pairs if you zoom in far enough.

Load Feature Data

Next, we'll use biodb-to-json.pl to get feature data out of the database and turn it into JSON data that the web browser can use.

In this case, we have specified all of our track configurations in pythium-1.conf.

...
 
  "TRACK DEFAULTS": {
    "class": "feature"
  },
 
 "tracks": [
    {
      "track": "Genes",
      "key": "Genes",
      "feature": ["mRNA"],
      "autocomplete": "all",
      "class": "transcript",
      "subfeature_classes" : {
            "CDS" : "transcript-CDS",
            "UTR" : "transcript-UTR"
      }
    },
   ...
]

track specifies the track identifier (a unique name for the track, for the software to use). This should be just letters and numbers and - and _ characters; using other characters makes things less convenient.

key specifies a human-friendly name for the track, which can use any characters you want.

feature gives a list of feature types to include in the track.

autocomplete including this setting makes the features in the track searchable.

urltemplate specifies a URL pattern that you can use to link genomic features to specific web pages.

class specifies the CSS class that describes how the feature should look.

For this particular track, I've specified the transcript feature class.

Run the bin/biodb-to-json.pl script with this config file to format this track, and the others in the file:

$ bin/biodb-to-json.pl --conf ../pythium-1.conf

Refresh JBrowse in your web browser. You should now see a bunch of annotation tracks.

Index feature names

When you generate JSON for a track, if you specify "autocomplete" then a listing of all of the feature names from that track (along with feature locations) will also be generated and used to provide feature searching and autocompletion.

The bin/generate-names.pl script collects those lists of names from all the tracks and combines them into one big tree that the client uses to search.

$ bin/generate-names.pl -v

Visit in web browser, try typing a feature name, such as maker-scf1117875582023-snap-gene-0.26-mRNA-1. Notice that JBrowse tries to auto-complete what you type.

Features from flat files

We're going to add a couple more tracks that come from repeats.gff, a different flat file.

GFF3 or BED

To get feature data from flat files into JBrowse, use flatfile-to-json.pl.

  • We'll add a RepeatMasker track:
$ bin/flatfile-to-json.pl --trackLabel repeatmasker \
    --type match:repeatmasker --getType --getSubfeatures --key RepeatMasker \
    --className generic_parent \
    --subfeatureClasses '{"match_part" : "feature"}' --gff ../repeats.gff
  • And then a RepeatRunner track:
$ bin/flatfile-to-json.pl --trackLabel repeatrunner \
    --type protein_match:repeatrunner --getType --getSubfeatures \
    --key RepeatRunner --className generic_parent \
    --subfeatureClasses '{"match_part" : "feature"}' --gff ../repeats.gff

Visit in web browser; you should see the two new RepeatMasker and RepeatRunner tracks.

BAM data

Now let's add some simulated short-read alignments from a BAM file. To import data from a BAM source:

$  bin/bam-to-json.pl \
    --bam ../simulated-sorted.bam \
    --tracklabel BAM_data --key "BAM Data"

Browse can display quantitative data directly from a BigWig file on your web server. Simply place the BigWig file in a directory accessible to your web server, and add a snippet of configuration to JBrowse to add the track, similar to:

     {
        "label" : "bam_alignments",
        "key" : "BAM alignments",
        "storeClass" : "JBrowse/Store/SeqFeature/BAM",
        "urlTemplate" : "../../simulated-sorted.bam",
        "type" : "Alignments2"
      }

This can be added by either editing the data/trackList.json file with a text editor, or by running something like this at the command line to inject the track configuration:

$ echo '{
       "label" : "bam_alignments",
       "key" : "BAM alignments",
       "storeClass" : "JBrowse/Store/SeqFeature/BAM",
       "urlTemplate" : "../../simulated-sorted.bam",
       "type" : "Alignments2"
     }' | bin/add-track-json.pl data/trackList.json

Quantitative data

BigWig

JBrowse can display quantitative data directly from a BigWig file on your web server. Simply place the BigWig file in a directory accessible to your web server, and add a snippet of configuration to JBrowse to add the track, similar to:

     {
        "label" : "bam_coverage",
        "key" : "BAM coverage",
        "storeClass" : "BigWig",
        "urlTemplate" : "../../simulated-sorted.bam.coverage.bw",
        "type" : "Wiggle",
        "variance_band" : true
      }

This can be added by either editing the data/trackList.json file with a text editor, or by running something like this at the command line to inject the track configuration:

$ echo ' {
       "label" : "bam_coverage",
       "key" : "BAM coverage",
       "storeClass" : "BigWig",
       "urlTemplate" : "../../simulated-sorted.bam.coverage.bw",
       "type" : "Wiggle",
       "variance_band" : true
     } ' | bin/add-track-json.pl data/trackList.json


Faceted Track Selection

JBrowse has a very powerful faceted track selector that can be used to search for tracks using metadata associated with them.

The track metadata is kept in a CSV-format file, with any number of columns, and with a "label" column whose contents must correspond to the track labels in the JBrowse configuration.

The demo bundle contains an example trackMetadata.csv file, which can be copied into the data directory for use with this configuration.

$ cp trackMetadata.csv jbrowse/data

Then a simple faceted track selection configuration might look like:

   trackSelector: {
       type: 'Faceted',
   },
   trackMetadata: {
       sources: [
          { type: 'csv', url: 'data/trackMetadata.csv' }
       ]
   }

The jbrowse_conf.json file in the jbrowse directory already conveniently contains this stanza, commented out. Uncomment it, refresh your browser, and you should now see the faceted track selector activated.

Upgrading an Existing JBrowse

If the old JBrowse is 1.3.0 or later, simply move the data directory from the old JBrowse directory into the new JBrowse directory.

Common Problems

  • JSON syntax errors


Future JBrowse Plans

See the accompanying slides (PDF)


Other links