MINERVA v12
Manual

MINERVA platform: User’s manual#

User view refers to the visualization and functionalities accessed by users of the content hosted by your MINERVA instance.

You can also see the summary of this page in the MINERVA Quick Reference Guide.

Main view#

The main view of the MINERVA platform is summarized in the figure below.

Main{:width=“800px”}

Main components of this view are

Accessing the project#

Your instance of MINERVA platform can host many projects, which are uploaded via the administrator view (see Admin manual - Add project). They are accessed by a provided, dedicated web address.

Exploring the display area#

The content is visualized using Google Maps API or Open Layers Library (depending on user preferences). It allows similar pan and zoom functionalities. The content is interactive, the user can click on an element or interaction to examine additional details displayed in the left panel (functional area).

The content is by default displayed in a semantic zoom mode, where compartments and areas in the submitted file cover underlying elements on higher levels of zoom. This view is generated procedurally, directly from the uploaded content - the layouts of the CellDesigner file. MINERVA platform calculates coverage of bigger areas by smaller, and assigns them to appropriate zoom levels. For more details see Section Content curation. You can turn off the semantic zoom view by going to the Overlays tab in the left panel (functional area), and changing the view to Network (see also Section Overlays tab).

Basic exploration tools#

Right-click in the display area invokes a contextual menu (see below), which allows to annotate, select or download displayed area and also visualize the proteins’ structure.

Annotating{:width=“400px”}

Add comment#

This functionality allows to annotate contents in the display area. Clicking the Add comment button invokes a form that can be filled out by the user and sent to the administrators of the project. The field Pinned controls, whether the comment will be visible in the map (see below, left).

Pinned comment{:width=“800px”}

Type field is a drop-down menu, listing elements nearby to the click location. This allows to choose and attach the comment to a particular element or interaction (see above, right).

After sending, and if the field Pinned was set to Yes, the comment becomes visible in the display area, as shown below, to the left (after checking the Comments checkbox, see Comments).

Pinning{:width=“800px”}

Clicking on the comment bubble displays annotated element and the text of the comment (see above, right). Name and email are not disclosed, they will be accessible only to project and platform administrators (see Admin manual - Comments).

Select mode#

Clicking the Select mode enables the functionality supported by Google Maps API and Open Layers Library, allowing to select an arbitrary shape in the display area. The shape then can be downloaded in various formats, either as a map (.xml file) or as an image (see below).

Select mode{:width=“800px”}

Export as image#

This option creates an image of the part of map on your display area. Export to vector graphics is supported, allowing to modify and enhance the downloaded image.

Export as map#

This option allows to produces a file acceptable by either CellDesigner, pure SBGN or SBML editors containing the editable fragment of the selected display area. Importantly, in the case of CellDesigner export, all additional annotations provided by MINERVA platform are downloaded as well.

Open MolArt#

This option is active only for protein annotated with UniProt ID (see image below). MolArt (MOLeculAR structure annoTator) is a JavaScript tool and library. It assists users in the visualization of sequence-related annotations over available experimental or predicted structures (click here for MolArt documentation). Select mode{:width=“900px”}

MolArt displays in the left panel the molecule’s sequence, relevant annotations (including variation data) and list of available structures (either experimental or predicted) for given molecule. The right panel shows selected 3D structure over which any of the sequence annotations can be color-overlaid. See image below:

Select mode{:width=“900px”}

Content curation#

MINERVA framework handles SBGN-compliant format and SBML format - these two are externally curated content which MINERVA relies on. In case of SBML format it is essential to modify the file before the upload to MINERVA.

SBGN-compliant format#

MINERVA handles SBGN-compliant format produced either by CellDesigner (click) or SBGN editors, like SBGN-ED (click). Moreover, a number of additional functionalities of MINERVA operates on metadata that can be provided in the SBGN-compliant file itself. These are the following:

For explanation and examples on content curation and annotation, see Example 01 - CellDesigner file upload and annotation.

SBML format#

