Identifier Mapping in Cytoscape

Inferring the data source

From within Cytoscape, a user initiates an ID mapping operation by right-clicking on the header of a column containing identifiers in the Table Panel. Based on the specified species a list of data sources is provided to the user. In the most common cases the type of identifier can be guessed by idmapper based on the its format and is presented as the default selection. Table 1 shows the supported data sources and example identifier formats. The app looks at the first ten entries and chooses the source that matches corresponding regular expressions provided by BridgeDb. If there is no match (or if more than one system is matched), then it simply chooses first option in the list as the default selection.

Cytoscape tasks

There are two different tasks supported by the idmapper app. ColumnMappingTask is activated by the right-click mouse event on a table header. It infers the current table and column from the information that comes from the mouse event, triggering a dialog (see GUI use case) that collects the information needed to make a call to BridgeDb web services. Please refer to the BridgeDb project for details about their services and sources³. In order to support automation, we added MapColumnCommandTask as an analog that is exposed specifically for Commands and CyREST access. These tasks eventually result in the same algorithms being invoked.

Cytoscape graphical user interface (GUI)

The idmapper app provides the same basic functionality of the BridgeDb app with less fuss. Users do not have to install it, launch it, make configuration decisions or think about which database they are accessing. The app comes bundled with every Cytoscape release. As such its usage in Cytoscape via the interactive GUI (graphical user interface) is documented in the Cytoscape manual: http://manual.cytoscape.org/en/stable/Node_and_Edge_Column_Data.html#mapping-identifiers.

To map an identifier from one source to another, right click on the column header of your identifier. Select the option to Map Column to bring up the idmapper dialog (Figure 1).

The idmapper dialog presents a few choices the user can override before performing ID mapping. The default Species is determined by the previous selection made by the user per network, providing a persistant behavior across mulitple searches. The available choices for the identifier data sources are determined by the species. The Map from data source is automatically selected based on an inspection of the first ten identifiers found in the column clicked on by the user. This can be overridden by the pull down menu. The To data source must be selected by the user; Ensembl is presented by default. Finally, the Force single checkbox offers to simplify the results of ID mapping by ignoring one-to-many cases and only keeping the first result (arbitrarily determined by the BridgeDb web service result). If the option is off, a list of results will appear in the column. This can easily be overridden by clicking the toggled checkbox. The result of the mapping is appended to the node table in a column named after the target data source, e.g., "Ensembl". If a column by that name already exists, a parenthesized number is appended to the name to ensure it is unique, e.g., "Ensembl(1)".

Cytoscape command line interface

The command interface does not use the same tasks as the GUI. In the GUI use case, the app knows the current context of where the command was activated, i.e., the network, table and column. This information must explicitly be provided as paramaters to the command interface to perform the same operation. Thus, in addition to species, mapFrom, mapTo and forceSingle, the command line operation of idmapper also requires networkName, table and columnName (see next section for more details).

Cytoscape automation

In the scripting environment, idmapper provides all of its functionality in a single call (Figure 2). This means that identifier mapping can be incorporated into Cytoscape automation workflows with a single additional command. The scripting version of the command includes extra parameter for columnName, networkName and table, which are implicit in the GUI version from the location of the mouse event.

The map column function takes the following parameters:

Figure 2. Swagger documented function.

The functionality of idmapper is contained in this single function: map column.

With Cytoscape running, the map column function can be called from any scripting environment or programming language that supports REST calls. In the case of R and Python scripts, there are dedicated packages to make this even easier. The RCy3 package wraps this command in an R function called mapTableColumn to conform to other table functions (https://www.bioconductor.org/packages/release/bioc/html/RCy3.html). The py2cytoscape library similarly provides this command as a python function, cyclient.idmapper.map_column (https://github.com/cytoscape/py2cytoscape). The advantage of using one of these dedicated packages is having more concise syntax and language-specific conventions. In RCy3, for example, the custom mapTableColumn function simplifies the call, conforms to other RCy3 functions and returns a dataframe with the map.from and map.to columns, while the generic commandsPOST function relies on the composition of a command string using the idmapper parameters defined in Figure 2:

(RCy3 generic): commandsPOST(paste('idmapper map column,
                        columnName="name",  forceSingle="true", 
                        mapFrom="Ensembl",  mapTo="Entrez Gene", 
                        species="Human",  table="node",  sep=" '))

(RCy3 custom): mapTableColumn(column="name",  species="Human", 
                map.from="Ensembl",  map.to="Entrez  Gene")

A sample script demonstrates how to map identifiers via RCy3, covering the most common use cases (https://github.com/cytoscape/RCy3/blob/master/vignettes/Identifier-mapping.Rmd).

Case 1: Species-specific considerations

The Yeast Perturbation sample network provided with Cytoscape can be loaded from the Starter Panel and provides gene identifiers of the form “YDL194W”. These are actually Ensembl-supported identifiers for Yeast, distinct from the typical “ENSXXXG00000123456” form as presented in Table 1. This presents a special case that users will need to be aware of when selecting species and source database or mapFrom in the GUI. (Ensembl has special cases for Yeast, Worm and Fly identifiers in addtition to the standard terms that start with ENS.) In terms of automation, you could generate a new column of Entrez Gene IDs in this network with these calls:

(RCy3): mapTableColumn(column="name", species="Yeast", 
                map.from="Ensembl", map.to="Entrez Gene")

(py2cytoscape): cyclient.idmapper.map_column(source_column="name", species="Yeast", 
                source_selection="Ensembl", target_selection="Entrez Gene")

Case 2: From proteins to genes

When working with protein interaction networks, for example those from the STRING database (see http://apps.cytoscape.org/apps/stringapp), you may want to translate protein identifiers (e.g., Uniprot-TrEMBL) to gene identifiers. The idmapper app supports this case as well, but one should be aware of the assumptions involved when making this translation. Since most genes encode for many proteins, you may have many-to-one mappings in your results. For all human networks imported from STRING using the StringApp⁵, the following commands will perform an ID mapping from Uniprot-TrEMBL (proteins) to Ensembl (genes):

(RCy3): mapTableColumn(column="canonical name", species="Human",
                map.from="Uniprot–TrEMBL", map.to="Ensembl")
                
(py2cytoscape): cyclient.idmapper.map_column(source_column="canonical name",
                species="Human", source_selection="Uniprot–TrEMBL",
                target_selection="Ensembl")

Case 3: Identifiers and symbols

In contrast to gene names and symbols, identifiers provide a more reliable means of specifying a particular gene. All data integration should be performed using identifiers as keys. Nevertheless, names and symbols play an important role in making results easier to read and understand. The idmapper app is primarily concerned with identifiers. However, relying on a subset of commonly used sources from BridgeDb (Table 1) it does provide one exception. HGNC symbols, when used properly, can serve as identifiers in ID mapping and more generally can be added when starting from any other human ID source:

(RCy3): mapTableColumn(column="canonical name", species="Human", 
                map.from="Ensembl", map.to="HGNC")
(py2cytoscape): cyclient.idmapper.map_column(source_column="canonical name", 
                species="Human", source_selection="Ensembl",
                target_selection="HGNC")