The R markdown is available from the pulldown menu for Code at the upper-right, choose “Download Rmd”, or download the Rmd from GitHub.

1 Why use Jupyter Bridge

  • Users do not need to worry about dependencies and environment.
  • Easily share notebook-based workflows and data sets
  • Workflows can reside in the cloud, access cloud resources, and yet still use Cytoscape features.

2 How Jupyter Bridge works

Jupyter-Bridge enables a workflow running on remote Jupyter to execute functions on a PC-local Cytoscape – the remote Jupyter runs the request through Jupyter-Bridge, where it is picked up by Javascript code running on the Jupyter web page in the PC-local browser, which in turn calls Cytoscape. The Cytoscape response travels the reverse route.

Jupyter-Bridge allows a remote Jupyter Notebook to communicate with a workstation-based Cytoscape as if the Notebook were running on the Cytoscape workstation. A Jupyter Notebook passes a Cytoscape call to an independent Jupyter-Bridge server where it’s picked up by the Jupyter-Bridge browser component and is passed to Cytoscape. The Cytoscape response is returned via the opposite flow. As a result, workflows can reside in the cloud, access cloud resources, and yet still leverage Cytoscape features. Jupyter Bridge supports py4cytoscape (Python library for communicating with Cytoscape) first, and now RCy3 also support Jupyter-Bridge.

Visit the source code of Juputer Bridge for more information.

3 Sandbox

A sandbox is a directory on the Cytoscape workstation that is guaranteed writeable and is guaranteed to be isolated from the whole file system. All file operations are carried out relative to the “current sandbox”. Generally, a Notebook-based workflow doesn’t have to do anything to set up a sandbox … the default sandbox is automatically set up as part of RCy3 startup. However, the workflow can set different sandboxes, and can even switch between them. A sandbox can contain both files and directories, and the user can transfer files between a sandbox and the workflow’s native file system (e.g., a remote Notebook’s server).

If a sandbox is defined, all Cytoscape functions read and write files to it by default.

Thus, is it possible to build workflows that don’t depend on the structure of the Cytoscape workstation’s file system. Such workflows can store workflow data files along with other workflow files on a remote Notebook server, then transfer them to a sandbox only when Cytoscape will need them. Conversely, when Cytoscape creates a file in a sandbox (e.g., exporting an image), the workflow can transfer the file to workflow storage.

A special case is when RCy3 is running on the same workstation as Cytoscape. The default sandbox is considered to be directory that’s current for the Python kernel. Alternatively, the workflow could also define a sandbox, and then move files in and out of it just as a remote Notebook would.

4 Prerequisites (Local machine)

RCy3 works by connecting with Cytoscape. You will need to install and launch Cytoscape in your local machine:

5 Prerequisites (Cloud server)

There are a lot of cloud computing services online, such as Google Colab, Amazon EMR Notebook, Microsoft Azure, CoCalc and your own JupyterHub. You can choose your favorite one.

Here we use Google Colab to demonstrate. Visit this link to create a new empty R Notebook, and make sure to run code below in the cloud.

Copy codes below to build connection between Jupyter notebook (cloud) and Cytoscape (local).

Make sure to run code below in the cloud!!!

6 Installation

Install the latest version of RCy3 from Bioconductor.

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("RCy3")
library(RCy3)

7 Connect to local Cytoscape

First, build connection between the jupyter notebook and local Cytoscape.

browserClientJs <- getBrowserClientJs()
IRdisplay::display_javascript(browserClientJs)

8 Check connection

Then, launch Cytoscape and keep it running whenever using RCy3 and Jupyter Bridge. Confirm that you have everything installed and running:

cytoscapeVersionInfo()
cytoscapePing()
getCurrentSandbox()

Done! Now you can execute a workflow in a remote server-based Jupyter Notebook to leverage your workstation’s Cytoscape. You can also easily share notebook-based workflows and data sets.

9 Use case: Run differentially expressed genes network analysis in the cloud

Visit the Jupyter Bridge RCy3 and Differentially Expressed Genes Network Analysis for the detailed workflow.