SBML file contains text information about elements, reactions and annotations. MINERVA takes annotations from SBML file as the inputs and transforms them to element/interaction annotations which can be displayed in the map. Use of SBOTerms is necessary to determine the type of elements/interactions. Moreover, SBOTerms must be inputted into the SBML file by user manually. Without updating SBML file on SBOTerms, all elements are displayed on map as small molecules and all reactions are represented by state transitions. See here the list of CellDesigner types matching SBOTerms.

For explanation on modifying SBML file, see Example 02 - SBML file modifications.

Functional area#

Functional area (the panel to the left from the display area) displays additional information about selected elements and interactions, allows to query the content, generate custom overlays and browse submaps.

Search tab#

Search tab allows to search for particular elements or interactions in the displayed map. Also, under this tab, the panel displays detailed information on selected elements or interactions, such as: full name of element, symbols annotations and their source (automatic or manual), see below:

Search{:width=“900px”}

There are four subtabs available in the Search tab, offering different scopes:

GENERIC#

The generic scope works as follows:

Select mode{:width=“800px”}

The reaction results are supported with information about reaction kinetics. It is available after clicking on chosen reaction in the display area. Select mode{:width=“600px”}

The search pins indicate hits in the display area. Similar search results are merged (marked with the same number). Also, for multiple elements search, the results have different color and shape icons (see image below) which are clickable and show information in popup window. In case of searching for different targets (i. e. generic target and drug target) the overlaying results are highlighted with different icon. The same icon on main map informs that searching results hit in the submap. See more in Submaps tab. Select mode{:width=“900px”}

Direct link to the elements in the display area is possible, as the search query can be provided within the web address of the displayed project. An address has to be manually constructed, directly into web browser, as below:

your.webserver.address/?search='search query'

is a link executing the search for a given search query in the default project of your MINERVA instance. For example, an address

your.webserver.address/?search=reaction:xyz123

will directly point to an interaction with id xyz123. Referring to a given project on your MINERVA instance requires additionally to pass the project identifier in the address, as shown below. Identifiers of projects are accessible using the Admin view.

your.webserver.address/?id='project id'&search='search query'

DRUG (target)#

The Drug scope works as follows. Drug subtab under the the Search tab allows to look for known drugs or their brand names and display their targets in the map. Targets will be marked by pins in the display area. Please, note that they have specific shape, different than the results of other search scopes.

CHEMICAL (target)#

The Chemical scope works as follows. Chemical subtab under the the Search tab allows to look for known chemicals or their synonyms and display their targets in the map. Targets will be marked by pins in the display area. Please, note that they have specific shape, different than the results of other search scopes.

MiRNA (target)#

The microRNA scope works as follows. MiRNA subtab under the the Search tab allows to look for miRNAs and display their targets in the map. Targets will be marked by pins in the display area. Please, note that they have specific shape, different than the results of other search scopes.

Overlays tab#

Overlays tab allows to display or generate custom coloring of elements and interactions in the map. It is composed of two sections - general overlays and user-provided overlays (which becomes visible upon login).

Overlays are also visible in the popup menu, with the value and the sign marked on the horizontal color bars (see figure below).

Overlays{:width=“800px”}

In the figure above:

Overlays2{:width=“900px”}

User-provided overlays part contains the following elements (above):

Upload user-provided overlay data#

Format

For examples of basic and advanced data upload, see Example 03 - Custom data upload by registered users. Description of the format follows below.

Basic format The basic format of file containing the uploaded data is two-column, tab-separated text file, with the columns Name and Value.

Basic format will match names of the elements provided in the Name column among the names of elements in a given network and for the matching ones will assign them colors: blue for negative values, red for positive values, with the saturation proportional to the value. The color range for the data upload is customizable in the admin panel.

Advanced format The advanced format allows for by identifier matching, custom color assignment and coloring of interactions. Advanced format foresees two parts of the uploaded dataset - header and body.

Header lines have to start with ‘#’. It can contain the following elements:

Body is a table with a following set of allowed columns:

The dataset for upload may be integrated and sparse, i.e. a document may contain all columns at once, and, where irrelevant, their content may be left blank. In other words, you can color interactions and elements in the same dataset, leaving blank fields in ReactionIdentifier and LineWidth for elements, and leaving blank fields in Name for interactions.

