aMatReader: Importing adjacency matrices via Cytoscape Automation

Implementation

aMatReader is developed to handle a wide spectrum of adjacency matrix formats. To accommodate possible missing or reordered row and column names, we use an adjacency list of node indices as an intermediary data structure. Two separate arrays are used to store source and target node names, where the i^th name in the array refers to the node at index i in the adjacency list. Once the matrix has been translated, aMatReader makes a pass through the adjacency list and set edge attributes in the network.

One constraint of aMatReader is that the parser expects integer or floating point values. Any String, Boolean, or unrecognized values will be considered null and no edge will be created (and no warning will be generated).

There are two possible options for importing an adjacency matrix into a Cytoscape network. To create a new network from an adjacency matrix file, the caller can use the import Function. If the adjacency matrix defines edge attributes that should be added to an existing network, the extend Function should be used. This is especially useful because an adjacency matrix can only represent one type of edge attribute, and complex networks are often represented by multiple adjacency matrix files.

If a new network is being created (via the import Function, described in the Operation section below), all of the network nodes are created and named first. Then each non-null value in the matrix is used to create an edge. The edge attribute takes its name from the name of the matrix file that is being imported.

If a network is being extended (via the extend Function, described in the Operation section below), aMatReader attempts to match row and column names to existing nodes in the network. If no node exists with the given name, a new one is created. Creating edge attributes is handled similarly; an edge between the source and target node is added if it does not already exist, and then the attribute is set.

Some matrix formats add extra information to provide insight to the parser. Matrices produced by cCrepe and MATLAB optionally prefix column names with a period-delimited description of the weights specified by the matrix (e.g. “sim.score” or “q.value” in cCrepe). Additionally, comments can be included in files by inserting a hash symbol at the start of a line. Below is an example gene similarity table produced by MATLAB. More examples of supported format idiosyncrasies can be seen in the documentation provided on the Cytoscape App Store.

# With row and column names, the cell at (0, 0) is ignored
# PIPE delimited adjacency matrix, with column name prefix "distance."
Rows|distance.nodeA|distance.nodeB|distance.nodeC|...
nodeA|0|2.0|1.45|...
...

Listing 1. Sample adjacency matrix with confusing format. Pipe “|” delimited text file with comments and column name prefix.

Operation

aMatReader exposes two Functions⁵ via the Cytoscape CyREST API, import to create a new network and extend to add edge attributes to an existing network. If necessary, the caller specifies the network to be extended as part of the REST URL. The Function endpoints (Figure 2) enable users to manipulate network data as internal Cytoscape data, and are documented in the Apps: aMatReader section of the Swagger document available via Help → Automation → CyREST API.

Figure 2. Functions exposed by the aMatReader API, as documented in Swagger.

Both endpoints expect the same parameters within the JSON body of the request:

{
  “files”: [“list”, “of”, “paths”],
  “delimiter”: “TAB”,
  "undirected": false,
  "ignoreZeros": true,
  "interactionName": "interacts with",
  "rowNames": true,
  "columnNames": true,
  "removeColumnPrefix": true
}

The files parameter specifies a list of local file paths for matrix files, and is the only required parameter; all other parameters default to the values shown above. Files imported in the same REST call must have the same format and thus be importable with identical parameters. The caller can specify the matrix delimiter (as one of “PIPE”, “SPACE”, “TAB”, or “COMMA”), whether the matrix is symmetric and diagonal and should only import the upper triangle as undirected, whether or not to create edges for zero values (called ignoreZeros), edge interaction type (called interactionName). The payload can also define whether row and column names are present in the file (called rowNames and columnNames). The removeColumnPrefix parameter informs the parser to ignore a common prefix in column names, if it exists.

Note that the interaction type is only set for edges created by the import, and is not set for pre-existing edges in an extend call.

The aMatReader endpoints return a CIResponse⁶ according to Cytoscape Automation best practices. If the call succeeds, the CIResponse contains an import result object (as the data element); otherwise, it contains an explanation of the error (as the errors element):

{
  "data": {"newEdges": integer,
           "updatedEdges": integer},
  "errors": []
}

The newEdges value contains the number of edges created in the network, and the updatedEdges contains the number of edges that already existed and received new edge attribute(s).

If the delimiter is unrecognized or any of the matrix files cannot be found or fails to parse correctly, the errors[0].status element returns 404, and the remainder of the errors[0] element contains additional information.

In order to download and use aMatReader, ensure that you are running Cytoscape version 3.6.0 or later with at least 512MB of free memory to store the matrix before creating the edges.

Calling aMatReader Functions. To import files to a new network, the caller must send an HTTP POST request to /v1/aMatReader/import with a JSON payload object specifying the list of matrix files and any optional parameters listed above. To extend an existing network, the caller must also pass the networkSUID parameter as part of the URL (/v1/aMatReader/extend/{networkSUID}).

Note that the networkSUID must be an integer. The caller can determine a network’s SUID via the /v1/networks endpoint.

Example code is provided in R, Python and as a Bash curl, but can easily be adapted into any language that supports REST calls.

R

# Basic settings for cyREST
port.number = 1234
base.url = paste("http://localhost:", toString(port.number), "/v1", sep="")

# Send it to Cytoscape!
amatreader.url = paste(base.url, "aMatReader", "import", sep="/")
amatreader.args = list(files="path", delimiter="TAB", undirected=FALSE, ignoreZeros=TRUE, interactionName="correlates to", rowNames=TRUE, columnNames=TRUE, removeColumnPrefix=FALSE)
amatreader.JSON = toJSON(amatreader.args)
res <- PUT(url=amatreader.url, body=amatreader.JSON, encode="json")

Python

import requests, json
resp = requests.put("localhost:1234/v1/aMatReader/import", data=json.dumps(data))
resp = resp.json()

Bash

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
  "files": [ \ 
     "string" \ 
   ], \ 
   "delimiter": "TAB", \ 
   "undirected": false, \ 
   "ignoreZeros": true, \ 
   "interactionName": "interacts with", \ 
   "rowNames": true, \ 
   "columnNames": true, \ 
   "removeColumnPrefix": true \
 }' 'http://localhost:1234/v1/aMatReader/import'

Future plans

aMatReader was designed with existing adjacency matrix exporters in mind, such as the igraph.Graph.Adjacency⁷ and pandas DataFrame⁸ objects. We will continue to improve aMatReader to handle more diverse matrix formats, including string matrices, and to provide a CyREST Function that returns the predicted parameters for importing a matrix file.