MINERVA configuration: Administrator’s manual (version 12.2.x)

Table of contents

Administrator view

Administrator view refers to the set of functionalities for web-based management of the content and configuration of a MINERVA instance.

Login

Administrator view is accessible via the button with the lock icon in the upper left corner of the main view (see below).

Login view

Many projects (maps, networks) can be hosted in parallel on a single MINERVA instance. The users access the projects via direct hyperlinks. To manage these projects, the user with administrator’s rights to at least one of the projects can log as an administrator via lock icon. After successful login, you will have an access to the administrator panel to manage a MINERVA instance (see below).

Successful login


PROJECTS

This panel allows you to (1) add new projects (2) examine messages generated during the upload of the projects (3) edit and (4) remove them.

Projects view


Add project

The Add project button invokes a menu allowing you to upload your project and start its generation in the MINERVA platform.

Add project

File formats

Files uploaded to create a project on a MINERVA instance can be:

Single files of these types are uploaded via the Add project button. Advanced project structure can also be uploaded as a compressed file, as described in the Advanced format.

Fields of the Add project window

  • Upload file - Choose File invokes a file upload dialog. Available options and configurations of the source file are discussed in section Source file.

  • File format - choose a format of an uploading file: CellDesigner, SBGN or SBML.
    Note: Adding CellDesigner file or SBGN-format file automatically changes file format in the window. For an SBML file, the file format must be changed manually.

  • Map canvas type - choose Google Maps API or OpenLayers to display the map, if you choose Google Maps API you have to agree on Google Maps API Terms by ticking the checkbox.

  • ProjectId - a working name of the uploaded project on the MINERVA platform.

  • Project name - the name of the uploaded project displayed in the top left corner of the main view; your official name of the project.

  • Project Disease - the disease associated with the project, the code has to be a valid MeSH identifier, e.g.D010300. This is needed for chemical target search, see section chemical target.

  • Organism - the taxonomy id of the species, for which the map is primarily developed, e.g. 9606. This is needed to display genetic variants overlays.

  • Version - a text field displayed next to the name of your project in the User panel.

  • Notify email - e-mail address that should be used for project-related notifications.

  • Annotate model automatically - if this checkbox is checked, elements of the uploaded map will be automatically annotated using built in annotators. Behavior of the annotators can be configured by clicking the Advanced button (see section Configure automatic annotation).

  • Verify manual annotations - if this checkbox is checked, elements and interactions of the uploaded map will be scanned for existing annotations; if present, these existing annotations will be validated against a set of rules. Verification rules can be configured by clicking the Advanced button (see section Configure automatic verification).

  • Cache data - if this checkbox is checked, all hyperlinks in the project resolved by MIRIAM repository (e.g. cross-links to external bioinformatics databases) are resolved and cached.

  • Auto margin - if this checkbox is checked, the map will be drawn with equal amount of empty spaces around it.

  • Display as SBGN - if this checkbox is checked, the uploaded model will be displayed in SBGN format, instead of the default CellDesigner format.

  • Semantic zooming contains multiple overlays - tick the checkbox to display each semantic zoom level as a separate overlay in the General Overlays panel in the map. Find out more about semantic zoom here. This mode is primarily for testing purposes and we advise it should be unchecked by default.


Configure automatic annotation

The Advanced button, next to the Annotate model automatically checkbox under Add project button, invokes a dedicated configuration window (see below).

Configuration window

Clicking on each element type from the tree in the left panel, an annotator can be assigned in the right panel that will attempt to automatically retrieve information from external bioinformatics databases for each relevant element and annotate them.
Copy from button in the right panel copies annotators set from other objects we choose (see above image: GenericProtein will get the same annotators as Gene already has set).
Important note: Settings for lower hierarchy levels are overridden by settings for upper hierarchy levels. For instance, if no Ensembl annotation is selected for GenericProtein, but Protein selects Ensembl, GenericProtein will be automatically annotated with Ensembl as well.


There are a number annotators available, working either by name, or by annotation of an element.
By annotation refers to the MIRIAM identifiers in the <annotation> section of SBML and CellDesigner formats.
These annotators use specific identifiers, mentioned below, to retrieve additional information for elements. For instance, by UniProt annotation means that the annotator needs a valid UniProt identifier in the <annotation> section.
Note: SBGN files can be automatically annotated only by name as they have no <annotation> section.

BRENDA
- By annotation: BRENDA, UniProt.
- Retrieves all BRENDA codes for enzymatic activity of the element.

