Difference between revisions of "JBrowse 2 Tutorial PAG 2022"

Revision as of 00:39, 28 December 2021

This is very much a draft version of the PAG 2022 tutorial, using the JBrowse 1 tutorial as a template.

This tutorial assumes a VirtualBox Ubuntu 18.04 (LTS) instance with the tutorial bundle zip file, also available on Amazon S3: JBrowse PAG 2020.ova (about 4GB) or PAG_2020_JBrowse.zip (about 36MB) for just the JBrowse source and data files for this tutorial.

Prerequisites

Prerequisites are installed by JBrowse automatically. A few things may fail to install (like legacy support for wiggle files), but that doesn't matter.

Make sure you can copy/paste from the wiki.

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

It's probably a good idea to use a browser like Chrome or Firefox that has the ability to turn off caching while working on this tutorial. To do this in Chrome, with the browser open to the JBrowse page you're working on, select Developer->Javascript Console from the View menu. In the console, click the "gear" icon (settings) and check the box labeled "Disable Cache".

A few basic packages were installed before JBrowse via apt-get:

 sudo apt-get install build-essential zlib1g-dev apache2 curl

Also, a few items were installed that aren't needed for this tutorial but would be necessary if you wanted to add plugins (git and NodeJS):

 curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -
 sudo apt-get install -y nodejs
 sudo apt-get install git

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

A Short Detour for GFF

GFF (Generic Feature Format) is a very commonly used text format for describing features that exist on sequences. We'll head off to that page to talk about it a bit.

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": "PAG 2017 P. ultima Example",
  "db_adaptor": "Bio::DB::SeqFeature::Store",
  "db_args" : {
      "-adaptor" : "memory",
      "-dir" : ".."
   },
...

Specify reference sequences

Load Feature Data

Index feature names

Features from GFF3 or BED files

Quantitative data

Changing the way tracks look

Tracks can be modified by changing several aspects of how the images are created. While this can be done be done both with HTML and Canvas tracks, this tutorial will focus on Canvas tracks only (the repeat tracks created above).

The configuration for the RepeatMasker track looks like this:

      {
         "key" : "RepeatMasker",
         "trackType" : "CanvasFeatures",
         "storeClass" : "JBrowse/Store/SeqFeature/NCList",
         "urlTemplate" : "tracks/repeat masker/{refseq}/trackData.json",
         "style" : {
            "subfeatureClasses" : {
               "match_part" : "feature"
            },
            "className" : "generic_parent"
         },
         "type" : "CanvasFeatures",
         "compress" : 0,
         "label" : "repeat masker"
      }

Open the data/trackList.json file in your favorite editor and Control-F will open a "find" window; search for "repeatmasker". A simple change we can make is to the color; in the line starting with "style", add:

  "color" : "black",

save the changes and select the RepeatMasker track or reload the browser to see the change. Many attributes of the display can be modified in this way, see the JBrowse Configuration Guide for a list of options.

Making changes based on the data

Much like GBrowse's perl callbacks that can change the track display, in the JBrowse configuration file you can include JavaScript functions to change the way tracks look. For example, in the RepeatMasker track, we can change the color of the glyph depending on what kind of repeat it is (where we happen to know that the type of repeat is encoded in the name). In this example, we leave the glyph black, unless it is a low complexity repeat, where we'll color it red. A function to do that would look like this:

  "color" : "function(feature) { var name = feature.get('Name'); if (name.match('Low_complexity') ) { return 'red'; } return 'black';  }",

When editing the trackList.json file directly in this way, the function has to go all on one line, but if we create an "include file" (not covered here) the function can have carriage returns in it. Replace the simple "color : black" section we just created in the configuration file with the function above, save the file and reload the browser page to see the changes (you might have to mouse around to find a low complexity repeat).

Making links open something else

