The MINERVA Platform: User’s manual
Table of contents
- MAIN VIEW
- FUNCTIONAL AREA
- INFORMATION BAR
User view refers to the visualization and functionalities accessed by users of the content hosted by your MINERVA instance.
The main view of the MINERVA Platform is summarized in the figure below.
Main components of this view are:
- DISPLAY AREA where the contents of the projects are visualized.
- FUNCTIONAL AREA (called left panel), allowing for advanced interaction with explored content.
- INFORMATION BAR containing additional overlay functions.
- PLUGINS / login-logout / ADMINISTRATOR PANEL allowing a user on upload of own plugin, log in/out to MINERVA and enter Administrator panel. Log in to MINERVA is possible also in Overlays tab or Info tab.
Accessing the project
Your instance of MINERVA platform can host many projects, which are uploaded by the administrators (see add project). Every project can be accessed by a dedicated web address.
Exploring the display area
The MINERVA Platform displays molecular interaction diagrams with their annotations and links to databases. Click on any element on the display area - element will be marked with color pin and its details will be displayed in the left panel.
Systems biology diagrams
MINERVA Platform visualises diagrams using three formats: SBGN-compliant, SBML and GPML. Read more about customising the content here. Especially for SBML format, it is worthwhile to customise the file before the upload to MINERVA in order to improve its visualization.
The content is visualized using Google Maps API or Open Layers Library (chosen on the project upload), and allows for similar pan-and-zoom functionalities. The content is interactive, the user can click on an element or an interaction to examine additional details, which are displayed in the left panel (functional area). More exploration tools are available via right click on the map. Moreover, the MINERVA Platform allows to color the map’s elements with glyphs provided by user (check section glyphs) and to precisely set the elements order (check section Z-Index). The map content is by default displayed in semantic zoom mode, which enhances map’s clarity. In that view, the compartments and the pathways areas are displayed in a particular order, regulated by the zoom level.
Semantic zoom is a default view of the map. It makes the compartments and pathways cover underlying elements on higher levels of zoom. This view is generated procedurally, directly from the uploaded content. MINERVA calculates which areas cover others, and assigns them to the appropriate zoom levels. Note: In the tab Overlays tab in the left panel (functional area), semantic zoom is activated via Pathways and compartments background. You can turn it off by changing the view on Network or Empty background. Find out more here: procedural generation of the semantic zoom.
Basic exploration tools
Right-click in the display area invokes a contextual menu (image below). The menu allows to:
- visualise the structures of proteins (MolArt),
- add a comment on a map,
- download as map or image currently displayed map’s area,
- download the particularly selected area as map or image.
To open MolArt window you need to click on the UniProt ID of the protein in the context menu. There will be open a new window, which displays in the left panel the molecule’s sequence, relevant annotations (including variation data) and the list of available structures (either experimental or predicted) for a given molecule. The right panel of MolArt window shows selected 3D structure over which any of the sequence annotations can be color-overlaid. See image below:
This functionality allows to comment on contents in the display area. Clicking on Add comment invokes a form that can be filled out by the user and send to the administrators of the project (see below left). Type field is a drop-down menu, listing the elements nearby to the click location. This allows to choose and attach the comment to a particular element or interaction (see below middle). If particular type is selected, its name is displayed (see below right). The field Pinned controls whether the comment will be visible in the map.
If the comment is placed in a submap, the main map shows its bubble also. It is placed on the anchor to the submap.
Click on the comment bubble displays details of annotated element and the text of the comment (see below). The mail is not disclosed, only project and platform administrators have access to it (see Administrator’s manual - Comments).
Export current view as image
This option creates an image of the map currently displayed on your screen. Export to vector and raster graphics is supported, allowing to modify and enhance the downloaded image.
Export current view as map
This option allows to produces a file acceptable by either CellDesigner, GPML, pure SBGN or SBML editors. The exported file contains the editable fragment of your display area, together with its contents and layout. Importantly, in the case of CellDesigner or SBML export, all additional annotations provided by MINERVA platform are downloaded as well.
Clicking the Select mode enables the functionality supported by Google Maps API and Open Layers Library. It allows to select an arbitrary shape in the display area.
To select the area:
choose Select mode from context menu. Then, click on the map - this is the start point of your selected area. Mark all of your polygon’s points. To close the polygon choose the end point of the polygon the same as the start point, or just double click on your end point.
Click on the selected area allows to remove the selection or download it in various formats, either as a map or an image.
Export as image produces a rectangular image containing the selection. Export to vector and raster graphics is supported, allowing to modify and enhance the downloaded image.
Export as map produces a file acceptable by either CellDesigner, GPML, pure SBGN or SBML editors, containing the editable fragment of the selected display area, together with its contents and layout. Importantly, in the case of CellDesigner or SBML export, all additional annotations provided by MINERVA platform are downloaded as well.
The left panel from the display area is the functional area. It shows information about selected elements or interactions, allows to query the content, generate custom overlays and browse the submaps.
Search tab allows to search for a particular elements or interactions in the displayed map. Similar search results are merged (marked with the same number) and displayed on the map with color pins (see image below). In the left panel the search results are grouped by top map and submaps, with information about size of that group of x elements. Moreover, left panel displays details of each result.
Click on eye icon reveals detailed information on selected elements or interactions, such as: element’s compartment and full name, symbols, annotations and their source (automatic or manual by curator).
Click on the submap name opens the submap with the search results pins displayed.
There are four subtabs available in the Search tab, offering different scopes:
- CONTENT for regular search
- DRUG for drug target search
- CHEMICAL for chemical target search
- MiRNA for miRNA target search
Here you can search through the map content by simply typing in the element’s e.g.
water. Search will look for similar names and synonyms of the elements in the map, and display the results.
- Multiple search
If you search for more than one element separate the queries with a semicolon ‘;’ (e.g.
park7; sod). Search results for separate terms will be visible in separate tabs, and the pins on the map will have different colors (image below).
The button shows/hides particular information as per Search panel options setting in MINERVA configuration.
When multiple search returns common targets these are highlighted with a special icon . The same icon indicates search results that are found in a submap, see more in Submaps.
You can search directly for an identifier of element. The query looks like
annotator's name:identifiere.g. hgnc:14581.
You can also search for an identifier of a reaction (visible in the left panel after clicking on a particular reaction). To do this, you need to add
reaction:prefix to the searched term, e.g. for a reaction with id re944 you will search for a term reaction:re944.
If this box is ticked, only terms exactly matching the query will be returned. For large networks or broad queries the search results may be capped to ensure the performance of the system. The limit of displaying search results can be configured by the administrator (see configuration).
- “Reversed” search
Click on the pin to display the element’s popup, which allows to view drugs, chemicals or miRNA interacting with the protein.
Click to show all drugs for this element(image below) search for the interacting elements and list them, see image below on the right. Click on any of the “reversed” search results - its details will be displayed in the left panel, image below.
Note that search results of drugs have different shape of pin than regular search results pin.
Click on any reaction to highlight it. In the left panel you will find details of the reactants. The reaction kinetics, if available, is displayed in the popup dialog after clicking on highlighted reaction.
Direct link search
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:
is a link executing the search for a given search query in the default project of your MINERVA instance. For example, an address
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) search
The Drug scope works as follows: Drug subtab under the Search tab allows to look for known drugs or their brand names and display their targets in the map. The pins have specific shape , different than the results of other search scopes.
- Search field: type your search query here, separating multiple drug names or their brand names with a semicolon ‘;’.
DrugBank (click) and ChEMBL (click) will be queried for known targets to be displayed in the map.
- Drug description, synonyms and all known targets will be displayed in the left panel.
Chemical (target) search
The Chemical scope works as follows: Chemical subtab under the Search tab allows to look for known chemicals or their synonyms and display their targets in the map. The pins have specific shape , different than the results of other search scopes.
- Search field: type your search query here, separating multiple chemical names or their synonyms with a semicolon ‘;’.
Clinical Toxicogenomics Database (click) will be queried for known targets to be displayed in the map.
- Chemical description, synonyms and all known targets will be displayed in the left panel.
miRNA (target) search
The microRNA scope works as follows: MiRNA subtab under the Search tab allows to look for miRNAs and display their targets in the map. The pins have specific shape , different than the results of other search scopes.
- Search field: type your search query here, separating multiple miRNAs with a semicolon ‘;’. miRTarBase (click) will be queried for known targets to be displayed in the map. Use only mature sequence IDs according to miRBase (click), e.g. hsa-miR-125a-3p.
- Known targets will be displayed in the left panel.
Overlays tab allows to display or generate custom coloring of elements and interactions in the map. It is composed of three sections, image below:
- general overlays,
- user-provided overlays (which becomes visible upon login).
Pathway and compartments is default background for the maps. Main feature of this view is Semantic zoom which improves map’s clarity. In this particular view, on the high level of zoom bigger areas overlay smaller ones, and the contents of complexes are masked.
Network displays colored network structure.
Empty shows only network structure, no coloring. It is recommended for data display.
General and user-provided overlays
Data overlays provide additional information about elements and interactions. Data overlays can be general or user-provided:
General overlays are accessible for every user viewing the content.
User-provided overlays are your private overlays, uploaded and available only for you.
Also, there are two types of data overlays (more details in the next section):
Generic overlay displays a coloring on the map according to data set of indicated molecules (e.g. differentially expressed genes).
Genetic variant overlay displays a coloring for the genes, for which the variants are present. It also enables the genome browser popup, displaying the position of a variant in the sequence of the corresponding gene.
In the left panel there are following feature for overlays:
View the overlay - tick the chosen boxes to display multiple overlays - choosing that option automatically turns the background to Empty to emphasize the overlay’s colors. Also, in the bottom left corner the legend for each overlay will be displayed.
Data column contains buttons, where applicable, allowing to download the dataset used to generate the overlay.
Edit - change name, description or remove overlay.
Description display - hover over the overlay name/view to display a short description of the dataset, if provided on upload.
Overlays are also visible in the popup window, displayed after clicking on the element’s pin, showing the value and the sign marked on the horizontal color bars. The popup contains information about Interacting drugs, chemicals and MicroRNA with selected element, available after ticking check box
Click to show all drugs for this element.
Upload of user-provided overlay data
User-provided overlays are the overlays uploaded by and visible to the currently logged user. Available overlays can be reordered by name or number.
Adding a new overlay is available via Add overlay button, which opens the dialog window (image below, marked red).
Note: Refresh button (image below, marked yellow) allows to refresh the overlays list. It is necessary in case an overlay is added via API during viewing a map in a browser.
Add overlay button invoking the dialog window with the following components (image above).
Name field for the new overlay.
Description of the dataset.
- Type field, which depends on the header of uploaded file - TYPE field. (Data overlay file syntax is explained fully further in the paragraph.)
After choosing a file, the dropdown list TYPE switches automatically between GENERIC / GENETIC_VARIANT as MINERVA recognizes file’s header. This happens because genetic variant overlays need to have a specific header field.
- GENERIC overlay displays a coloring on the map according to data set of indicated molecules (e.g. differentially expressed genes).
- GENETIC VARIANT overlay displays a coloring for the genes, for which the variants are present. It also enables the genome browser popup, displaying the position of a variant in the sequence of the corresponding gene. To upload and correctly display the genomics information your instance must contain reference genomes, uploaded by the administrator. Also, the Organism id (e.g. 9606) must be provided for the project, and reference genomes uploaded on MINERVA instance must include its type.
Upload file - Choose file button to select a file with overlay data.
List of elements field - instead of providing an overlay file, the user can provide a list of named elements to highlight in the map (e.g. list of genes). Choose TYPE corresponding to the content of your list: GENERIC for named elements; GENETIC_VARIANT for the variants.
Upload button to generate the user-define.
Fill the above fields and click UPLOAD button. Your overlay will become available in the left panel. You will be notified by email when your overlay is ready. The email will also contain the list of elements in your dataset and the number of elements they colored in the map.
Important reminder: The number of available overlays is common for all projects hosted on your MINERVA instance. If a user is registered in a number of projects and uploads custom datasets in all of them, the global number of available custom overlays will be reduced with each uploaded overlay.
Note: The genetic variant overlays additionally contain the genome browser in the popup window (see below):
The genome browser allows to view the position of a variant in the sequence of the corresponding gene. Image below presents just the gene browser:
Reference genome contains reference genomes uploaded into the instance by admin (e.g. hg19).
Scale of base pairs display, changed by slide.
Location indicates currently viewed position in the genome.
Genes mapping display the reference genes locus provided to the instance by admin, see more in add new genomes.
User-provided overlay displays the variants from uploaded file.
Data overlay files must have correct syntax, so MINERVA could color the map as needed. To learn more about uploading data sets check out the example 3 - custom data upload.
Basic GENERIC format
Download here the example of basic generic overlay and read its description below.
The file in a basic format is a two-column, tab-separated text file, with the columns Name and Value. Please note that the basic format does not have a header.
Name column contains the names of elements to be colored.
Value column contains the values normalized to [-1, 1] range.
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 GENERIC format
Download here the example of advanced generic overlay and read its description below.
The advanced format allows for by identifier matching, custom color assignment and coloring of interactions. The uploaded dataset has two sections - the header and the body.
The header lines start with
#and contain the following elements:
# VERSION=1.0- a version of this overlay file.
# NAME=my-overlay- a name that will be automatically assigned upon upload.
# DESCRIPTION=The details of my-overlay- a description that will be automatically assigned upon upload.
The body is a table with a set of allowed columns. See the list of all available columns here.
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 element_identifier and line_width for elements, and leaving blank fields in name for interactions.
All data columns work as an intersection to narrow down the coloring. Example: if your map contains only protein SNCA, and you put RNA SNCA, there will be no coloring even though the SNCA is displayed in the map.
GENETIC VARIANT format
Download here the example of genetic overlay and read its description below.
It is a particular type of advanced format, it contains the header and the body, see below:
- The header lines start with ‘#’ and can contain the following elements:
Genome type -
#GENOME_TYPE=UCSC- type of reference genome being used (e.g. UCSC)
Genome version -
#GENOME_VERSION=xyz- version of reference genome being used (e.g. hg19)
- The body is a table with a set of allowed columns. Click here to see the list of all available columns.
The Submaps tab summarizes all the submaps linked to the main map of this project hosted by your MINERVA instance. See Administrator manual - advanced upload 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 at least one submap. The tab contains names of the submaps, to show maps’ description, if one is provided, and magnifying glass buttons to display them. The submaps show as a pop-up window on top of the main map (image below).
The submaps are synchronized with respect to search queries and displaying data overlays.
This means that search results and search pins will be visible in the main map and the active submaps (image below).
Also, on the main map there is an icon informing that search results hit submap (image below).
The Info tab has two components, displaying Project info and User data (for registered and logged users).
Displays name, version and the details of the map.
The Data section features the links to:
- Browse the publications supporting the map. The Publication list dialogue allows to search for articles by title, author names or year. It contains links to interactions supported by particular articles. The list of the publications can be downloaded.
- Download the project’s source files.
- Export the contents of the map (see below for more details).
- Open the MINERVA manual.
- The information about the disease type (Mesh id).
- The information about the organism type (Taxonomy id).
The Description section contains information from the CellDesigner file from Model Notes and Model Description (if provided).
The Export page contains three tabs (Elements, Network and Graphics), allowing to download the map contents in different formats.
- ELEMENTS tab allows to download the list of elements in the map as a text file. Available filters include:
- Type - filters elements by the element type (e.g. Protein, RNA)
- (sub)map - filters elements by the (sub)map
- Column - selects particular details, including:
- Id - identifier of the element in the MINERVA system
- Name - name of the element
- Map id - identifier of the (sub)network containing this element
- Type - type of element
- Complex id - if applicable, id of the complex containing this element
- Compartment - the smallest compartment/pathway containing the element
- Element external id - corresponding source file e.g. CellDesigner ID
- Annotations - filters the annotations of elements in the downloaded file; by default all annotation types are considered. Fields highlighted in green are non-empty annotation sources
- Included/excluded compartment/pathways - filters the elements by compartments/pathways they are in; by default all compartments are considered as “included”, none as “excluded”
- NETWORK tab allows to narrow down and download the interactions in the map. The exported network file is not a fixed-column table. As interactions are in fact hyper-edges, each line may contain different number of reactants, products and identifiers. Available filters include:
- Element type - filters the nodes of exported interactions by the element type
- Reaction type - filters interactions by type
- (sub)map - filters elements by the (sub)map
- Column - selects particular columns, including:
- Elements - information about reactants, products and reaction modifiers
- Reaction external id - reaction identifier from the source file e.g. CellDesigner ID
- Map id - identifier of the (sub)network containing this element
- Annotations - filters the annotations of elements and interactions in the downloaded file; by default all annotation types are considered. Green highlighted fields are non empty annotation sources
- Included/excluded compartment/pathways - filters the elements by compartments they are in; by default all compartments are considered as “included”, none as “excluded”
- GRAPHICS tab allows to download graphics of the (Sub)map in one of the Format: PNG image, PDF and SVG image. Also, user can provide size of graphics in Image size.
If registered, users can login here, or request for an account from the administrators of this MINERVA instance. Platform administrators can register new users (see Administrator’s manual - USERS) and configure Request an account functionality (see Administrator’s 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 Overlays).
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.
This button invokes a static image associated with the displayed content. It may be a graphics helping to understand the underlying map, 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:
- another static image to be displayed next
- a defined area in the displayed content
- a set of elements or interactions
If this checkbox is checked, the comments provided by users with Pinned option set to Yes will become visible in the display area (see Add comment).
If this checkbox is checked, the legend describing element and interaction types will be displayed.
Plugins allow for creating client-side custom visualizations, independent from the core functionalities of MINERVA. After clicking on the plugin icon a popup window becomes available (see images below).
Example plugin: you can upload below URL into the plugin dialog to find out more:
Afterwards, a plugin panel becomes available on the right (see image below). To close that panel, click the plugin icon to open the window and click Unload button.
Please find below the list of available plugins, click at plugin’s name for its details.
|Name of the plugin||Address URL and the short description of the plugin|
|Disease variants associations||Provide the information about genes associated with the given disease in the context of the selected disease map.
|Drug reactions||Explore the adverse reactions of the drugs which are interacting with the presented entities in a disease map.
|Exploration||Enhance the visualization and exploration of molecular interaction in the map.
|Guide||Provide the introductory guide through various aspects of the MINERVA platform.
|GSEA||Calculate the enrichment of the elements from the selected overlay in the pathway.