ChEBI
- By annotation: ChEBI or by name (ChEBI).
- retrieves full name and synonyms in the ChEBI ontology.

ENSEMBL
- by annotation: ENSEMBL.
- Retrieves symbol, full name, HGNC Symbol and identifier, Entrez Gene identifier.

Entrez Gene
- By annotation: Entrez Gene.
- Retrieves full name, symbol, synonyms, description, HGNC identifier and ENSEMBL identifier.

Gene Ontology
- By annotation: Gene Ontology.
- Retrieves full GO definition for this identifier.

HGNC
- By annotation: HGNC and by name (HGNC symbol).
- Retrieves full name, symbol, synonyms and UniProt identifier, RefSeq identifier, ENSEMBL identifier, Entrez Gene identifier.

Protein Data Bank
- By annotation: PDB, UniProt, HGNC, HGNC symbol and by name (HGNC symbol).
- Retrieves all relevant PDB structure identifiers. If HGNC symbol or identifier are used, it will also run the HGNC annotator.

STRING
- By annotation: STRING, UniProt.
- Retrieves all relevant STRING identifiers. If UniProt identifier is used, it will also run the UniProt annotator.

UniProt
- by annotation: UniProt.
- Retrieves HGNC symbol and Enzyme Nomenclature identifier.

Biocompendium
Warning! this annotation service is unstable due to maintenance
- by name, retrieves full name, symbols, description and identifiers: RefSeq, ENSEMBL, Entrez Gene identifier, HGNC symbol, KEGG, Reactome, PubMed and others


Configure automatic verification

The Advanced button, next to the Verify manual annotations checkbox under Add project button, invokes a dedicated configuration window (see below).

Configuration window

Clicking on each element or interaction type in the tree in the left panel, then:

- top right panels
A list of MIRIAM identifiers which are configured as valid. Elements or interactions in the uploaded model annotated with any identifier other than the valid list will raise a warning.

- bottom right panels
A list of MIRIAM identifiers which are configured as mandatory. If checkbox One of these miriam should be required is checked, elements or interactions in the uploaded model annotated without at least one identifier from mandatory list will raise a warning.

Save button: project generation

Clicking Save in the Add project window will start generation of the project. The status of the project in the Projects tab will update during the process. Also, you can use the Refresh button. Any warnings raised during the process will cause an exclamation mark icon to appear next to the project status. The list of warnings is extended gradually when the project upload advances, and you need to wait for the project completion to see the full list. You will receive an email notification after the generation is complete.

It may happen that the project generation will result in a failure. An icon will be displayed, and mouse over it will display the reason for failure. You will receive an email message with the brief description of the error.


To find out more, check example 1 - CellDesigner file upload and annotation.


Project status

Clicking on the exclamation mark icon (if present) next to the project status description, will display the list of warnings raised during the generation of this project (see below).

Warnings list

The list can also be downloaded as a tab-delimited text file. Types and identifiers of the elements and interactions are listed on the left side of column Content, while the nature of an error is provided on the right. Take a look at the list of possible errors and their explanations.


Edit project

This panel allows you to configure and manage the project. Functionalities are grouped in the following tabs (see below for an illustration):

  • General edit information about this project: canvas type, name, version, disease and organism type or notify email address
  • Overlays add or configure overlays for this map, both general and user-provided
  • Maps configure visuals for the main map and submaps
  • Users manage users’ access rights to this map
  • Comments manage user-provided comments for this map

Edit project - tab general


Overlays

This tab allows you to add new overlays and edit properties and ownership of existing overlays. You see here overlays that have been:

  • uploaded with the project, if it contains overlays already (see sections Add project and Source file)
    Important! Overlays named Pathways and compartments, Network and Empty allow for different ways of displaying the map’s content, and they have no data associated with them.
  • uploaded by the users (see section Upload user-provided overlay data)
  • uploaded by the administrators by Add overlay button in top left corner

Edit project - tab overlays

In this tab, besides Name and Description, the following columns are available:

  • Public - this checkbox makes the overlay available to any user
  • Default - this checkbox sets the default view of the map
  • Owner - the user having the access right to a given overlay. Dropdown menu allows to choose from existing users
      Important!
      Choosing the owner to be ‘N/A’ (top of the list) and checking the Public checkbox makes this overlay a General overlay, accessible for all users
  • Data - action buttons to download the associated dataset
  • Update - action buttons to save any changes in the configuration of the corresponding overlay
  • Remove - action buttons to remove the corresponding overlay


Maps

