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.

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}

Many biological analyses rely on performing differential analysis on derived subnetworks. In the case of inferring gene regulatory networks ⁹ , it is beneficial to show mutations at each time-step without touching the unchanged parts of the network. Identifying and visualizing the changes over time is much easier with Cytoscape Automation. After loading networks into Cytoscape, the CyREST API can be used to fetch the SUID of networks and views, and the names of columns in the node table. What follows are some of the essential steps for this kind of analysis.

# Retrieve network and view SUID from Cytoscape in Python REST_PORT= '1234' # Set to whatever rest.port is in Cytoscape preferences REST_ENDPOINT = "http://localhost:{}/v1" .format(REST_PORT) resp = requests.get(REST_ENDPOINT + "/networks" ) network_suids = resp.json() suid_map = { 'source' : { 'suid' : network_suids[ 0 ]}, 'target' : { 'suid' :network_suids[ 1 ]}} resp = requests.get( "{}/networks/{}/views" .format(REST_ENDPOINT, suid_map[ 'source' ][ 'suid' ])) suid_map[ 'source' ][ 'view_suid' ] = resp.json()[ 0 ] # only one view exists

Insert the network view SUIDs into the sample scripts listed above to apply the Copycat layout, and the CyREST API will return the number of mapped and unmapped nodes in the target layout. Once the layout has completed, add a GET request to /networks/{SUID}/views/{viewSUID}.png to generate images of the aligned networks. Adding the selectUnmapped parameter and a few calls to the core Cytoscape network API suite allows callers to take full advantage of the layout results by getting unmapped node information.

resp = requests.get( "{}/networks/{}/nodes/selected" .format(REST_ENDPOINT,networkId)) nodes = [] for nodeId in resp.json(): resp = requests.get( "{}/networks/{}/nodes/{}" .format(REST_ENDPOINT,networkId, nodeId)) nodes.append(resp.json())

The complete working example of this workflow is available in a Jupyter notebook found in the copycat-layout Github repository at https://github.com/cytoscape/copycat-layout/blob/master/notebooks/Copycat%20Automation%20Example.ipynb.