Difference between revisions of "JBrowse"

From GMOD
Jump to: navigation, search
m
m (1 revision)
(88 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{SessionHead}}
+
<!-- to alter this page, please edit the raw data, which is stored at http://gmod.org/wiki/JBrowse/tool_data -->
{| class="tutorialheader"
+
| {{TutorialTitleLine|[[gmod:JBrowse|JBrowse]]}}<br />
+
[[2011 GMOD Spring Training]]<br />
+
8-12 March 2011<br />
+
[[User:MitchSkinner|Mitch Skinner]]
+
| align="right" | [[Image:GMODAmericas2011Logo.png|200px]]
+
|}
+
  
 +
{{ :JBrowse/tool_data | template = Template:ToolDisplay }}
  
__TOC__
+
[[Category:GMOD Components]]
 
+
[[Category:AJAX]]
== Prerequisites ==
+
[[Category:JBrowse]]
 
+
These have <b>already been set up</b> on the VM image.
+
 
+
Perl:
+
* [[gmod:BioPerl|BioPerl 1.6]]
+
* {{CPAN|JSON}}
+
* {{CPAN|JSON::XS}} (optional, for speed)
+
* {{CPAN|PerlIO::gzip}}
+
* {{CPAN|Heap::Simple}}
+
* {{CPAN|Heap::Simple::XS}}
+
* {{CPAN|Devel::Size}}
+
 
+
 
+
System packages:
+
* libpng12-0
+
* libpng12-dev
+
 
+
Optional, for BAM files:
+
* samtools, and its dependency libncurses5-dev
+
* perl module: {{CPAN|Bio::DB::SAM}}
+
 
