Dynamix

Dynamix allows dynamic display of genomic information upon browsing. Dynamix registers tracks and their associated set of genomic coordinates where potentially interesting genomic features have been identified. Registered tracks are dynamically displayed to the browsing user when moving around the genome.

Dynamix is a plugin for the JBrowse genome browser, developped in the Europen Molecular Biology Laboratory - EMBL -, in Heidelberg, by the Furlong Laboratory (http://www.embl.de/research/units/genome_biology/furlong/index.html - http://furlonglab.embl.de/) and the Genome Biology Computational Support - GBCS (http://gbcs.embl.de/).

=================================================================================================

Plugin : Dynamix v1.0 (08-14-2014, stable) Download link : Contact Author, see Author section at EOF Introduction link : http://gbcs.embl.de/portal/tiki-index.php?page=JBrowse%20Dynamix%20Plugin Programmer : Matthias Monfort Keywords : dynamix, plugin, jbrowse, genome, browser, dynamic, browsing, dojo, ...

=================================================================================================

Background

Visualisation of high-throughput genome-wide sequencing data in genome browsers becomes more challenging with the increasing size of datasets outcoming from single experiments. In addition, successful visual analysis of such datasets often requires to visualise them in association with other datasets, complementary and well-established, shared among a scientist community. This results in a large pool of information that needs to be simultaneously observed. In this context, smooth visualisation is often impaired by technical limitations such as the limited ressources available for visual rendering of genomic information or the limited vertical real-estate available for information juxtaposition on a typical computer monitor. It is needed to overcome those current technical limitations in order to allow intuitive and efficient genome browsing of large datasets.

The genomic information available in genome browsers is registered in the form of tracks. Each track contains both the genomic information that has been aligned to a reference sequence and a set of rules to render it in 2D. Tracks can for example display discrete (in the term of "features") or continuous (in the term of "signal") types of information. Large datasets typically result in a large number of those different tracks, aligned to the same reference and stacked upon each other .

Over a given reference genome, the information of interest can be sparsely and unevenly distributed, thus the relevant information on two different genomic intervals might come from two very different sets of tracks. Since it is technically very challenging to simultaneously stack many of those tracks, when browsing large datasets, the user is forced to tediously interchange the visualised pool of tracks between different genomic regions.

Description

Dynamix proposes a solution allowing users to gain visual analysis power by automatically modifying the set of visualised track. Dynamix allows the user to focus only on the information of interest for the observed genomic region by hiding obsolete pieces of information (that were relevant on the previous genomic region) and displaying relevant ones. Namely, it selectively moves tracks from the track selector into the track container (and vice-versa) when needed. Relevant locations for tracks are not computed by Dynamix itself but objectively defined beforehand through well-established analysis tools and pipelines (e.g. relevant locations defined using peak calling). Dynamix maps locations information to the tracks using unique IDs.

Technically, it relies on an indexed track that stores this map in a format that can be queried upon browsing. When moving to a new genomic region, the track is queried and returns the set of relevant track IDs associated with the relevant genomic intervals overlapping the observed region.

A track can therefore be registered with Dynamix in an JBrowse instance using a set of coordinates defining relevant genomic intervals. Registration associates the track identifier to each of these genomic intervals. In the case of a signal track, Dynamix associate the unique ID of the track to each relevant genomic interval that are described in an associated feature track. In the case of a feature track, the set of relevant genomic intervals is intrinsically defined, thus each interval is associated with a unique ID corresponding to the track itself.

Since the track container content can be automatically updated, Dynamix implements a control parameter (maxTracks) that defines how many tracks maximum Dynamix can add to the track container. This allow users with different hardware to enjoy dynamic browsing to the limit of their computing power.

Key features

• Automatic track display Dynamix automatically displays to the user tracks that possess relevant information on the observed genomic interval. Namely, it selectively moves tracks from the track selector into the track container (and vice-versa) when needed.

• Manual track display Dynamix proposes a manual mode that computes which set of track is relevant over the observed genomic interval, and indicate it to the user via the interface, but does not modify automatically the track container without explicit user demand. This manual mode complements the fully automated behavior and allows noticing that a piece of the registered information is missing on the observed genomic interval.

• Grouping of related tracks Independent track groups can be defined. Each of the group is autonomous and might have a different behaviour and configuration. As an example, the maxTracks parameter is implemented on a per group basis, i.e. the user controls how many tracks maximum can be added in the track container.

Instalation

This How-To aims at explaining step by step how to get Dynamix set-up in a JBrowse instance.

[ Pre-requisites ]

• A functional JBrowse instance. The latest release of JBrowse is available at http://jbrowse.org/install/. A complete set-up guide is available at http://gmod.org/wiki/JBrowse_Configuration_Guide

• A batch of files constituting the dataset. To register a track in Dynamix, one needs to provide a set of genomic interval in the form of a tab-delimited file. One tab-delimited file per track. If the user is interested in dynamically showing signal, he needs to provide a tab-delimited file describing genomic interval of interest for each signal file.

       refSeq  start   end
       ______________________________
      |chr2L   1007764 1308130       |
      |chr2L   1007764 1308130       |
      |chr2L   1007764 1308130       |
      |[...]                         |
      |______________________________|
  
      *refSeq:        Reference sequence where the signal is located,
                      e.g. the chromosome name.
      *start & end:   Lower and upper bound of the signal location
                      over the refSeq.

[ Important steps ]

1. Download Dynamix [ TODO LINK ]

2. Unzip Dynamix archive

3. The folder should contain:

   • This README file,
   • The Dynamix source code (js/ folder)
   • A python script to create the needed Dynamix configuration (pyscripts/ folder). The python script import the following libraries:
     • os
     • re
     • sys
     • time
     • subprocess (to call JBrowse's perl scripts)
     • simplejson (to parse JBrowse and Dynamix configurations)

4. Indicate to JBrowse the plugin path, and its configuration in the jbrowse.conf configuration file (JBrowse/jbrowse.conf). By default dynamix configuration is created by the script at JBROWSE_ROOT/data/dynamix/

   • In jbrowse.conf, indicate Dynamix path as so: [ plugins.Dynamix ] location = plugins/Dynamix

   • In jbrowse.conf, indicate Dynamix configuration file. In the [GENERAL] section, add the following include line (the file itself is automatically created later on by the Dynamix configuration script): include += {dataRoot}/dynamix_conf.json

Tracks registration (plugin configuration)

One registers track by executing the dynamix python script(in JBROWSE_ROOT/plugins/dynamix/pyscripts/)

To register a feature track, the user would execute:

        python2.7 dynamix add-dx-data -g GROUP_NAME --id TRACK_UNIQ_ID -f PATH/TO/TAB/DELIM/FILE --index-features --display-name="Human readable name"

Where -g indicate the group name, --id the unique track ID, -f the path to the tab delimited file describing relevant genomic intervals. --display-name is an optional parameter to define a human readable name that would be use by JBrowse interface. The path to the tab-delimited file can be absolute as there is an indexing step which stores the index somewhere where JBrowse can access at browsing time.

To register a signal track, the user would execute:

        python2.7 dynamix add-dx-data -g GROUP_NAME --id TRACK_UNIQ_ID2 -s ../../../data/PATH/TO/SIGNAL/FILE -f PATH/TO/TAB/DELIM/FILE --display-name="Human readable name"

Where -g indicate the group name, --id the unique track ID, -s the path to the signal file and -f the path to the tab delimited file describing relevant genomic intervals. As JBrowse is natively handling bigwig file (it reads them at browsing time), it is necessary to store it where it can access it, e.g. in the data folder and to give the relative path to the file to the dynamix script. NB: With such command line, the tab-delimited file is only used to describe the relevant genomic intervals for the signal track. However, in such cases the tab delimited file can also be register to be dynamically shown, just by adding --index-features to the command line.

Registering a track for the first time should create all the needed configuration files at JBROWSE_ROOT/data/dynamix. See the "Configuration details" section

Usage

Plugin Activation

In the JBrowse top-menu : Dynamix > Enable Dyanmix You might as well modify the default Dynamix state in dynamix_conf.json by setting it to "active"

When activated the plugin displays an interface widget in the JBrowse browser.

Interface & Features

• Main widget : The main widget provide a general visual sum-up of the information available at the current genomic position taking into consideration all the registered tracks for all the different groups. The text sum-up follow this pattern [X] Y/Z. With X: the total number of tracks that are currently displayed by the group on the observed region, disregarding their relevance. Y is the number of shown relevant tracks and Z the total number of relevant track on the observed region. The main widget also provides interactive elements to update the view. A click on the main widget will open a drop-down that contains group widget(s).

• Group widget(s) : Dynamix can handle several groups, each with its own behavior. Each group possesses its own widget that contains the same information and buttons than the main widget, but on a per group basis. The main difference is the Select menu, that allow to change the group behavior from automatic to manual (and to disable it if needed).

When in 'Manual' mode user have to interact with the widgets to get the track container updated. When using main widget buttons, the track container is updated for all widgets.

The user can interact with

• the group behavior selector (auto - manual - disabled)
• the plus button (#+): This button will only add missing relevant tracks on the observed genomic location, keeping tracks previously shown by the group.
• the refresh button (#): This button will add relevant tracks and hide irrelevant tracks for the observed regions. In case max tracs is reached, a part of the relevant tracks is not shown: this button will allow a turnover of visible tracks. Hiding visible relevant tracks and showing not shown relevant tracks
• the minus button (#-): This button will hide tracks that are not relevant anymore on the observed genomic location.
• the signal toggle button: This button allows to toggle the display of signal tracks.
• the features toggle button: This button allows to toggle the display of feature tracks.

When relevant tracks are missing, the circle indicator is orange, while green when everything relevant is shown. When max track is reached for at least one group a warning icon is displayed by the main widget and by the circle indicator of the group(s) that have reached its(their) limit.

Settings

Additional setting can be accessed through the configuration window via the Dynamix menu (Dynamix > Settings). Namely:

• the group max_tracks : It is the maximum number of tracks that can be added to the track container by one group.
• the group overlap_range (%): If set (>0), it defines the region size outside the visible region where relevant tracks should be fetched. In % of the visible region. If e.g. 10% Dynamix will fetch relevant track at -10% and +10% of the visible region length (bp).

Configuration details

TODO: This changed a bit, to update

The Dynamix configuration file is a JSON file, the structure is the following:

        dynamix_conf.json:
         _______________________________________________________________________________________
        |{                                                                                      |
        |    "dynamix": {                                                                       |
        |        "default_state": "inactive",                                                   |
        |        "default_configuration": {                                                     |
        |            "Group_name": {                                                            |
        |                "overlap_range": "0",                                                  |
        |                "group_track_name": "indexed_track_label",                             |
        |                "trackList": "track_label1,track_label2,...,track_labeln",             |
        |                "mode": "automatic",                                                   |
        |                "max_tracks": "25",                                                    |
        |            }                                                                          |
        |        }                                                                              |
        |    }                                                                                  |
        |}                                                                                      |
        |_______________________________________________________________________________________|

Contact

For any remark, question, suggestion, bug report on Dynamix please contact Matthias Monfort (see Author below). Do not contact the author for JBrowse related issues, contact GMOD/JBrowse Support instead (see http://gmod.827538.n3.nabble.com/JBrowse-Support-f815920.html)

Author

Matthias Monfort, Bioinformatics Technical Officer in the Furlong lab @EMBL, Heidelberg mail1 : monfort@embl.de mail2 : monfort.matthias@gmail.com

Charles Girardot, Head of the Genome Biology Computational Support @EMBL Heidelberg, mail : girardot@embl.de