Loading...
 
Print

JBrowse Dynamix Plugin

The Furlong Laboratory (and GBCS) provides a new JBrowse plugin for displaying dynamic data : Dynamix.

This plugin has been developed to better handle a large number of tracks simultaneously.

In genomics, the various types of experiments generate multiple types of data. Sometimes, the obtained information is continuous (i.e. positive signal present all over the genome), but in several experimental protocols (e.g. some 4C-sequencing experiments) biologists target a few regions, referred to as viewpoints, like known transcript positions, methylated regions etc. . This generates a point-source signal, meaning that the signal is positive only at a few positions over the genome, the rest being background signals (null or ≈0). Although this null signal is a form of information in some situations, in most cases biologists are looking for regions showing statically significant positive signal.

One aspect that can be emphasised here is that the absence of signal does not mean the absence of data. It connotes that background/null signals are as resource-expensive to fetch as positive signals (even if it is less ressource-expensive to draw). This becomes an issue in certain situations,  regarding time and ressource consumption and considering technical limitations of current genome browsers.

Dynamix, a complementary way of browsing:

Plugin behavior:

Dynamix is developed considering the above-mentioned apects (i.e. number of tracks to display, point-source signal and known viewpoints).

It can be installed on any JBrowse instance to improve the user browsing experience when it comes to visualising complex sets of data. A precomputation is necessary to indicate to the plugin the regions that contain information, where the viewer should focus on. Generally, this precomputation will be performed by the data holder and given to the JBrowse administrator to set up Dynamix properly.

During execution, the plugin calculates the current displayed region coordinates at each browsing event ( e.g. dragging & moving, zooming, etc.) and dynamically computes relevant information overlapping this position to propose it to the viewer.

Dynamix has been developed as a complementary way of browsing and does not aim to substitute itself to the classic browsing experience. This is why you can enable/disable the plugin, and defined groups of tracks that will be handled by the plugin (the other tracks remaining browsable the classic way). However it possesses intrinsic characteristics that would be explained below.  

Administrator configuration:

The plugin relies on a special configuration, loaded from an additional independent configuration file. The file contains necessary and sufficient information for the plugin to execute. The minimum information that needs to be given is the following (per viewpoint):

  • The track unique name (referred to as label in JBrowse tracklist configuration),
  • The region(s) of interest over the genome ( chromosome(s) and position(s) )

 

