This is a previous version of the manual » v16.0 || Go to


The MINERVA Platform: User’s manual

Table of contents



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

You can also see the brief summary of this page in the MINERVA Quick Reference Guide or you can follow the guide.


MAIN VIEW

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

Main

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 Pin and its details will be displayed in the left panel.

Main


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

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.

Right click menu


Open MolArt

MolArt (MOLeculAR structure annoTator) is a JavaScript tool and library. It visualizes sequence-related annotations over available experimental or predicted structures (MolArt documentation is available here). MolArt is active only for the protein annotated with UniProt ID (image below left). The right image below displays context menu for the element without UniProt annotation.

MolArtMolArt1

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:

MolArt


Add comment

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.

Comment

After sending the comment by clicking on Send button, check the box Comments located in Information bar to display comments bubbles on the map (image below).

Pinning comment

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

Pinning comment


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.

Pinning comment


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.

Pinning comment


Select mode

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.

Select mode

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.

Select mode

  • 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.

Back to top


FUNCTIONAL AREA

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

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 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.

Search


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


Content search

Here you can search through the map content by simply typing in the element’s e.g. park7, 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 Reveal button 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 Reveal button. The same icon indicates search results that are found in a submap, see more in Submaps.

Search

  • Identifier search
    You can search directly for an identifier of element. The query looks like annotator's name:identifier e.g. hgnc:14581.

  • Find reaction
    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.

  • Perfect match
    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).

SearchSearch


  • “Reversed” search
    Click on the pin to display the element’s popup, which allows to view drugs, chemicals or miRNA interacting with the protein.
    Button Click to show all drugs for this element (image below) search for the interacting elements and list them, see image below on the right. Reversed searchReversed search 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. Reversed search


  • Reaction kinetics
    Click on any reaction to highlight it. In the left panel you will find details of the reactants. Reaction dialog The reaction kinetics, if available, is displayed in the popup dialog after clicking on highlighted reaction.
    Reaction kinetics

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

      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'


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 Drug icon, 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.


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 Chemical icon, 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.


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 miRNA icon, 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.
Back to top


Overlays tab

Overlays tab allows to display or generate custom coloring of elements and interactions in the map. It is composed of three sections, image below:

  • backgrounds,
  • general overlays,
  • user-provided overlays (which becomes visible upon login).

Overlays tab


Backgrounds

  • 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.

Background1 Background2 Background3


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. General overlay

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.

Overlays main


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.

User-provided overlays

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.

  • (Optional) if a map is displayed using Google Maps API engine, Google Maps API Terms of Use checkbox will appear.

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

Genetic variant browser


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: Genetic variant browser

  • Reference genome contains reference genomes uploaded into the instance by admin (e.g. hg19).

  • Scale of base pairs display, changed by Eye icon 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 - # VERSION=1.0 - a version of this overlay file.

    • Name - # NAME=my-overlay - a name that will be automatically assigned upon upload.

    • Description - # 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:

    • Type - #TYPE=GENETIC_VARIANT

    • 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.
Back to top


Submaps tab

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, + icon 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).

Submaps

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 multi icon informing that search results hit submap (image below).

Submaps

Back to top


Info tab

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


Project info

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


Export

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.


User data

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

Back to top


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

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 Add comment).

Legend

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


PLUGINS

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


Plugins icon

Plugins dialog
The user can choose any of the plugins that are available on the MINERVA platform, uploaded on the instance by the admin. Also, in the URL field one can supply a URL to the plugin, written in JavaScript. To learn how to write your own plugins, visit the “Plugin starter kit” repository.

Example plugin: you can upload below URL into the plugin dialog to find out more:
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, click the plugin icon to open the window and click Unload button.

Plugins panel


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.
https://minerva-dev.lcsb.uni.lu/plugins/disease-associations/plugin.js
Drug reactions Explore the adverse reactions of the drugs which are interacting with the presented entities in a disease map.
https://minerva-dev.lcsb.uni.lu/plugins/drug-reactions/plugin.js
Exploration Enhance the visualization and exploration of molecular interaction in the map.
https://minerva-dev.lcsb.uni.lu/plugins/exploration/plugin.js
Guide Provide the introductory guide through various aspects of the MINERVA platform.
https://minerva-dev.lcsb.uni.lu/plugins/guide/plugin.js
GSEA Calculate the enrichment of the elements from the selected overlay in the pathway.
https://minerva-dev.lcsb.uni.lu/plugins/gsea/plugin.js
Back to top