Copycat Layout: Network layout alignment via Cytoscape Automation

Implementation

The Copycat endpoint operates on two Cytoscape network views, where a source view contains a source network, and a target view contains a target network. The source view acts as a reference for laying out nodes in the target view.

Copycat matches nodes in a source view to nodes in a target view based on a common node attribute value. For each match, it sets the target node’s X Location, Y Location and Z Location visual attributes to those of the source node. For each source node, the attribute value is found in a column of the source network table, and likewise for each target node. (While the columns themselves may be different, they are assumed to have the same type and meaning.)

Copycat implements a multi-pass algorithm where the first pass creates a map of source node attributes to source view coordinates. The second pass searches for target node attribute values in the source node attribute map and sets the target node’s view coordinates when an attribute match is found.

A node attribute value in the source column is considered to match a value in the target column if they are lexicographically equal. Note that a poor choice of mapping attributes can lead to confusing layouts. For example, when multiple target nodes match a single source node, all of the matching target nodes will be stacked on top of each other at the coordinates of the source node. Also, if a target node matches multiple source nodes, only the last encountered source mapping is used. To avoid visual confusion, avoid having multiple nodes associated with the same attribute value. (A good choice for a mapping attribute is the node’s name if each node has a different name. A bad choice could be a node’s in-degree if multiple nodes have the same in-degree.)

Optionally, Copycat sets the selected attribute for source nodes that aren’t mapped and for target nodes whose attributes aren’t found in the source node map, as shown in Figure 2. (The caller can subsequently query and act upon selected source and target nodes using other CyREST endpoints). Also optionally, unmapped target nodes are laid out in a grid in the top right portion of the target view.

Figure 2. Calling Copycat layout on a derived subnetwork with the selectUnmapped parameter set to false.

After the Copycat layout, the target network nodes have the same coordinates as the corresponding source network nodes. Because the node H in the source and nodes N and O in the target are unmatched, they are selected.

Operation

The Copycat Layout is accessible in the Cytoscape Desktop interface via the Layouts>Copycat Layout menu action, and is enabled if two or more networks exist in the network panel. For example, if the user has spent considerable time optimizing the layout of a network only to find that the data has changed, they can reload the data in the same Cytoscape session and use Copycat to copy the layout to the new network. To apply the layout, choose the source and target network views and their respective mapping columns (as defined in the Implementation section) and check boxes for selecting and gridding unmapped nodes if desired. The rest of this paper is intended for Cytoscape workflow programmers hoping to automate network view alignment via the Copycat layout algorithm.

Copycat exposes a single endpoint with both a Commands and Functions⁶ variant, each with similar parameters. While both variants perform the same layout, Commands are most conveniently used in conjunction with the Cytoscape scripting facilities, and Functions are most convenient for calls from scripting languages such as Python and R.

Generally, the caller specifies the Cytoscape views containing the source and target networks (called sourceViewSUID and targetViewSUID) and provides the name of the mapping column in the source network (called sourceColumn) and target network (called targetColumn). It can control whether unmapped nodes are selected (called selectUnmapped) or the unmapped nodes are laid out in a grid (called gridUnmapped).

Note that the caller can determine columns available for a network via a CyREST endpoint, such as /v1/networks/{networkId}/tables/defaultnode/columns.

Note that the source and target columns must both be either string types or integer types.

The Copycat endpoint returns a CIResponse⁷ according to Cytoscape Automation best practices. If the call succeeds, the CIResponse contains a layout result object (as the data element); otherwise, it contains an explanation of the error (as the errors element):

     {
       "data": {"mappedNodeCount": integer,
                "unmappedNodeCount": integer
       },
       "errors": []
     }

The mappedNodeCount value contains the number of target nodes successfully mapped, and the unmappedNodeCount contains the number of target nodes that did not correspond to a source node. To calculate the number of unmapped source nodes, the user can execute a GET request at /networks/{networkSUID}/nodes/selected and get the length of the list returned.

If either of the network views cannot be resolved by the given SUIDs or the mapping columns cannot be found in the node table of the source and target network, the errors[0].status element returns 404, and the remainder of the errors[0] element contains additional information.

To apply Copycat Layout to a network, you must be running Cytoscape version 3.6.0 or later with at least 512MB of free memory.

Copycat as a Function. The Functions endpoint is documented in a Swagger page in the Layouts section available via Help → Automation → CyREST API.