+
<div class="dont">
+
And this is how they were installed: <b>(don't do this)</b>
+
<pre class="dont">
+
$ sudo apt-get install git-core libpng12-0 libpng12-dev libncurses5-dev
+
$ cd ~/Documents/Software
+
$ wget http://sourceforge.net/projects/samtools/files/samtools/0.1.7/samtools-0.1.7a.tar.bz2
+
$ tar xjf samtools-0.1.7a.tar.bz2
+
$ cd samtools-0.1.7a/
+
$ make
+
$ sudo cpan
+
cpan[1]> install Bio::DB::Das::Chado Bio::DB::Sam JSON JSON::XS PerlIO::gzip Heap::Simple Heap::Simple::XS Devel::Size
+
</pre>
+
</div>
+
 
+
Also: make sure you can Copy/paste from wiki.
+
 
+
Shell tricks:
+
* Tab completion
+
* History
+
* History search
+
<br><br><br>
+
 
+
== JBrowse Introduction ==
+
 
+
How and why [[JBrowse]] is different from most other web-based genome browsers, including [[GBrowse]].
+
 
+
More detail: [http://genome.cshlp.org/content/19/9/1630.full paper]
+
<br><br>
+
 
+
[[Media:JBrowse_GMOD_Meeting_2011.pdf]]
+
 
+
== JBrowse arch ==
+
[[Image:Jbrowse_arch.png|||600px]]
+
 
+
== Setting up JBrowse ==
+
 
+
=== Getting JBrowse ===
+
 
+
<div class="dont">
+
* Install git '''(This has already been done in the VMware image.)'''
+
 
+
<pre class="dont">$ sudo apt-get install git-core
+
</pre>
+
 
+
</div>
+
 
+
* prepare a directory for JBrowse
+
 
+
$ <span class="enter">cd /var/www</span>
+
$ <span class="enter">sudo mkdir jbrowse</span>
+
$ <span class="enter">sudo chown gmod.gmod jbrowse</span>
+
 
+
* download it from github
+
 
+
$ <span class="enter">git clone git://github.com/jbrowse/jbrowse.git jbrowse</span>
+
 
+
(or alternately)
+
 
+
$ <span class="enter">git clone https://github.com/jbrowse/jbrowse.git jbrowse</span>
+
 
+
=== Starting Point ===
+
 
+
Visit in web browser: http://localhost/jbrowse/
+
 
+
 
+
You should see just a blank white page.
+
 
+
=== Basic Steps ===
+
 
+
Setting up a JBrowse instance with feature data goes in three basic steps:
+
 
+
# Specify reference sequences
+
# Load feature data
+
# Collect feature names
+
 
+
<!--
+
=== If you didn't follow along in the chado session ===
+
 
+
We'll be using the chado database from the chado session; if you didn't follow along exactly, re-load the database like so:
+
 
+
<pre>
+
$ dropdb chado
+
$ createdb chado
+
$ bzip2 -cd ~/Documents/Software/schema/chado/complete_db.bz2 | psql chado
+
</pre>
+
-->
+
 
+
=== Data from a database ===
+
 
+
Here, we'll use the [[Chado]] adapter; other common database adapters are {{CPAN|Bio::DB::SeqFeature::Store}} and {{CPAN|Bio::DB::GFF}}.
+
 
+
Starting config file:
+
<tt>~/Documents/Data/jbrowse/first-config.json</tt>
+
<pre>
+
{
+
  "description": "Pythium",
+
  "db_adaptor": "Bio::DB::Das::Chado",
+
  "db_args": { "-dsn": "dbi:Pg:dbname=chado",
+
              "-user": "gmod",
+
              "-pass": ""},
+
 
+
...
+
</pre>
+
 
+
==== Specify reference sequences ====
+
 
+
The first script to run is <tt>bin/prepare-refseqs.pl</tt>; that script is the way you tell JBrowse about what your reference sequences are.  Running <tt>bin/prepare-refseqs.pl</tt> also sets up the "DNA" track.
+
 
+
Run this from within the <tt>/var/www/jbrowse</tt> directory (you could run it elsewhere, but you'd have to explicitly specify the location of the data directory on the command line).
+
 
+
$ <span class="enter">cd /var/www/jbrowse</span>
+
$ <span class="enter">bin/prepare-refseqs.pl --conf ~/Documents/Data/jbrowse/first-config.json \
+
    --refs scf1117875582023</span>
+
 
+
Visit in web browser: you should new see the JBrowse UI (and if you zoom all the way in, some sequence)
+
 
+
==== Load Feature Data ====
+
 
+
Next, we'll use <tt>biodb-to-json.pl</tt> to get feature data out of the database and turn it into [[gmod:Glossary#JSON|JSON]] data that the web browser can use.
+
 
+
Add a basic track definition; this will tell <tt>biodb-to-json.pl</tt> what features to put into the track, and how the track should look:
+
 
+
<javascript>...
+
 
+
  "TRACK DEFAULTS": {
+
    "class": "feature"
+
  },
+
 
+
  "tracks": [
+
    {
+
      "track": "gene",
+
      "key": "Gene",
+
      "feature": ["gene"],
+
      "autocomplete": "all",
+
      "class": "feature2",
+
      "urlTemplate": "http://www.google.com/search?q={name}"
+
    }
+
  ]
+
}</javascript>
+
 
+
<tt>track</tt> 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.
+
 
+
<tt>key</tt> specifies a human-friendly name for the track, which can use any characters you want.
+
 
+
<tt>feature</tt> gives a list of feature types to include in the track.
+
 
+
<tt>autocomplete</tt> including this setting makes the features in the track searchable.
+
 
+
<tt>urltemplate</tt> specifies a URL pattern that you can use to link genomic features to specific web pages.
+
 
+
<tt>class</tt> specifies the [[gmod:Glossary#CSS|CSS]] class that describes how the feature should look.  The classes are specified in the <tt>genome.css</tt> file:
+
$ <span class="enter">less genome.css</span>
+
 
+
For this particular track, I've specified the <tt>"feature2"</tt> class which looks like this in the CSS file:
+
 
+
<javascript>.plus-feature2,
+
.minus-feature2 {
+
    position:absolute;
+
    height: 15px;
+
    background-repeat: repeat-x;
+
    cursor: pointer;
+
    min-width: 1px;
+
    z-index: 10;
+
}
+
 
+
.plus-feature2 { background-image: url('img/plus-herringbone16.png'); }
+
 
+
.minus-feature2 { background-image: url('img/minus-herringbone16.png'); }</javascript>
+
 
+
Run the <tt>bin/biodb-to-json.pl</tt> script with this config file to set up this track:
+
 
+
$ <span class="enter">bin/biodb-to-json.pl --conf ~/Documents/Data/jbrowse/first-config.json</span>
+
 
+
(visit in web browser: you should see a new gene track)
+
 
+
==== More complex track ====
+
 
+
Now we'll add a second track; this one will have subfeatures.  This snippet is from:
+
<tt>~/Documents/Data/jbrowse/second-config.json</tt>
+
 
+
<javascript>...
+
 
+
    {
+
      "track": "match",
+
      "key": "Matches",
+
      "feature": ["match"],
+
      "autocomplete": "all",
+
      "subfeatures": true,
+
      "class": "generic_parent",
+
      "subfeature_classes": {
+
          "match_part": "match_part"
+
      },
+
      "clientConfig": {
+
          "subfeatureScale": 20
+
      }
+
    }
+
 
+
...</javascript>
+
 
+
$ <span class="enter">bin/biodb-to-json.pl --conf ~/Documents/Data/jbrowse/second-config.json</span>
+
 
+
(visit in web browser: you should see a new track, which has subfeatures if you're zoomed in far enough)
+
 
+
==== Collect feature names ====
+
 
+
When you generate JSON for a track, if you specify <tt>"autocomplete"</tt> then a listing of all of the names/IDs from that track (along with the locations of the corresponding features) will also be generated.
+
 
+
The <tt>bin/generate-names.pl</tt> script collects those lists of names from all the tracks and combines them into one big tree that the client uses to search.
+
 
+
$ <span class="enter">bin/generate-names.pl -v</span>
+
 
+
Visit in web browser, search for feature name: e.g.,
+
 
+
: '''maker-scf1117875582023-snap-gene-0.3'''
+
 
+
=== Data from flat files ===
+
 
+
We're going to recreate a JBrowse instance from a different data source: flat files.
+
 
+
First, wipe the slate clean by removing the <tt>data</tt> directory:
+
 
+
$ <span class="enter">rm -r data</span>
+
 
+
If you visit your JBrowse instance in a web browser, you'll see a blank screen again
+
 
+
==== Sequences ====
+
 
+
To import sequence data from a fasta file into a JBrowse instance, use <tt>prepare-refseqs.pl</tt> with the <tt>--fasta</tt> argument:
+
 
+
$ <span class="enter">bin/prepare-refseqs.pl --fasta ~/Documents/Data/jbrowse/scf1117875582023.fasta</span>
+
 
+
Visit in web browser; you should see a second reference sequence.
+
 
+
==== Features ====
+
 
+
To get feature data from flat files into JBrowse, use <tt>flatfile-to-json.pl</tt>.  We'll use some more of the data from the [[MAKER]] session:
+
 
+
$ <span class="enter">bin/flatfile-to-json.pl \
+
    --gff /home/gmod/Documents/Data/maker/example2_pyu/finished.maker.output/gff/scf1117875582023.gff \
+
    --type match --getSubs --tracklabel "gff_match" --key "GFF match" \
+
    --cssclass generic_parent --subfeatureClasses '{"match_part": "generic_part_a"}'</span>
+
 
+
Visit in web browser; you should see a new "GFF match" track.
+
 
+
==== BAM data ====
+
 
+
To incorporate data from a BAM source:
+
 
+
$ <span class="enter"> bin/bam-to-json.pl \
+
    --bam ~/Documents/Data/jbrowse/simulated-sorted.bam \
+
    --tracklabel BAM_data --key "BAM Data"
+
 
+
=== Quantitative data ===
+
 
+
JBrowse can also display quantitative data in the wiggle format.  JBrowse processes wiggle files with a C++ program, which you have to compile:
+
 
+
$ <span class="enter">make</span>
+
 
+
Now you can process the wiggle file:
+
 
+
$ <span class="enter">bin/wig-to-json.pl --wig ~/Documents/Data/jbrowse/pyu.wig \
+
    --tracklabel "coverage_wig" --key "Wiggle Coverage" --min 0 --max 50</span>
+
 
+
Visit in web browser
+
 
+
<br><br>
+
 
+
== Common Problems ==
+
 
+
* JSON syntax errors
+
 
+
<br><br><br>
+
 
+
== Other links ==
+
 
+
* Config file ref: http://jbrowse.org/code/jbrowse-master/docs/config.html
+
* DIV test: http://jbrowse.org/test/boatdiv/boat.html
+
 
+
 
+
<!--
+
== Advanced JBrowse ==
+
 
+
* Feature CSS
+
 
+
== How it works ==
+
* HTML elements
+
* JSON
+
* NCLists
+
** named vs. positional data formats ?
+
* Static files
+
** No server-side code needed for browsing
+
*** Easier deployment
+
*** Easy parallel installation
+
** HTTP caching
+
*** Traditional: cut down on transfer by only downloading region of interest
+
*** Complement: cut down on transfer by only downloading when there's a change
+
**** Underutilized
+
**** HTTP servers handle this for you automatically with static files
+
-->
+
 
+
== Evaluation ==
+
 
+
{{Feedback}}
+
 
+
{{NextSession|MAKER|MAKER}}
+

Revision as of 21:43, 13 February 2013



JBrowse logo
Status
  • Mature release
  • Development: active
  • Support: active
Resources


Included in

Cloud component

About JBrowse

JBrowse is a genome browser with a fully dynamic HTML5 user interface, being developed as the successor to GBrowse. It is very fast and scales well to large datasets. JBrowse does almost all of its work directly in the user's web browser, with minimal requirements for the server.

Features

  • Fast, smooth scrolling and zooming. Explore your genome with unparalleled speed.
  • Scales easily to multi-gigabase genomes.
  • Supports GFF3, BED, FASTA, Wiggle, BigWig, BAM, and more.
  • Very light server resource requirements. Serve huge datasets from a single low-cost cloud instance.



Visit the JBrowse website.

Screenshots

JBrowse alignment and coverage.png

Downloads


Using JBrowse

The JBrowse Quick-Start Tutorial provides a basic step-by-step recipe for quickly getting up and running with JBrowse.

System Requirements

JBrowse requires libpng, Zlib, and GD development libraries, plus make and a C compiler. On Ubuntu, you can install these prerequisites using the command:

 sudo apt-get install libpng-dev libgd2-noxpm-dev build-essential

For tips on installing these baseline libraries, see JBrowse Troubleshooting.

Installation

The JBrowse Quick-Start Tutorial provides a basic step-by-step recipe for quickly getting up and running with JBrowse.

1. Download JBrowse onto your web server.

2. Unpack JBrowse into a directory that is served by your web browser. On many systems, this defaults to /var/www.

   cd /var/www
   unzip JBrowse-*.zip

Make sure you have permissions to write to the contents of the jbrowse/ directory you have just created.

3. Run the automated-setup script, ./setup.sh, which will attempt to install all of JBrowse's (modest) prerequisites for you in the jbrowse/ directory itself. Note that setup.sh does not need to be run as root or with sudo. For help troubleshooting failures of setup.sh, see JBrowse Troubleshooting.

4. Visit JBrowse on your machine, substituting the http://(your_machine/path_to_jbrowse)/index.html?data=sample_data/json/volvox. If you can see the included Volvox example data, you are ready to configure JBrowse to show your own data!

Configuration

See the JBrowse Configuration Guide for information on:

Additional topics:

Upgrading JBrowse

To upgrade an existing JBrowse (1.3.0 or later) to the latest version, simply move its data directory (and jbrowse_conf.json if you are using it) into the directory of a newer JBrowse, and the new JBrowse will display that data.

To upgrade a 1.2.x JBrowse, copy its data directory into the new JBrowse directory, and point your browser at compat_121.html in the new JBrowse directory, instead of index.html.

If you are upgrading from a version of JBrowse older than 1.2.0, a fresh installation is required.


Publications, Tutorials, and Presentations

Tutorials

JBrowse Tutorial covering installation and configuration
part of the 2013 GMOD Summer School
Getting Started with JBrowse Tutorial
part of the JBrowse documentation
Exploration of structural variation in the tomato clade using JBrowse
Tutorial explaining how to browse structural variants from the 150+ tomato genome resequencing project (http://www.tomatogenome.net) using JBrowse

Presentations

Contacts and Mailing Lists

Please direct questions and inquiries regarding JBrowse to the mailing lists below.

Requests for help should be directed to gmod-ajax@lists.sourceforge.net.

Mailing List Link Description Archive(s)
JBrowse gmod-ajax JBrowse help and general questions. Nabble (2010/05+), Sourceforge
jbrowse-dev JBrowse development discussions. Nabble (2011/08+)


JBrowse Development

Development team

JBrowse is an open-source project, started and managed by the laboratory of Ian Holmes at the University of California, Berkeley.

As of January 2012, the lead developer of JBrowse is Robert Buels. Most of JBrowse was originally written by Mitch Skinner.

There is a mailing list for developers, and there is usually a teleconference on the 3rd Monday of the month at 2pm Pacific US time. We welcome participation from anyone and everyone. Please contact Robert Buels if you would like to listen in or participate.

Current status

The JBrowse source code repository is kept on GitHub. Please feel very free to fork the code on GitHub and make modifications and improvements, submitting pull requests. GitHub has a very nice tutorial on how to get started with this style of development.

More on JBrowse

See Category:JBrowse




Raw tool data at JBrowse/tool data