scNetViz: from single cells to networks using Cytoscape

Overview

scNetViz consists of two main components, a Java-based Cytoscape app and a web service implemented on a compute cluster at the Resource for Biocomputing, Visualization and Informatics (RBVI) at the University of California, San Francisco. In addition, the app portion uses several other Cytoscape apps, including stringApp,¹⁸ cyPlot,¹⁹ and enhancedGraphics.²⁰

The Cytoscape app provides the following functionality:

The RBVI web service component provides a simple wrapper around Scanpy that exposes REST endpoints for:

Matrices are passed as compressed MatrixMarket files²⁴ and parameters may be provided to simplify and normalize the matrix in a pre-processing step, in addition to parameters related to the appropriate algorithm.

Cytoscape app

The Cytoscape App provides the main front-end, data management, and orchestration for scNetViz. Importantly, the app also exports Cytoscape commands so that scNetViz can be used by CyREST²⁵ packages such as RCy3²⁶ and py4cytoscape.²⁷ Below, we discuss five of the app functions: data access, differential gene expression calculation, plot generation, network creation, and automation via R and Python. The various user interface components are all implemented in Java Swing, use the Cytoscape Java Desktop API, and are shown in the use case descriptions.

Data access

scNetViz supports three types of data: cell by gene matrices (typically read in MatrixMarket format), experiment-level metadata including organism, number of cells in the experiment, and category-level metadata such as cell cluster assignments, disease state, cell type, tissue, ethnicity, which is typically in comma-separated value (CSV) format. scNetViz has a sources module, which includes submodules for each supported data source. A source module provides the tasks necessary to import data for an experiment or category, enumerates the available experiments and displays them. We have currently implemented support for three sources: EMBL-EBI’s Single Cell Expression Atlas, the Human Cell Atlas data portal, and local files. The former two are public sources and are referred to as GXA and HCA, respectively, in scNetViz commands. They provide support for browsing experiments, while the local source provides methods to read category and experiment files. Since different category data might be in a different orientation (typically clusterings files are organized with the clusters in rows and cells in columns, but cell metadata and demographics are organized with the cells in rows and categorical information in the columns), we provided the ability to read in the CSV and transpose the resulting matrix, which may be needed to feed the data to downstream analysis steps.

To import data from the two public repositories, we rely on their published REST interfaces. The Single Cell Expression Atlas provided the simplest interface as specific endpoints for the matrices, clusters, and experimental-design:

Data access from the Human Cell Atlas recently transitioned to a new data coordination platform (DCP) API. scNetViz currently uses the ”DCP1” API, and we will transition to ”DCP2” in the near future. To access the DCP1 data:

Differential expression calculation

As shown below, the key function of scNetViz is to calculate the differential expression of each gene across categories and then use the highly differentially expressed genes (possible marker genes) to construct a gene functional interaction network. We calculate differential gene expression using Mann-Whitney U test and represent it as the log₂(fold change) where fold change is the ratio of the mean expression of a gene in a single group within a category vs. the mean expression of that gene in the comparison set of all other groups within that same category. For example, if the chosen category is a clustering with K=5 classes, then each of the five classes is one group within the category. We provide two cutoff values to reduce noise in the resulting gene interaction network. First, a gene must be expressed in at least 10% of the cells in the group or 10% of the cells in the set of all other groups in the category. Second, we have a minimum log₂(fold change) cutoff that drops any changes that are beneath that threshold. All of this data is provided in a table that is created and provided to the user.

Plot generation

All of the plots provided by scNetViz are generated by the cyPlot Cytoscape App.¹⁹ cyPlot uses the built-in Cytoscape web browser and the plotly.js Javascript library to display plots. All of the data is passed to cyPlot using its automation interface. For example, below is the scNetViz method to create a violin plot.

 public static void createViolinPlot(ScNVManager manager,
                     String names, String data,
                     String groups, String title,
                     String xlabel, String ylabel,
                     String accession,
                     boolean showAll, double jitter) {
 Map<String, Object> argMap = new HashMap<>();
 argMap.put("data", data);
 argMap.put("editor", "false");
 argMap.put("xLabel",xlabel);
 argMap.put("yLabel",ylabel);
 argMap.put("title",title);
 argMap.put("names",names);
 argMap.put("groups",groups);
 argMap.put("id",accession);
 if (showAll)
   argMap.put("showAll","true");
 else
   argMap.put("showAll","false");
 argMap.put("jitter",jitter);
 argMap.put("selectionString",
        "scnetviz select accession=\""+accession+"\" genes=%s");
 manager.executeCommand("cyplot", "violin", argMap);
}

