1 Introduction

scTreeViz is a package for interactive visualization and exploration of Single Cell RNA sequencing data. scTreeViz provides methods for exploring hierarchical features (eg. clusters in single cell at different resolutions or taxonomic hierarchy in single cell datasets), while supporting other useful data visualization charts like heatmaps for expression and scatter plots for dimensionality reductions like UMAP or TSNE.

1.1 Loading required packages


2 Preparing Datasets

The first step in using the scTreeViz package is to wrap datasets into TreeViz objects. The TreeViz class extends SummarizedExperiment and provides various methods to interactively perform various operations on the underlying hierarchy and count or expression matrices. In this section, we show various ways to generate a TreeViz object either from existing Single Cell packages (SingleCellExperiment or Seurat) or from a raw count matrix and cluster hierarchy.

2.1 From SingleCellExperiment

A number of Single cell datasets are available as SingleCellExperiment objects through the scRNAseq package, for this usecase, we use LunSpikeInData dataset. In addition, we calculate the dimensionality reductions; UMAP, TSNE and PCA from the functions provided in scater package.

# load dataset
sce<- ZeiselBrainData()
# Normalization
sce <- logNormCounts(sce)
# calculate umap and tsne
sce <- runUMAP(sce)
sce<- runTSNE(sce)
sce<- runPCA(sce)

We provide createFromSCE function to create a TreeViz object from SingleCellExperiment object. Here, the workflow works in two ways:

  1. If no cluster information is available in the colData of the SingleCellExperiment object, we create clusters at different resolutions using the WalkTrap algorithm by calling an internal function generate_walktrap_hierarchy and use this cluster information for visualization.
treeViz <- createFromSCE(sce, reduced_dim = c("UMAP","PCA","TSNE"))
#>  [1] "1.cluster1"   "2.cluster2"   "3.cluster3"   "4.cluster4"   "5.cluster5"  
#>  [6] "6.cluster6"   "7.cluster7"   "8.cluster8"   "9.cluster9"   "10.cluster10"
#> [11] "11.cluster11" "12.cluster12" "13.cluster13" "14.cluster14" "samples"

  1. If cluster information is provided in the colData of the object, then the user should set the flag parameter check_coldata to TRUE and provide prefix for the columns where cluster information is stored.
# Forming clusters
for (i in  seq(10)) {
  clust.kmeans <- kmeans(reducedDim(sce, "TSNE"), centers = i)
  sce[[paste0("clust", i)]] <- factor(clust.kmeans$cluster)

treeViz<- createFromSCE(sce, check_coldata = TRUE, col_regex = "clust")

Note: In both cases the user needs to provide the name of dimensionality reductions present in the object as a parameter.

2.2 From Seurat

We use the dataset pbmc_small available through Seurat to create a TreeViz object.

pbmc <- pbmc_small

We then preprocess the data and find clusters at different resolutions.

pbmc[[""]] <- PercentageFeatureSet(pbmc, pattern = "^MT-")
pbmc <- NormalizeData(pbmc)
all.genes <- rownames(pbmc)
pbmc <- ScaleData(pbmc, = "")
pbmc <- FindVariableFeatures(object = pbmc)
pbmc <- RunPCA(pbmc, features = VariableFeatures(object = pbmc))
pbmc <- FindNeighbors(pbmc, dims = 1:10)
pbmc <- FindClusters(pbmc, resolution = c(0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0), print.output = 0, save.SNN = TRUE)

The measurements for dimensionality reduction methods we want to visualize are also added to the object via native functions in Seurat. Since PCA is already added, we calculate TSNE and UMAP

# pbmc<- RunTSNE(pbmc)
pbmc<- RunUMAP(pbmc, dims=1:3)

We use the createFromSeurat function to create a TreeViz object from Seurat object. In addition the object, we pass the name of dimensionality reductions present in the object as a paramter in vector format to indicate these measurements should be added to treeviz for visualization. If the mentioned reduced dimension is not present it would simply be ignored.

treeViz<- createFromSeurat(pbmc, check_metadata = TRUE, reduced_dim = c("umap","pca","tsne"))
#> [1] "6.cluster6"   "10.cluster10" "11.cluster11" "samples"     
#> [1] "umap" "pca"  "tsne"

2.3 Create TreeViz from count matrix and Cluster hierarchy

# create a hierarchy
df<- data.frame(cluster0=rep(1,n))
for(i in seq(1,5)){
  df[[paste0("cluster",i)]]<- rep(seq(1:(2**i)),each=ceiling(n/(2**i)),len=n)

# generate a count matrix
counts <- matrix(rpois(6400, lambda = 10), ncol=n, nrow=100)
colnames(counts)<- seq(1:64)
# create a `TreeViz` object
treeViz <- createTreeViz(df, counts)

2.4 Start the TreeViz App (using hosted app)

Start the App from the treeViz object we created. This adds a facetZoom to navigate the cluster hierarchy, a heatmap of the top n most variable genes from the dataset, where ‘n’ is selected by the user and one scatter plot for each of the reduced dimensions.

app <- startTreeviz(treeViz, top_genes = 500)