The caller must pass the SourceViewSUID and targetViewSUID parameters as part of the URL (/v1/apply/layouts/copycat/{sourceViewSUID}/{targetViewSUID}), and the remaining parameters in a JSON payload object:

     {
       “sourceColumn”: string, // defaults to “name”
       “targetColumn”: string, // defaults to “name”
       “selectUnmapped” : boolean,
       “gridUnmapped” : boolean
     }

Note that unlike other layout REST endpoints, the Copycat Function requires an HTTP PUT request because it consumes a JSON payload with extra parameters -- the other CyREST layout endpoints require GET requests with optional parameters directly in the URL.

Note that the sourceViewSUID and targetViewSUID must be either integers or the word “current” (meaning the view currently selected in Cytoscape). The caller can determine a network view’s SUID via a number of CyREST endpoints, including /v1/networks/views/currentNetworkView. The sourceViewSUID and targetViewSUID must reference different views.

Example code is provided in R, Python and as a Bash curl, but can easily be adapted into any language that supports REST calls. (Note that you must determine the values of sourceViewSUID and targetViewSUID independently ahead of these calls.)

R

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

# Send it to Cytoscape!
copycat.url = paste(base.url, "apply", "layouts", "copycat",
sourceViewSUID, targetViewSUID, sep="/")
copycat.args = list(sourceColumn="name", targetColumn="name",
selectUnmapped=TRUE)
copycat.JSON = toJSON(copycat.args)
res <- PUT(url=copycat.url, body=copycat.JSON, encode="json")

Python

import requests, json
resp = requests.put("localhost:1234/v1/apply/layouts/copycat/{}/{}".format(sourceViewSUID, 
targetViewSUID), data=json.dumps(data))
resp = resp.json()

Bash

curl -X PUT --header 'Content-Type: application/json' --header 'Accept:
application/json' -d '{ \
   "sourceColumn": "name", \
   "targetColumn": "name", \
   "selectUnmapped": true, \
   "gridUnmapped": false \
 }'
'http://localhost:1234/v1/apply/layouts/copycat/${sourceViewSUID}/${targetViewSUID}'

Copycat as a Command. The Commands version is documented in the Swagger page reachable from Cytoscape’s Help → Automation → CyREST Command API and can be found in the layouts section. Commands are executable via the Cytoscape Command Tool⁸ as well as the CyREST Commands API.

The caller must pass the sourceViewSUID and targetViewSUID as part of the payload object instead of the URL. They must be the name of a network (e.g., “galFiltered.sif”) instead of an SUID integer; Copycat will operate on the primary view for the network.

Note that like other layout Command REST endpoints, the Copycat Function requires an HTTP POST request.

Note that with the current CyREST Commands, it is difficult to query Cytoscape to find the name of a network. The caller must know the name in advance, likely as a result of creating or naming it by using a different Command prior to the Copycat call (e.g., /v1/commands/network/create empty).

Example code is provided in R, Python and as a Bash curl, but can easily be adapted into any language that supports REST calls. (Note that you must determine the values of sourceNetworkName and targetNetworkName independently ahead of these calls.)

R

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

# Send it to Cytoscape!
copycat.url = paste(base.url, "commands", "layout", "copycat", sep="/")
copycat.args = list(sourceNetwork="sourceNetworkName", sourceColumn="name", 
targetNetwork="targetNetworkName", targetColumn="name", selectUnmapped=TRUE)
copycat.JSON = toJSON(copycat.args)
res <- PUT(url=copycat.url, body=copycat.JSON, encode="json")

Python

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

Bash

curl -X POST --header 'Content-Type: application/json' --header 'Accept:application/json' -d '{\ 
   "gridUnmapped": "true", \ 
   "selectUnmapped": "true", \ 
   "sourceColumn": "name", \ 
   "sourceNetwork": "sourceNetworkName", \ 
   "targetColumn": "name", \ 
   "targetNetwork": "targetNetworkName" \ 
 }' 'http://localhost:1234/v1/commands/layout/copycat'

Additionally, the Copycat Command can be executed directly via the Cytoscape Command Tool or as part of a Cytoscape Command script as shown below, where each parameter is specified using a key-value pair. Optional parameters can be specified by appending additional key-value pairs.

layout copycat sourceNetwork={sourceNetworkName} targetNetwork={targetNetworkName}