Existing tools

Several Cytoscape apps and plugins tackle tool interoperability and workflow reproducibility challenges (Table 1), most notably Cytoscape 3’s Command core module, but also including plugins deprecated along with Cytoscape 2.

Cytoscape 3’s Command Line Tool⁵ facilitates task automation via its own domain specific language, which provides access to high-level Cytoscape functions using a separate REST server within Cytoscape. While Command can execute individual commands (e.g., for loading and applying layouts) and sequences of commands (as scripts), it has no provision for accessing the network, style, and visualization information available through cyREST. Command is a complement to cyREST, where the combination greatly improves interoperability between Cytoscape and workflow-capable external tools, which contribute looping and control flow. A workflow can intermix Command and cyREST calls without conflict – they address different capabilities within Cytoscape.

A notable alternative to cyREST is the Cyrface app⁶, which allows R and Bioconductor⁷ functions to be executed from Cytoscape 3, with the results returned to Cytoscape 3 – the opposite of a cyREST call. While this approach enables Cytoscape to act as the workflow orchestrator, it requires that a target application act as a server, which often requires idiosyncratic and complex support for each target application. So far, this approach has been taken only for interfacing to R.

Numerous approaches to interoperability were implemented as ScriptingEngine⁸-based plugins for Cytoscape 2, now deprecated. Such plugins were created for executing scripts written in languages (e.g., JRuby⁹, Jython¹⁰, Groovy¹¹, Clojure¹², and JavaScript¹³). While these scripts had full access to Cytoscape’s comprehensive public API, their tight coupling to the Cytoscape runtime made them difficult to write, debug, and maintain. Because they were built on top of the Java virtual machine (JVM) and shared Cytoscape’s JVM, they had little access to increasingly capable and standardized third party native libraries (e.g., SciPy¹⁴ for Python). By contrast, the cyREST approach allows control of Cytoscape by best-of-breed tools and languages running independently as separate processes and leveraging best-of-breed native libraries. Conversely, while plugin implementations could interact with the user via dialog boxes directly within Cytoscape 2, scripts executing in separate processes run within their own windows, disconnected from Cytoscape 3.

Similar to the cyREST approach, the CytoscapeRPC plugin¹⁵ enabled independent scripts (e.g., Python) to create, query, and modify networks and visual styles in Cytoscape 2, but using an XML-RPC¹⁶ protocol instead of REST. Given the rapid adoption of REST conventions and supporting infrastructure, use of XML-RPC is becoming less common. Notably, RCytoscape¹⁷ is a Bioconductor package that leveraged CytoscapeRPC to enabled R applications to control Cytoscape 2. For Cytoscape 3, RCytoscape has been replaced by the RCy3 package in Bioconductor release 3.2, which leverages cyREST instead and is described below.

Design

cyREST is a Cytoscape app that exposes the Cytoscape network data model to external tools and languages. It presents an API based on principles of REST, as do other popular biology-related data services, including those provided by EBI¹⁹. As a result, cyREST leverages REST facilities in existing tools and languages already built and vetted for use with other REST-based services. The definition and packaging of individual API functions takes advantage of lessons learned in building similar interfaces for Cytoscape 2.

cyREST APIs represent all Cytoscape data objects and functions as resources according to principles of Resource-oriented Design (ROD)²⁰. Data objects include networks, tables, and Visual Styles. Functions include applying layout algorithms on networks, updating Visual Styles, and performing statistical analysis. Under REST and ROD, each resource is encoded as a URL where hierarchy is represented as segments within the URL. For example, the URL http://localhost:1234/v1/tables/count can be decomposed into a REST server (http://localhost), port number (1234), an API version (v1), a resource (tables), and an attribute of the resource (count). So, this URL represents the count of global tables maintained by Cytoscape. Table 2 shows a sampling of resources available under the http://localhost:1234/v1 URL, with a more comprehensive list in the cyREST document at http://idekerlab.github.io/cyREST).