All of the arguments in the above code chunk are JSON strings that are consumed by cyPlot and passed on to the plotly.js library for display.

Network creation

Once the calculation of differential expression is complete, scNetViz can create networks to show the functional interactions among the proteins encoded by the differentially expressed genes. This proceeds in two steps. First, the STRING network of a user-specified number (default 200) of top differentially expressed genes for each group within the category is created by using the Cytoscape automation interface of the stringApp. The method that does this is:

 private void createStringNetwork(Object cat, String name,
                   List<String> geneList,
                    Map<Object, List<String>> geneMap,
                   TaskMonitor monitor) {
 monitor.setTitle("Retrieving STRING network for: "+name);
 monitor.showMessage(TaskMonitor.Level.INFO,
             "Retrieving STRING network for: "+name);
 Map<String, Object> args = new HashMap<>();
 args.put("query", listToString(geneList, ""));
 args.put("species",
    diffExp.getCurrentCategory().getExperiment().getSpecies());
 args.put("limit", "0");
 args.put("includesViruses", "false");
 manager.executeCommand("string", "protein query", args,
       new RenameNetwork(diffExp, cat, name,
                 geneList, geneMap, false, monitor),
               true);
 cyEventHelper.flushPayloadEvents();
}

This creates the argument map and then calls the executeCommand method, which is a wrapper method that we implemented around the Cytoscape org.cytoscape.command.CommandExecutorTaskFactory. The stringApp queries STRING and creates the network. The second part of the process extracts significantly differentially expressed genes in a single group from the network that contains the top differentially expressed genes in a category. This is done using the Cytoscape API to create subnetworks and provide styles that color nodes based on their differential expression in a given group.

Automation

Similar to the automation functionality that scNetViz uses, described above, scNetViz provides its own automation commands, useful for scripts to control scNetViz operations. The following is a list of available commands (details available in the Swagger documentation (Help $\to$ Automation $\to$ CyREST Command API)).

help scnetviz
Available commands:

scnetviz add file category      Add a category to an experiment from a file
scnetviz add leiden category    Calculate the Leiden clustering
scnetviz add louvain category   Calculate the Louvain clustering
scnetviz calculate diffexp      Calculate the table of differential gene expression
scnetviz calculate draw_graph   Calculate the graph layout embedding
scnetviz calculate tsne         Calculate the t-SNE embedding (remote)
scnetviz calculate tSNE         Calculate the tSNE embedding (local)
scnetviz calculate UMAP         Calculate the UMAP embedding (remote)
scnetviz create all             Calculate differential expression and create networks
scnetviz create network         Create the networks for differentially expressed genes
scnetviz delete experiment      Remove an experiment
scnetviz export category        Export a currently loaded category table
scnetviz export diffexp         Export a differential expression table
scnetviz export experiment      Export a currently loaded experiment table
scnetviz list experiments       List the currently loaded experiments
scnetviz list gxa entries       List all Single Cell Expression Atlas (GXA) entries available
scnetviz list hca entries       List all Human Cell Atlas (HCA) entries available
scnetviz load experiment file   Load an experiment from a file
scnetviz load gxa experiment    Load an experiment from the EBI Single Cell Expression Atlas
scnetviz select                 Select genes or assays in current tables
scnetviz show cell plot         Display the cell plot (UMAP, t-SNE) for a single experiment
scnetviz show diff plot         Display the differential expression plot for a single experiment
scnetviz show experiment        Show a currently loaded experiment
scnetviz show experiment table  Display the experiment table for a single experiment

As an example workflow, one might execute the following commands:

# Load experiment "E-CURD-3" from the EBI Single Cell Expression Atlas
scnetviz load gxa experiment accession="E-CURD-3"

# Calculate the differential expression using the default values:
#   category=Cluster
#   categoryRow=4 (or whatever row has "True")
#   logGERCutoff=0.5
#   minPctCutoff=10
scnetviz calculate diffexp accession="E-CURD-3"

# Create the networks using the default values:
#   fdrCutoff=0.5
#   maxgenes=200
#   positiveOnly=false
#   log2FCCutoff=1.0
scnetviz create network accession="E-CURD-3"

Web service