This tab lists all available maps (the main map and submaps) in the project, and allows to change default displaying options of the maps, see below.

Edit projects - tab maps The following columns are available:

  • Default center x and y sets the default center point of the (sub)map
  • Default zoom level set the default zoom level for this (sub)map
  • Update to save the changes


Users (of this map)

This tab lists all users of a MINERVA instance and allows to configure their access rights to this particular map. It contains the following columns of checkboxes:

  • Manage comments
  • Manage overlays
  • View project
  • Update button, to save changes Ticking a checkbox in a respective column for a given user assigns the corresponding privilege to them. Each change needs to be saved with the Update privileges button.

General users privileges are discussed in detail in the following section USERS.


Comments

This panel allows you to manage comments provided by users to the particular map (see section User manual - Comments).

The field Title is a hyperlink to a given comment in the map. In the following columns there are author of the comment, his email and the content. Pinned informs if the comment’s icon is visible on the map.
Users logged in as administrators have a possibility to delete a comment by pressing press the Remove button. The removed comment will no longer be visible among the pinned comments on the map, and its status will be updated in the Removed panel with comment in the brackets (see image below).

Edit project - tab comments


USERS

Registered users can be allowed to upload data overlays to maps hosted on a MINERVA instance, and to manage it. This panel allows you to Add (1) users, Configure LDAP authentication (2) and Edit (3) their privileges, or Remove(4) them. See image below:

USERS

Clicking on the Add user button invokes the window (see below) allowing to set login, password and personal details of a new user.
The panel to Edit allows to modify user data except the login field. Remove button removes this registered user from a MINERVA instance.

Add new user

The two next tabs in the window allow to configure the access rights and privileges of the user.

  • Global privileges concern all projects on a MINERVA instance.
    • Add project if checked, permits the user to add new projects (Add project button becomes visible).
    • Custom overlays field defines how many overlays can be created by a given user across all projects.
    • Manage configuration if checked, grants the access right to Configuration tab and permits to configure the parameters of MINERVA platform.
    • Manage genomes if checked, grants the right to access Genomes tab and manage a reference genomes for MINERVA.
    • Map management if checked, grants the right to access Map manager tab and manage existing projects.
    • User management if checked, grants the right to access the User manager tab and to manage users.
  • Project-specific privileges concern only the project, for which they are configured
    • Top row: Default privilege for a new project checkboxes - set up default privileges assigned to this user for any new project.
    • The list of available projects on a MINERVA instance, contains four columns:
      • ProjectId name of the project.
      • Manage comments if checked, grants access to the comments tab in Edit project and allows them to manage comments for this project.
      • Manage overlays if checked, grants the right to manage overlays of all users for this project.
      • View project if checked, grants the right to open the URL of this project, and makes it visible in the PROJECTS tab. Important for non-administrators, only this box should be selected.
        Important unchecking this box for the user anonymous makes this map inaccessible without login. Only registered users with proper privileges will be able to open the URL of this map.


CONFIGURATION

Configuration tab allows privileged users to configure global parameters of a MINERVA instance. Particular categories of configuration items are grouped in separate tabs (see image below).

Configuration tab