Procedure

After choosing the dataset to upload, pressing Upload button will invoke a comment, initiate generation and reduce the amount of available custom overlays (see below, left).

You will be notified by email when your overlay is ready. The email will also contain the list of elements in your dataset not found in the map.

Important reminder:

Submaps tab#

The Submaps tab summarizes all the submap networks uploaded together and linked to the main network of this project hosted by your MINERVA instance. See Admin manual - Source file to learn how to upload the submaps together with the main file. The tab Submaps is visible in the left panel, only if the map contains any submap.

The Submaps tab contains the Name column, and the column with the buttons invoking corresponding submaps.

Submaps{:width=“900px”}

The submaps show as a pop-up window on top of the main map, and are synchronized with respect to search queries and displaying mapped experimental data. This means that search results and search target bubbles will be visible in the main map and the displayed submaps. Similarly, coloring for overlays are mirrored in the submaps. Moreover, on the main map there is icon informing that search results hit submap. See figures below:

Submaps{:width=“800px”}

Submaps2{:width=“800px”}

Info tab#

The Info tab has two components, displaying Project info and User data (for registered and logged in users).

Project info#

Displays Name, Version and Description of the map.

The Data section features four links, allowing the user to:

The export page contains three tabs, allowing to download the hosted content in different formats.

User data#

It allows a registered user to type in their login and password, or to request for an account from the administrators of this MINERVA instance. Platform administrators can register new users (see Section User manager) and configure Request an account functionality (see Admin manual - Configuration)

After login, this panel displays information about the user. After the successful login the user gains the possibility to upload custom overlays (see Section Overlays).

Information bar#

Information bar is the topmost part of the user view, containing the Show overview button, Comment and Legend checkboxes and Clear button. The Clear button clears all search results currently shown in the display area. The remaining functionalities are detailed below.

Show overview#

This button invokes a static image associated with the displayed content. It may be a graphics facilitating the understanding of the underlying network, or any other visual cue that the content curator decided to present. The initial image displayed with the Show overview button can be linked to:

Detailed information on how to configure Show overview images display is provided in Admin manual - Source file.

Comments#

If this checkbox is checked, the comments provided by users with Pinned option set to Yes will become visible in the display area (see also Section Add comment).

Legend#

If this checkbox is checked, the legend describing element and interaction types will be displayed.

Admin login#

Options available in top left corner of the map. Padlock shape icon allowing administrator login or request for an account. To login as user go to Overlays or Info tab.

Plugins#

Plugins allow for creating client-side custom visualizations, independent from the core functionalities of MINERVA. After clicking on the plugin icon (see image below) a popup window becomes available. Plugins{:width=“600px”}

In the URL field one needs to supply a URL to the plugin, written in JavaScript. To learn how to write your own plugins, visit the “Plugin starter kit” repository here

For example, you can use a link for an example plugin:

https://raw.githubusercontent.com/davidhoksza/minerva-plugins-starter-kit/master/dist/plugin.js

Afterwards, a plugin panel becomes available on the right (see image below). To close that panel, go to plugin icon and click Unload button.

Plugins panel{:width=“800px”}

Exploration plugin#

Exploration plugin is a particular plugin providing 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:

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):

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:

  1. The root representing all instances of the the EOI anywhere in the map (including submaps).
  2. The (sub)maps in which the EOI connects by a reaction to any entity (of the selected type).
  3. The compartments in given (sub)map in which the EOI connects by a reaction to any entity (of the selected type).
  4. 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.

Exploration_Plugins1{:width=“900px”}

By left clicking any of the inner nodes, the corresponding subtree gets folded or unfolded making more space for the rest of the nodes.

Exploration_Plugins1Plugins2{:width=“900px”}

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.

Exploration_Plugins3{:width=“900px”}

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.

Exploration_Plugins4{:width=“900px”}

Additional features - right click#

If you right click on any entity pop up with menu shows, containing four options described below:

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.

Exploration_Plugins5{:width=“900px”}

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.

Exploration_Plugins6{:width=“900px”}

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.

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:

This documentation does not correspond to the latest official release of MINERVA (v21.0).
Page outline