As discussed above, the web service component is primarily a wrapper around Scanpy that exposes a limited set of the Scanpy functionality appropriate to the needs of scNetViz. In each case, the web service collects the data and arguments, calls Scanpy pre-processing routines as appropriate, and then calls the Scanpy implementation of the algorithm. By default, the matrix will be normalized, log-transformed, restricted to only the most variable genes, and scaled. The default minimum of 100 genes/cell and a minimum of at least 1 cell for each gene are also used. The parameters to control pre-processing may be changed by opening up the Advanced pre-processing parameters section of the UMAP, t-SNE, Louvain, or Leiden dialogs, which enables the user to change any of the pre-processing defaults.

The web service implements the algorithms using the appropriate scanpy.tl methods (scanpy.tl.tsne, scanpy.tl.umap, scapy.tl.leiden, and scanpy.tl.louvain). In all cases, the matrix is pre-processed and passed to the appropriate Scanpy module. We expose the most useful parameters in each case. For UMAP, we expose the number of neighbors and the minimum distance parameters; for t-SNE, we expose the perplexity, the number of initial dimensions, the early exaggeration parameter and the learning rate. Note that if the number of initial dimensions is set to -1, a PCA will be calculated first to reduce the dimensionality of the matrix, which can improve the resulting t-SNE embedding. For Leiden and Louvain, we expose the number of neighbors to use to calculate the neighborhood graph before clustering (see scanpy.pp.neighbors). See the Scanpy documentation for a more detailed explanation of the effects of these routines and parameters.

Use Cases

We have prioritized providing access to the Single Cell Expression Atlas and Human Cell Atlas.^3,4 Additionally, researchers can import normalized and clustered scRNA-seq data from local files. The following workflows demonstrate two use cases using either the Single Cell Expression Atlas or local files, and illustrate the utility of scNetViz in integrating network information with scRNA-seq data. Scripted versions of these workflows are also available as R Markdown documents and Jupyter notebooks, which leverage the RCy3²⁶ and py4cytoscape²⁷ packages, respectively. They require Cytoscape (3.7.1 or later), CyREST (3.8.0 or later), and R (version 4.0 or later) or Python (version 3.6 or later). User documentation is available at: https://www.cgl.ucsf.edu/cytoscape/scNetViz/index.shtml. Downloadable notebooks of these workflows are available in R and Python at http://automation.cytoscape.org.

Use Case #1: Loading data from the EMBL-EBI Single Cell Expression Atlas for scNetViz analysis

In this example, we will browse the Single Cell Expression Atlas from within Cytoscape, explore a particular dataset, perform differential expression analysis based on one of the provided cell annotation categories, generate networks from the top differentially expressed genes for each group within the chosen category, and functionally characterize and visualize the networks.

Figure 1. The Categories tab shows the grouping of cells for differential analysis and visualization purposes.

The menu labeled New Cell Plot contains options for generating UMAP and t-SNE plots. Note that these results are for data from the Single Cell Expression Atlas release 15 (March, 2021).

Figure 2. The DiffExp tab allows selection of cutoffs for genes to be used for network analysis and contains options for generating gene by cell heatmaps and violin plots showing gene expression distributions across cell annotation categories.

Figure 3. The networks from the STRING database are displayed in the main Cytoscape window.

The illustration shows the interaction network for genes specific to the group labeled ”Cluster 4”. Users can filter the complete network using the network analysis tools in Cytoscape. (a) A selection of the largest connected component, which is highlighted with yellow nodes and red edges. (b) Other sub-networks might also be of interest. The second-largest connected component of Cluster 4 shows enrichment of melanoma-associated terms, which is consistent with the fact that this experiment is on melanoma cell lines.

Use Case #2: Loading your own scRNA-Seq data from local files for scNetViz analysis

In this example, we will import normalized scRNA-seq data and cluster assignments from local files, visualize all cells in a UMAP plot, perform differential expression analysis based on one of the provided categories, visualize as a combined gene expression heat map, and generate networks for the most significantly differentially expressed genes from each group within the chosen category.

Figure 4. The UMAP plot is displayed in a pop-up window and can be explored interactively.

Each dot is a cell, and coloring is by cluster number. Note that the illustration shows results obtained from analysis with the default settings.

Figure 5. The heatmap for the top differentially expressed genes is displayed in a pop-up window and can be explored interactively.

Note that the illustration shows results obtained from analysis with the default settings.