Global MINERVA configuration category are:

  • Email notification details
    • E-mail address - e-mail address used for sending notifications about the activity of a MINERVA instance - project uploads, comments, etc.
    • Email settings for requesting an account - the Info and Overlay tabs in the user interface allow to a Request for an account action, which will auto-compose an email with the message defined in Email content used for requesting an account to addressed to the e-mail, or e-mails (separated by a semicolon) provided in the field Email used for requesting an account.
    • E-mail server login, E-mail server password, IMAP server, SMTP port and SMTP server - configuration of your mail server for notification sending
  • Server configuration
    • Issue tracker - a tool to submit MINERVA issues.
    • Default project Id - the project that will be displayed by default under the root address of the platform (your.url/MapViewer/)
    • Domain allowed to connect via x-frame technology - the address of a website allowed to embed a MINERVA instance via x-frame technology
    • Google Analytics tracking ID used for statistics - provide here a valid Google Analytics ID to track user activity of a MINERVA instance
      • Max session inactivity time (in seconds) set the time after inactive session is expired
    • Path to store big files - location in the directory structure of a MINERVA instance to store big files
  • Legend and logo
    • Legend 1-4 image file - path in the directory structure of a MINERVA instance for displayed legend images
    • Logo description - the popup text that will be displayed upon mouse over your logo
    • Logo icon - the filename of your logo icon, displayed in the bottom-left corner of the main view; path in the directory or URL
    • Logo link (after click) - the website to which you will be redirected after clicking on the logo
    • Show reaction type when browsing map checkbox
    • URL of platform Terms of Use file
    • User manual file - location in the directory structure of a MINERVA instance for the user manual file
  • Point and click
    • Max distance for clicking on element (px) - the content visualized by MINERVA is interactive, and clicked elements or interactions are recognized by the vicinity of the click event. This parameter controls how close to an element or interaction, in pixels, you need to click to select them
    • Max number of results - sets the max number of search results, (similar elements are grouped into a single search result)
    • Max number of map zoom levels - sets the max size (of canvas) of the map, that can be uploaded to MINERVA.
  • Overlays
    • Opacity used when drawing data overlays (value between 0.0-1.0)
    • Overlay color for negative/positive values - sets the colors should be used for positive and negative values in basic overlays. Values close to zero have the lowest color saturation, values close to -1/1 have the highest color saturation
    • Overlay color for value=0
    • Overlay color when no values are defined - sets the color to use for coloring list of elements overlays
  • Default user privileges Sets default user privileges to manage comments, overlays and view projects for any project on a MINERVA instance.

  • Search panel options Defines which search results in the left panel will be expandable via plus/minus icon.

  • LDAP configuration
    • LDAP address - address of the machine where LDAP server is located
    • LDAP port - port on which LDAP is listening (by default it’s 389, for SSL connections usually it’s 636)
    • LDAP uses SSL - check to use SSL for LDAP connection
    • LDAP bind DN - Distinguished Name of the user account that should be used for LDAP connection (this user should be able to search/list accounts on LDAP server)
    • LDAP password - password for the LDAP bind DN
    • LDAP base DN - definition of the point from where a server will search for users
    • LDAP filter objectClass - this parameter allows to filter by objectClass type of LDAP entry; * value skips the filtering
    • LDAP first name attribute - which attribute in LDAP directory corresponds to “First name” of the user
    • LDAP last name attribute - which attribute in LDAP directory corresponds to “Last name” of the user
    • LDAP email attribute - which attribute in LDAP directory corresponds to the user email address
    • LDAP filter - when there are many accounts in LDAP administrators create groups of users that have access to specific systems, this filter allows to define LDAP filter that will limit set of accounts that can access minerva, empty string disable filtering
    • LDAP login (user id)

GENOMES

In this section an administrator can set up a reference genome for displaying genetic variant overlays and a genome browser in the map. Currently, MINERVA supports human genomes data from UCSC Genomics Institute. Available fields (see also image below):

  • Type informs about type of data, currently MINERVA supports UCSC format
  • Organism identifier of the organism of the added reference genome (e.g. 9606)
  • Version version of the added reference genome (e.g. hg19)
  • Progress of the upload
  • Source - url address of the genome data; sets up automatically after selecting Version, or user can paste own url address Note: the file must be in .2bit format
  • Edit/Remove buttons allows to edit the gene mapping and remove the genome from the instance

Important note:
The Taxonomy id (e.g. 9606) for Organism must be provided for the project, and reference genomes uploaded on a MINERVA instance must include its type. If Organism for the project is missing, the genome browser is not displayed in the overlay’s popup window.

Genomes main view


Add new genomes

In top left corner choose ADD GENOME button; the window pops up, as shown below:

Genomes add new

The window contains two tabs:

  • DETAILS - select new genome parameters as described above
  • GENE MAPPING - information about the gene loci in the genome, which are visualized on the blue axis in the genome browser. In the dialog window, provide the name of the data set and its url address. The name will be displayed in the genome browser (here: gene ref), see User manual - Overlays. The data must be provided in .bb format file. More details how to create .bb file.

Genomes gene mapping


PLUGINS

The plugin tab allows the administrator to add a public plugin to a MINERVA instance. These plugins will be displayed if in the Plugins menu in the map.
The Plugin tab is shown on the image below, it contains:

  • Name of the plugin
  • Version of the plugin
  • URL of the plugin
  • Remove the plugin from a MINERVA instance

Plugins main view


To add a new plugin, click Add plugin button, and paste the plugin url into the URL field and click Validate (see image below). The name and version fields are usually filled automatically from the plugin content. Click Save to add the plugin to a MINERVA instance. Add new plugin


Note: The administrator cannot add the same plugin twice to the MINERVA in the Administrator panel (the notification is displayed). But a user can upload an already exiting plugin via Plugins menu in the user’s view of a map.