Example of a tab-delimited file containing sufficient information (trackname
Example of a tab-delimited file containing sufficient information (trackname

 

This information can be gathered into different forms, e.g. A classic BED file, or a tab-delimited file (see example above). In both cases the administrator has to create the configuration file. Additionally, the administrator will have to index a corresponding BED file (which can be already existing or created by parsing the given tab-delimited file) with the JBrowse executable Jbrowse-x.xx/bin/flatfile-to-json.pl. This indexed track should contain all necessary information and be defined in the classic configuration file (JBrowse-x.xx/data/trackList.json) as any other. It will be fetched by the plugin, using the group_track_name parameter(see image below), to find relevant information.

The configuration file must be a JSON file complying with the following example, and must be added in the JBrowse-x.xx/data/ folder of the instance. The name of this file must be dynamixDisplayer_conf.json.

Example of a typical one group configuration in  dynamixDisplayer_conf.json
Example of a typical one group configuration in dynamixDisplayer_conf.json

If multiple types of tracks need to be handled, e.g. originating from different types of experiments, one can define distinct groups of tracks that will follow separate displaying rules. Distinct group configurations are separated by commas in the JSON configuration file.

Configuration details:

Instance setting:
Default_state:

String. [[ 'active' | 'inactive']] The global state of the plugin when a user start the JBrowse instance. In its active state, the plugin will be loaded at startup. Oppositely, if the default state is set to 'inactive', the user will have to manually activate the plugin.

Per group settings:
Group_track_name:

String. > The indexed track name. This name is used by the plugin to fetch relevant information from the indexed BED file.  

TrackList:

String. > Track labels separated by commas, e.g. "track1, track2, ..., trackn". Check track labels in the trackList.json configuration. This tracklist gathers all the tracknames handled by this group.

Overlap_range:

Integer. > Number of bases considered to extend information fetching outside the current view boundaries, in order to access nearby positive signal. For example, an overlap_range of 100 000 will allow the plugin to fetch the information located at -100,000 and +100,000 bases around the current observed region, i.e. for a current observed region : chr2L:6,000,000..8,000,000 (2 Mb) and an overlap_range configuration of 100,000, Dynamix will consider all the information available in the region : chr2L:5,900,000..8,100,000 (2.2 Mb), and load corresponding tracks.

Mode:

String [[ 'automatic' | 'manual' | 'disabled' ]]. > Describes how the tracks defined in this trackList will be handled by the plugin. See user interface information below.

Max_tracks:

Integer. > Maximum number of tracks that can be added to the track container by one group. It is defined to avoid loading too many tracks automatically when a large region and/or a large overlap_range are selected. It is advised to chose a number that is in the range of what Genome browsers can load (around ~100 tracks) and considering that each group can load its own number of track. A good value will be close to the average maximum number of tracks loaded when observing a 3 Mb region.

 

 

The user Dynamix interface:

Enabling the plugin:

Dynamix is made to complete and improve browsing. Hence, it can be enabled/fully disabled from the JBrowse main menu in the front-end interface.

Dynamix main menu in JBrowse menu bar. Enables or disables the plugin. Tweak configuration and access help's popup.
Dynamix main menu in JBrowse menu bar. Enables or disables the plugin. Tweak configuration and access help's popup.

Through this menu, the user can also access a settings window and an help popup. The settings window allows user to modify settings during execution, but will not modify the configuration file. For permanent changes, the user needs to access the configuration file in JBrowse-x.xx/data/ and modify it with a text editor.

Once enabled, a widget is added to the view, in the right part of the navigation bar. This widget contains the textual and visual sum up of the information occurring in the view, as well as buttons for the user to interact with - see next section.  

Plugin interface:

Plugin interface with a multiple group configuration file
Plugin interface with a multiple group configuration file

The widget added to the view by Dynamix possesses visual and textual information about the displayed information as well as buttons for the user to interact with. Clicking on the main widget opens a drop-down menu that displays per-group information, the main widget being a summary of all the groups information. 

1. State icon:

 

State icons framed on Dynamix widgets.
State icons framed on Dynamix widgets.

The state icon is a three-state color code ( green , orange , red ). The color gives visual details about the current display status of the group. The state refers to the completeness of the information that is displayed. Indeed, a green icon Image  indicates that the user currently faces all the relevant information, i.e. all the tracks that should be displayed at this position. Oppositely, an orange icon Image  is displayed when Dynamix considers that the user is missing information. A red icon Image  indicates a disabled group (see 2. Mode selector). In automatic mode, the icon will always be green if max_tracks is not reached, because the relevant tracks are automatically added to the view. In manual mode, because the view is not automatically updated, this icon will toggle between green and orange if relevant information is missing. The user will have to interact with the plugin to update the view and add relevant tracks.

The main element contains a two-state icon ( green or orange ), respectively whether all relevant information is displayed or not.

2. Mode selector (only in group widgets) :
Mode selectors framed on Dynamix widgets.
Mode selectors framed on Dynamix widgets.

Three modes are available for a group once it is defined in the configuration: automatic, manual and disabled. A select button is available for the user to change the way Dynamix handles each group of tracks.

➜ Automatic mode:

Automatic mode will automatically modifiy the view by adding and removing tracks while the user browses. Hence, it allows the user to focus only on the information of interest. However, it might be a behaviour that is not desired when seeking information outside of the defined viewpoints. To address this issue, a complementary manual mode is available.

➜ Manual mode :

Manual mode will automatically update the widget's information, telling the user about what he is viewing/missing, however it will not add nor remove tracks from the view without user interaction with the update buttons (see 4. Update buttons).

➜ Disabled mode:

Disabling a group of tracks is used when the user wants to handle this group in the classic way, like if it was not defined in the plugin configuration file. The difference between manual and disabled modes is that in disabled mode, the tracks of the disabled group are not considered when computing the overall state i.e. green v.s. orange icon state.

3. Textual sum-up :
Sum-up ratios framed on Dynamix widgets.
Sum-up ratios framed on Dynamix widgets.

The main and group elements both contain a ratio (X / Y) of the number of relevant tracks that are currently being displayed (X), over the total number of relevant tracks that should be displayed (Y).

It will normally be equal to 1 in automatic mode (except if max_tracks is reached), whereas in manual mode it will be inferior to 1 if information is missing. The main widget contains the total number of groups defined in the configuration. Group widgets contain the name of the group and the total number of tracks associated to this group in the configuration file.

4. Update buttons :
Update buttons (refresh and update) framed on Dynamix widgets.
Update buttons (refresh and update) framed on Dynamix widgets.

In manual mode, users have access to two buttons to update the view. According to the textual sum-up, they can know if information (e.g. tracks) is missing. Updating the view to add missing information is as easy as clicking buttons. Two ways of updating the view are available, depending on how users want the manual mode to behave, i.e. how the view will be updated.

The first button ( refresh, ⟳ ) is a refresh button that will add missing tracks and remove tracks that have no signal for this position, which is exactly what the automatic mode does. The second button update, + ) is an only add missing track button that will only add missing tracks, without removing previously observed tracks handled by this group.

The two update buttons are also available through the main widget. The characteristics are the same but they will apply to all the manually handled groups.

5. Warning state (max_tracks reached) :
warnin_img
Main and group widgets in a warning state

The maximum of track that a group can load is defined by the max_tracks parameter. If a large genomic region is selected, or simply in a case where a lot of tracks are relevant for a smaller region, max_tracks will be reached. 

If max_tracks is reached for at least one group, the widgets will be displayed in a warning state. This state displays a warning triangular icon on the main widget Image . The group that reached his own max_tracks parameter (here 25, for the 4CSeq_Yad group) will display a specific orange icon containing an exclamation mark Image . Importantly, even in manual mode it will not be possible to add more tracks without modifying this setting, increasing the max_tracks number.