cyREST follows ROD recommendations for sensible mappings between CRUD operations (create, read, update, and delete) and HTTP operations (POST, GET, PUT, DELETE) on data objects. Unless otherwise specified in the cyREST documentation, all HTTP operations accept or return values encoded as JSON. For example, GET http://localhost:1234/v1/networks returns a list of networkIds in an array (e.g., [1,2,3]). GET http://localhost:1234/v1/networks/networkId returns all nodes, edges, tables, and other data relating to network networkId in the Cytoscape.js²¹ JSON format.

For functions, ROD provides less guidance for CRUD/HTTP mappings or URL encoding. cyREST addresses this by grouping actions under http://localhost:1234/v1/apply (using GET operations) as illustrated in Table 3.

Implementation

cyREST is implemented as a Cytoscape app written in the Java programming language. It uses the Jersey JAX-RS²² library to implement the RESTful API, and provides access to data object and function operations as calls to public Cytoscape APIs. Under REST, each client request is phrased as an HTTP command (e.g., GET http://localhost:1234/v1/networks HTTP/1.1) and the reply is returned as a JSON structure.

cyREST uses an embedded Grizzly HTTP server to receive and process client requests, where each HTTP request’s URL is mapped to a method in a resource manager class created by cyREST and registered with Grizzly. Each resource method declares the URL it services. When Grizzly receives a REST request, it calls the resource function registered for the URL, which calculates and returns a REST reply. For example, the NetworkResource defines a function that returns the number of Cytoscape networks in the current session, shown in the code fragment below. Note that the fragment defines its associated HTTP command, URL, and JSON output via Java annotations.

@Path("/v1/networks")
public class NetworkResource extends
    AbstractResource {
  @GET
  @Path("/count")
  @Produces(MediaType.APPLICATION_JSON)
  public String getNetworkCount() {
    // Call Cytoscape to get count of network
        - return value as COUNT
    return
        getNumberObjectString(JsonTags.COUNT,
        networkManager.getNetworkSet().size());
}

As with most Cytoscape apps, cyREST is initialized in its cyActivator function, which creates resource classes that reference all Cytoscape APIs to be used in servicing client requests. These include factories and managers for networks, network views, visual mapping, layout algorithms, groups, tables, sessions, and others.

The default HTTP port for cyREST is 1234, which can be changed by creating or modify the Cytoscape rest.port property (via Cytoscape’s Edit | Preferences | Properties dialog). Note that security-conscious workstations should firewall the cyREST port to prevent unintended outside access.

To test for the availability of a cyREST server, use an Internet browser to view the URL http://localhost:1234/v1/, which returns JSON-formatted version information similar to:

{
	"apiVersion":"v1", 
	"numberOfCores":4, 
	"memoryStatus": {
	       "usedMemory":517, 
	       "freeMemory":1445, 
	       "totalMemory":1963, 	
	       "maxMemory":6917
	}
}

Each cyREST function is exercised and validated before release by a suite of JUnit-based tests.

Harmonization libraries

While most programming languages make calling REST APIs and composing or parsing JSON simple, the data returned by cyREST may not be organized efficiently for ease of use in a particular language or with that language’s libraries. To maximize programmer productivity, we provide harmonization libraries (see Figure 2) to perform efficient cyREST calls on one hand, and present an interface easily used by programmers on the other hand. To date, we provide harmonization libraries for Python and R, and we expect to produce others.

py2cytoscape harmonization library for Python

The Python programming language has become popular among scientists and data analysts because of its rich collection of open source data analysis packages and a large developer community. It is an excellent tool for data cleansing, manipulation, analysis, and visualization; its igraph²³, NetworkX²⁴, and graph-tool²⁵ packages are useful components in network data analysis workflows. In a workflow, it functions well as a glue that connects multiple heterogeneous computing resources, public databases, and private data files to build data analysis pipelines on workstations and computing clusters.

We created the py2cytoscape library to enable Python-based workflows to easily incorporate Cytoscape functionality by wrapping Python calls to cyREST and performing automatic translations between these packages’ data structures and cyREST’s JSON. For example, the following code creates a new Cytoscape network by using py2cytoscape calls, and replaces 16 lines that would be necessary when calling cyREST directly – see https://github.com/idekerlab/py2cytoscape/blob/develop/README.md for the direct cyREST calls.

from py2cytoscape.data.cyrest_client import
    CyRestClient

cy = CyRestClient()
network = cy.network.create(name=’My Network’, 
    collection=’My  network  collection’)
print(network.get_id())

py2cytoscape is open source and is available from the PyPI repository (https://pypi.python.org/pypi/py2cytoscape).

Note that py2cytoscape provides a widget that renders a network in cytoscape.js JSON format and then visualizes the network interactively within a Jupyter/IPython Notebook²⁶ document, an example of which is at http://nbviewer.ipython.org/github/idekerlab/py2cytoscape/blob/develop/examples/New_wrapper_api_sample.ipynb.

RCy3 harmonization library for R

R is a particularly important platform for biologists because of the complimentary Bioconductor library. We are collaborating with the Bioconductor group to produce the RCy3 harmonization library for R²⁷, which leverages cyREST to realize native R network visualization, analysis, and publishing functions. Its igraph, graph²⁸, and RBGL²⁹ packages are useful components for network data analysis workflows.

Sample workflows

A typical workflow performs data acquisition and integration, analysis, network visualization, and publishing. Often, these steps are performed one at a time by humans executing one discreet tool after another, possibly resulting in high labor costs, low throughput, high error rates, and an inability to reproduce the workflow reliably. In contrast, Figure 1 shows a workflow orchestrated by external tools such as Python and R, which interact with Cytoscape to perform parts of the workflow. As supplementary material, we provide downloadable sample workflows that incorporate and demonstrate cyREST functionality using py2cytoscape and RCy3 harmonization libraries.

Note that Cytoscape/cyREST is designed to run on the same workstation as the workflow that calls it – Cytoscape maintains its own application window, and workflows may find advantage in soliciting users directly within Cytoscape.

Python examples

Our Python-based sample workflows are simple reflections of real world data analysis and visualization pipelines (see Figure 1) and use standard Python packages as much as possible. They are located in https://github.com/idekerlab/cy-rest-python and are viewable using the nbviewer web application (http://nbviewer.ipython.org/) in Jupyter Notebook format.

Some Python packages are more capable or faster than equivalent Cytoscape functions, so the examples use them instead of calling Cytoscape. For example, Pandas³⁰ prepares and analyzes data by using NumPy³¹ and SciPy library for processor-intensive tasks such as community detection.

The examples use the py2cytoscape harmonization libraries to demonstrate efficient cooperation between Python workflows by using NetworkX, igraph, and Cytoscape to integrate and visualize data generated in external tools. They show:

For instance, the “Import KEGG pathways from web service” example demonstrates a typical biological data integration and visualization process involving KEGG databases³²:

This workflow is simple to do with Cytoscape – the alternative would be a custom program or manual, file based operations that are hard to reproduce. With this workflow script, collaborators or reviewers can easily execute the same process on their environment, which is essential for reproducible scientific research.

R examples

For network analysis and visualization, igraph is an important and much used package by R users, and our sample R workflows (https://github.com/idekerlab/cy-rest-R) use it to complement the graph analysis features in Cytoscape.

In our Workflow 1 example, we scripted typical network visualization techniques using igraph’s graph analysis functions and Cytoscape’s data visualization features. First, we used igraph to detect community structure using a fast greedy modularity optimization algorithm³³, and we calculated basic statistics of the network, including PageRank³⁴ and betweenness centrality³⁵. Our R code calls Cytoscape to create the resulting network, set properties for both layout and visual mapping, and generate an interactive network visualization. Output of this workflow helps users to visually understand the basic structure of the network (see Figure 3, which shows community structures color coded and used as weights for the Kamada-Kawai layout algorithm³⁶).

Figure 3. Yeast network³⁷ visualization with sample R script and Cytoscape.

In many cases, users apply an automatic layout algorithm early in a workflow to visually check the overall structure of a network. However, such layouts are often based on a simple force simulation and tend to produce uninformative “hairballs.” Our example illuminated network sub structures by using a community detection algorithm and igraph’s statistical analysis algorithms and visual styling. The alternative would be manual operation of both R and Cytoscape, which is laborious and error prone even for proficient users, and which is not reusable for subsequent networks.