The default action when you click on a glyph is to open a "floating" window that displays everything JBrowse knows about a feature. If you'd like something else to happen, you have several options (outlined here), including having a different floating window open or executing any JavaScript function you define. For this example, we'll create a link that will Google the repeat's name and open the result in a new window. In the RepeatMasker section of the JBrowse configuration, we'll add a section that looks like this after the style section:

        "onClick" : {
           "iconClass" : "dijitIconDatabase",
           "action" : "newWindow",
           "url" : "http://www.google.com/search?q={name}",
           "label" : "Search for {name} at Google",
           "title" : "function(track,feature,div) { return 'Searching for '+feature.get('name')+' at Google'; }"
        },

If you're having difficulties, the RepeatMasker section of the configuration file should now look something like this:

      {
         "key" : "RepeatMasker",
         "trackType" : "CanvasFeatures",
         "storeClass" : "JBrowse/Store/SeqFeature/NCList",
         "style" : {
            "color" : "function(feature) { var name = feature.get('Name'); if (name.match('Low_complexity') ) { return 'red'; } return 'black';  }",
            "subfeatureClasses" : {
               "match_part" : "feature"
            },
            "className" : "generic_parent"
         },
         "onClick" : {
           "iconClass" : "dijitIconDatabase",
           "action" : "newWindow",
           "url" : "http://www.google.com/search?q={name}",
           "label" : "Search for {name} at Google",
           "title" : "function(track,feature,div) { return 'Searching for '+feature.get('name')+' at Google'; }"
        },
         "label" : "repeat masker",
         "urlTemplate" : "tracks/repeat masker/{refseq}/trackData.json",
         "compress" : 0,
         "type" : "CanvasFeatures"
      },

Using Plugins

JBrowse is built with a very flexible and powerful plugin system. The JBrowse developers are working on a plugin registry website, but for the time being, you can look at the source code for what will drive the website in the jbrowse-registry github repo, and in particular, the file that contains the info about the available plugins, plugins.yaml.

For this tutorial, we'll look at a plugin that is shipped with JBrowse but isn't turned on by default. JBrowse plugins are typically stored in the plugins directory, and in 1.12.1's plugin directory there are 6 plugins:

 CategoryUrl
 DebugEvents
 HideTrackLabels
 NeatCanvasFeatures
 NeatHTMLFeatures
 RegexSequenceSearch

and the RegexSequenceSearch plugin is already activated (look under the "Track" menu for it). We will turn on the HideTrackLabels plugin. Open jbrowse.conf:

 gedit jbrowse.conf

and find (cntl-F) "plugins", which will look like this:

## uncomment and edit the example below to enable one or more
## JBrowse plugins
# [ plugins.MyPlugin ]
# location = plugins/MyPlugin
# [ plugins.AnotherPlugin ]
# location = ../plugin/dir/someplace/else

Add below this a few lines to active the HideTrackLabels plugin:

[ plugins.HideTrackLabels ]
location = plugins/HideTrackLabels

Note that not all plugins are activated this way: typically, if it modifies the way JBrowse *works*, it will go here. If the plugin modifies the way tracks look will go in the trackList.json file.

JBrowse Features

Highlighting interesting things

To highlight a region, you can either right-click on a feature and select 'highlight this', or you can set the highlight explicitly to a certain genomic region by clicking "View -> Set highlight" in the menu bar.

Beginning in JBrowse 1.10.0 you can also highlight a region with the mouse by clicking the highlighter tool (next to the Go button) and clicking and dragging to highlight a region.

Opening local files

JBrowse can display GFF3, BAM, BigWig, and VCF+Tabix files directly from your local machine without the need to transfer any data to the server. Just use the "File -> Open" tool from the menu bar to add tracks using local files.

Combination tracks

Starting in version 1.10.0, users can define tracks that are combinations of the data in other tracks. The operations used to combine these tracks can be set operations (union, intersection, subtraction), arithmetic operations for quantitative tracks (addition, subtraction, multiplication, division), and/or masking operations to just highlight or mask some regions based on data in another track.

To add a combination track, select "File->Add combination track" from the menu bar, and drag existing tracks into the new combination track to start combining them.

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 after running the setup.sh script.

Common Problems

• JSON syntax errors in configuration files (2.x series will stop this madness!)

Other links

• Config file ref: JBrowse Configuration Guide
• DIV test: http://jbrowse.org/test/boatdiv/boat.html