Revision as of 17:29, 24 August 2011

This is a space for notes about unreleased JBrowse developments. Developers are encouraged to document their code on this wiki page as they are writing it. This will not only provide a means for review, it will also considerably simplify the process of updating the current documentation when there is a new JBrowse release.

Guidelines

1. Describe how you've changed the functionality of JBrowse from a user's perspective. Assume that your readers already have a basic understanding of how to use JBrowse.

2. Provide a link to the repository with your code. If the code is unfinished, please indicate this in some way.

3. Keep track of which edits have been moved to the current documentation. When documentation is copied over to JBrowseDev/Current, remove the notes that no longer belong in this section.

Changes Since the Latest Version (JBrowse 1.2.1)

github fork nsfox/jbrowse, development May-August 2011

The following functionality has been added to the repository: https://github.com/nsfox/jbrowse.

Flags are available for the admin to activate/deactivate many of the following features. By default all new functionality is present and active. The flags are set in conf.js as seen below.

   var conf = {
       //popUpUrl can be an html file or a cgi script that produces html links 
       'popUpUrl' : '/cgi-bin/popup.pl',
       // if a flag isn't present then it defaults to false
       // Available flags are:
       //    facetedOff = controls the creation of the Find Tracks tab
       //    trackCustomizationOff = removes track customization from the popup and sets trackCustomizationHidden to true
       //    trackCustomizationHidden = hides the Customization tab label from the left of the page
       //    elasticZoomsOff = sets both elasticZoomTopOff and elasticZoomMainOff to true
       //    elasticZoomTopOff = deactivates the elastic drag zoom over the overview area, will override elasticZoomsOff
       //    elasticZoomMainOff = deactivates the elastic drag zoom for the display area, will override elasticZoomsOff 
       'flags': {
          'trackCustomizationHidden': true
       }
   }

Structured Track List

In the JBrowse client, hidden tracks are currently represented in a simple list format, as demonstrated in Media:JBrowseUI.png. This format is fine when there are a small number of tracks, but it cannot be used to efficiently manage large numbers of tracks. To make management of large numbers of tracks easier, a structured track list has been implemented. This tool makes it possible to organize tracks in a tree structure.

• 

  Select Tracks View

• 

  Find Tracks View

Select Tracks Tab

The select tracks tab is a structured version of JBrowse's current track list. To display a track, drag the track from the track list to the display area. One way to remove the track from the display is to drag it back to this track list.

In setup, the administrator adds tracks to JBrowse by the current process using prepare-refseqs.pl, biodb-to-json.pl, flatfile-to-json.pl, etc. However, the tracks will not appear in the Selected Tracks tab until prepare-nested-structure.pl is run. This script uses the category field associated with each track in a config file to specify the hierarchal structure of the tracks in JBrowse. The config file must have a specified track field within the tracks array for every track you wish to display in the track list. If the category field is not specified then the track will be place in the general category. Also, if prepare-nested-structure.pl is run without the conf option, every track will be put in the general category. This conf file can be combined with the conf file for biodb-to-json.pl if there is one.

Basic syntax:

   bin/prepare-nested-structure.pl --conf <conf file> [options]

Example conf file (for the volvox demo):

{
 "tracks": [
   {
     "track": "ExampleFeatures"
   },
   {
     "track": "NameTest"
   },
   {
     "track": "Motifs"
   },
   {
     "track": "Alignments",
     "category": "AlignmentsGroup"
   },
   {
     "track": "Genes"
   },
   {
     "track": "ReadingFrame",
     "category": "GenesGroup"
   },
   {
     "track": "CDS",
     "category": "GenesGroup"
   },
   {
     "track": "Transcript",
     "category": "GenesGroup"
   },
   {
     "track": "Clones"
   },
   {
     "track": "EST"
   }
 ]
}

Find Tracks Tab

The find tracks tab provides searching for tracks based on their metadata. The metadata fields are shown with their possible values on the left side of the tab. Clicking on a metadata value limits the track list, on the right of the tab, to only the tracks with that selected metadata value. Clicking on the track will toggle it on and off.

After the administrator adds tracks to JBrowse, the find tracks tab can be set up by running setup-faceted-browsing.pl. The script uses a config file to specify which metadata field can be browsed and give the metadata.

Basic syntax:

   bin/setup-faceted-browsing.pl --conf <conf file> [options]

Conf file format:

