Exploration plugin
The introduction
Exploration plugin provides more focused way of molecular interaction network exploration than a default searching, zooming and panning provided by MINERVA.
It is a helpful tool in case a user wants to explore a neighbourhood of a molecule appearing multiple times in a network in different compartments or context. In large networks certain entities need to be duplicated to obtain more readable layout or the entity might be very prevalent and significant in different pathways (e.g. “regular” searching for SNCA gives more than 100 results in different compartments, involved in various roles in different processes).
With the exploration plugin, the user can:
- See in which (sub)maps an interacting partners of the EOI are present
- See in which cell’s compartments interacting partners of the EOI are present
- Iterative exploration of partners’ neighbourhood in given compartment (localized exploration)
- Restrict types of interacting partners
- Highlight identified interactions in the map
- Locate interacting entities in the map
- Trace back list of interactions to the EOI
- Search for entities or reaction type by keyword
- Export the current state of the exploration
Start the plugin
Entering the below address in the plugin URL box to start:
https://minerva-dev.lcsb.uni.lu/plugins/exploration/plugin.js
To start the exploration, choose a bioentity neighbourhood to explore. We call this bioentity entity of interest - EOI and here we use PRKN gene as EOI example. You can click on particular element in the map or by search for it using the search box. Note that the color of Explore button in the top left corner of the plugin turns to dark green after selecting bioentity and shows its name when hovering over it. Clicking on Explore button creates a node representing the chosen entity on the canvas.
The adjacent buttons, next to the Explore, allow on (from left):
- Turn on/off map focus by hovering on the tree elements
- Restart exploration
- Choose Settings of plugin
- See the manual
By left clicking the initial node (in our example PRKN), the plugin connects to the server and obtains all the entities which are connected to it by any reactions. Please note, that only elements of the selected types (see section Settings below) are visible. The retrieved entities are then visualized as a tree by grouping them firstly by (sub)map and secondly by compartment they reside in. The (sub)map nodes are represented by gray diamond symbols and compartments by gray rectangles with rounded edges. Note that the visualization can be pan and zoom by click and drag or zoom in/out.
The tree in this stage thus has four levels:
- The root representing all instances of the the EOI anywhere in the map (including submaps).
- The (sub)maps in which the EOI connects by a reaction to any entity (of the selected type).
- The compartments in given (sub)map in which the EOI connects by a reaction to any entity (of the selected type).
- The entities (of the selected type) connected by a reaction to the EOI. The arrow head connecting the compartment node with the entity node specifies the type of relation of the two connected entities (see below Graphical Symbols for details). If given (sub)map and compartment contain multiple times a pair of entities connected by the same type of reaction in the same role, this pair will be shown only once. But, the information about it can be obtained by hovering over the target (right hand side) node which reveals information on all bioentities represented by that particular node.
By left clicking any of the inner nodes, the corresponding subtree gets folded or unfolded making more space for the rest of the nodes.
By left clicking on a leaf entity node, the plugin connects again to the server and retrieves all bioentities connected to it by a reaction and shows them grouped by compartment.
If there is no connected entity which has not been encountered yet, the node changes to empty node (no color filled).
Please note that here only neighbours connected to the bioentities represented by that specific node are shown. E.g. if a node represents gene G in a compartment C only neighbours of gene G in C are shown irrespective whether G appears also in other compartment D. That is, unlike at the root level, the exploration is restricted to a specific position in the map - localized exploration.
Searching
The exploration plugin offers search functionality for entities or reaction types containing entered keyword. The two search boxes are located at the bottom in plugin panel. The non-matched entities become transparent thus highlighting the matched entities and the entities from the roots of the respective trees to the matched entities. See below an example of searching for PINK.
Additional features - right click
If you right click on any entity pop up with menu shows, containing four options described below:
- Spawn new root
- Locate
- Locate subtree
- Backtrack
Spawning multiple trees
To check what are neighbours of an encountered bioentity anywhere in the map, i.e. go from local exploration to global exploration, right click on that node and choose Spawn new root. With this operation a new independent root is spawned and this root node again represent all instances of given bioentity anywhere in the map and submaps. Any node in the previous tree which matches the new root is highlighted by thick black circle around that node.
The spawned trees are tracked by rectangular buttons in the upper part of the visualization. Clicking on any of those, positions the view so that it is centred on the root of the respective tree.
A tree can be removed by right clicking on the root of a node and selecting Remove root. This operation removes not only the respective tree, but also all the following trees since those were spawned from the tree being removed which is not valid any more.
Locate - interaction with the map
All bioentities represented by the nodes in the visualization are highlighted in the map. This also holds for all reactions which connect an entity to its predecessor in the exploration. Specifically, the EOI is highlighted by an icon while all other entities and reactions are highlighted by color overlay.
The highlighted parts of the map can be either explored by panning and zooming, but the user can also right click on any node in an exploration tree and select Locate which takes to the corresponding position in the map. By choosing Locate subtree, which is available for non-leaf nodes, one can focus on a part
of the map covering all the nodes in the subtree rooted in the respective node.
The locating function can be turned on by default by clicking the bulls eye icon in the upper part of the plugin. If turned on, then every time a user hovers over a node, the corresponding entities will be located in the map.
Backtracking
It might be difficult to see in the map the sequence of reactions which connect certain bioentity with the EOI, especially when multiple roots were spawned. If that is the case, one can right click on any node and select Backtrack. This will highlight all paths from the selected node to the root of the first tree (if the backtrack depth is not specified - see Settings). The path will also be highlighted in the map, temporarily turning off other highlights created by the plugin.
Backtracking will result in multiple paths in situations when the root of one tree corresponds to multiple bioentities in the previous tree.
The backtrack paths can be turned of by right clicking on the node from which the last backtrack was started and selecting Clear backtrack.
Export
The export button is located in the lower right corner of the plugin. All currently visible elements in the visualization can be exported either to a CSV or JSON file by clicking on Export button.
Please note that the data are hierarchical and therefore the JSON format is more suitable for storing the data. If there are multiple spawned trees, they are all exported and separated by an empty line in the resulting CSV.
Graphical symbols
To distinguish different types of information in the visualization, the exploration plugin uses different graphical symbols for nodes and lines arrow heads.
- Nodes
There are three types of nodes:- Circles represent bioentities nodes and their color correspond to the exploration tree they appear in. If the the sphere has no fill color, there are no neighbours to explore (all appear in the path from that node to the root of the respective tree)
- Gray rectangles with rounded corners represent compartment nodes
- Gray diamonds correspond to (sub)maps nodes
- Lines
Lines differ by their arrow heads which represent what is the role of the two connected entities in a reaction. The arrow head can be either circle, arrow, or vertical bar depending on the reaction type and role of the right hand side entity (target). The mapping is as follows:- circle: the target modulates the reaction
- vertical bar: the reaction types is one of Inhibition, Unknown inhibition, Negative influence, Unknown negative influence
- arrow: the remaining reaction types
The direction of the arrow/position of the vertical bar determines the reactant/product role of the target. If the arrow goes from left to right or the vertical bar is on the right hand side of the head, the target is a product and otherwise it is a reactant. This does not apply to the circle symbol since modulation is not directional.
Settings
The exploration plugin has several settings which can impact the exploration process. These settings can be accessed by clicking on the Settings button in the upper part of the plugin:
- Species types: the user can select which types of bioentities will be considered during the exploration. Changing this does not impact the existing exploration state. Thus, for this change to take effect, one needs to restart the exploration (either by clicking on the restart or Explore button)
- Locate on expansion: if checked, when a node is expanded, the newly shown nodes are located in the map
- Backtrack depth: If set, the backtracking procedure will go only given number of levels back
- Highlight by icon/surface: sets the way of how encountered entities are highlighted in the map