Introduction to Cytoscape REST API

1. Import R Packages and Basic Setup

3rd Party Library

In this tutorial, we will use several popular R packages to make this workflow more realistic.

HTTP Client

Since you need to access Cytoscape via RESTful API, HTTP client library is the most important tool you need to understand. In this example, we use httr.

JSON Encoding and Decoding

Data will be exchanged as JSON between Cytoscape and R. We will use 3rd party package RJSONIO in this workflow to encode/decode JSON.

Basic Setup for the API

At this point, there is only one option for the cy-rest module: port number.

URL to Access Cytoscape REST API

We assume you are running Cytoscape desktop application and R on a same machine. To access Cytoscape REST API, use the following URL:

http://localhost:PORT_NUMBER/v1/

where v1 is the current version number of API. Once the final release is ready, we guarantee compatibility of your scripts as long as major version number is the same.

Change Port Number

By default, port number used by cy-rest module is 1234. To change this, you need set a global Cytoscape property from Edit–>Preserences–>Properties… and add a new property port.number.

library(RJSONIO)
library(igraph)
library(httr)

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

print(base.url)

## [1] "http://localhost:1234/v1"

2. Test Cytoscape REST API

Understand REST Basics

HTTP Verb	Description
GET	Retrieving resources (in most cases, it is Cytoscape data objects, such as networks or tables)
POST	Creating resources
PUT	Changing/replacing resources or collections
DELETE	Deleting resources

Make sure Cytoscape REST API module is running

First, send a simple request and check server status.

version.url = paste(base.url, "version", sep="/")
cytoscape.version = GET(version.url)
cy.version = fromJSON(rawToChar(cytoscape.version$content))
print(cy.version)

##       apiVersion cytoscapeVersion 
##          "1.0.0"          "3.1.1"

Generate Network with igraph

# 1. Create simple directed graph with Barabasi-Albert model
graph1 <- barabasi.game(200)

# 2. Calculate some statistics and assign then to the graph
graph1$name = "Scale-Free Network (BA Model)"
graph1$density = graph.density(graph1)

V(graph1)$degree <- degree(graph1)
V(graph1)$closeness <- closeness(graph1)
V(graph1)$betweenness <- betweenness(graph1)
V(graph1)$page_rank <- page.rank(graph1)$vector
V(graph1)$community <- label.propagation.community(graph1)$membership

E(graph1)$betweenness <- edge.betweenness(graph1)

Build Custom Visual Style

style.name = "MyCustomStyle3"

# Defaults
def.node.color <- list(
  visualProperty = "NODE_FILL_COLOR",
  value = "#00aabb"
)

def.node.border.width <- list(
  visualProperty = "NODE_BORDER_WIDTH",
  value = 0
)

def.edge.target.arrow <- list(
  visualProperty="EDGE_TARGET_ARROW_SHAPE",
  value="ARROW"
)

defaults <- list(def.node.color, def.node.border.width,def.edge.target.arrow)

# Visual Mappings
min.betweenness = min(V(graph1)$betweenness)
max.betweenness = max(V(graph1)$betweenness)

mappings = list()

point1 = list(
  value=min.betweenness,
  lesser= "20.0",
  equal="20.0",
  greater="20.0"
)

point2 = list(
  value=max.betweenness,
  lesser="200.0",
  equal="200.0",
  greater="200.0"
)

node.size.continuous.points = list(point1, point2)

node.size = list(
  mappingType="continuous",
  mappingColumn="betweenness",
  mappingColumnType="Integer",
  visualProperty="NODE_SIZE",
  points = node.size.continuous.points
)

node.label = list(
  mappingType="passthrough",
  mappingColumn="name",
  mappingColumnType="String",
  visualProperty="NODE_LABEL"
)

mappings = list(node.size, node.label)

style <- list(title=style.name, defaults = defaults, mappings = mappings)
style.JSON <- toJSON(style)

style.url = paste(base.url, "styles", sep="/")
POST(url=style.url, body=style.JSON, encode = "json")

## Response [http://localhost:1234/v1/styles]
##   Status: 200
##   Content-type: application/json
## {"title": "MyCustomStyle3_2"}

Send the graph to Cytoscape

# Load utility functions
source('toCytoscape.R')

# Convert to Cytoscape style JSON object
cygraph <- toCytoscape(graph1)

# Send it to Cytoscape!
network.url = paste(base.url, "networks", sep="/")
res <- POST(url=network.url, body=cygraph, encode="json")
network.suid = unname(fromJSON(rawToChar(res$content)))

Apply layouts and Visual Style

apply.layout.url = paste(base.url, "apply/layouts/force-directed", toString(network.suid), sep="/")
apply.style.url = paste(base.url, "apply/styles", style.name, toString(network.suid), sep="/")

res <- GET(apply.layout.url)
res <- GET(apply.style.url)

Introduction to Cytoscape REST API

Keiichiro Ono

8/6/2014

Basic Workflow 1: Fundamentals

Introduction

Prerequisites

System Requirments

Questions or Feature Requests?