{
 "facets": [ { "field": "metadata1", "label": "Color"},
             { "field": "metadata3", "label": "Metadata 3 Label"},
             { "field": "metadata4", "label": "Metadata 4 Label"}],
 "tracks": [
   {
     "track": "ExampleFeatures",
     "key": "Example Features",
     "metadata1": ["value1", "value2", "value3"],
     "metadata2": "value 3",
   },
   {
     "track": "NameTest",
     "metadata1": ["value4", "value8"],
     "metadata2": "value1",
     "metadata4": "value 7",
     "key": "Name test track"
   },
...
...
...
   {
     "track": "EST",
     "metadata1": ["value22"],
     "metadata3": "value 13",
     "key": "ESTs"
   }
 ]
}

Overview Level Tracks

Overview level tracks are static tracks that show the entire data set. Currently, the only overview level track type is the Chromosome Representation. The overview level tracks have the same basic config file design as the other tracks. Overview level tracks cannot be hidden or reordered and they do not have a track list menu.

• 

  Overview track Chromosome Representation

Adding a Chromosome Representation Track

After adding the reference sequences, running add-chromosome-track.pl input a single chromosome representation overview track into JBrowse.

Basic syntax:

   bin/add-chromosome-track.pl [options]

Pop-up menu

A right click on a track feature opens a pop up menu. Customize Track and Close Track are default Options that are always set first. However, the Customize Track option can be removed using the trackCustomizationOff flag. The other options, in this case feature Page and Experiment Page, are dynamically create by a script provided by the administrator.

• 

  Right Click Pop-up Menu

Additional Options Setup

The file that is used to dynamically create the popup menu is specified in conf.js. The script is passed the start, end, strand, label, and id corresponding to the feature which was clicked on and the track name in which is passed as track_name.

The following is a simple script that creates the example options:

   #!/usr/bin/perl
   use strict;
   use warnings;
   use CGI;
   my $q = CGI->new;
   print $q->header;
   print '<a href="http://yourGenePage?feature=',$q->param('label'),'" target="_blank">Feature Page</a>';
   print '<a href="http://yourExperimentPage?experimentName=',$q->param('track_name'),'" target="_blank">Experiment Page</a>';

If there isn't a cgi-bin directory set up to run scripts, the links can be specified in an html file:

   <a href="http://yourGenePage" target="_blank">Feature Page</a>
   <a href="http://yourExperimentPage" target="_blank">Experiment Page</a>

Track Customization

• 

  Customizing Track Option

Elastic Drag Zoom

To initiate a drag zoom, click and drag the mouse over one of the scale areas. the There are two levels of elastic drag zooms. First is the high level which is used by dragging in the area over the overview tracks. The second zoom is used by dragging in the grey scale area over the main display area for tracks.

• 

  Overview Elastic Drag Zoom

• 

  Display Area Elastic Drag Zoom

JBrowse Developer Notes

The JBrowse client is implemented using using the Dojo Toolkit. The dojo files included in JBrowse are located in the jslib directory. If on the addition of new features to JBrowse, additional dojo bundles are used than this process can be followed to include the needed dojo code into JBrowse.

The files are created through the following build process:

First, download the Dojo Toolkit. Be sure to select the source release (Dojo ToolKit SDK).

Within the release,

   cd util/buildscripts/

create the following file called profile/jbrowse_dojo.js.profile.js. This is the file which specifies what bundles should go into the compressed build ( will be created as ../../release/dojo/dijit/jbrowse_dojo.js). The dependencies match the dojo.require statements from the JBrowse JavaScript files.

   dependencies = {
       layers: [
               {
                       // This is a specially named layer, literally 'dojo.js'
                       // adding dependencies to this layer will include the modules
                       // in addition to the standard dojo.js base APIs.
                       name: "jbrowse_dojo.js",
                       dependencies: [
                               "dojo.dnd.Source",
                               "dojo.dnd.Moveable",
                               "dojo.dnd.Mover",
                               "dojo.dnd.move",
                               "dijit.layout.ContentPane",
                               "dijit.layout.BorderContainer",
                               "dojo.data.ItemFileWriteStore",
                               "dijit.tree.ForestStoreModel",
                               "dijit.tree.dndSource",
                               "dojo.cache",
                               "dijit.Tree",
                               "dijit.form.TextBox",
                               "dijit.form.Button",
                               "dijit.form.TabContainer"
                       ]
               }
       ],
       prefixes: [
               [ "dijit", "../dijit" ],
       ]
   }

Then run the following to create the build.

   ./build.sh profile=jbrowse_dojo action=release optimize=shrinksafe.keepLines layerOptimize=shrinksafe.keepLines

The release that was just created is found in ../../release/dojo. The required files should then be copied over to JBrowse's jslib directory.

Note: dijit/themes/tundra/tundra.css has been modified so cannot simply be copied over. Also dojo/jbrowse_dojo.js requires a few small changes to remove the default icons from the dijit.Tree. All other files haven't been modified.

See also

• JBrowseDev/Main
• JBrowseDev/Current