1 Introduction

In the context of RNA-seq expression (bulk or singlecell seq) data, the grade of membership model allows each sample (usually a tissue sample or a single cell) to have some proportion of its RNA-seq reads coming from each cluster. For typical bulk RNA-seq experiments this assumption can be argued as follows: each tissue sample is a mixture of different cell types, and so clusters could represent cell types (which are determined by the expression patterns of the genes), and the membership of a sample in each cluster could represent the proportions of each cell type present in that sample.

Many software packages available for document clustering are applicable to modeling RNA-seq data. Here, we use the R package maptpx (Taddy - International Conference on Artificial Intelligence and and 2012 2012) to fit these models, and add functionality for visualizing the results and annotating clusters by their most distinctive genes to help biological interpretation. We also provide additional functionality to correct for batch effects and also compare the outputs from two different grade of membership model fits to the same set of samples but different in terms of feature description or model assumptions.

2 CountClust Installation

CountClust requires the following CRAN-R packages: maptpx, ggplot2, cowplot, parallel, reshape2, RColorBrewer, flexmix,gtools, devtools along with the Bioconductor package: limma.

Before installing , pelase install the latest version of the maptpx package on Github.

library(devtools)
install_github("TaddyLab/maptpx")

## 
##   
   checking for file ‘/tmp/RtmpAAhBAV/remotes666710de7251/TaddyLab-maptpx-089f681/DESCRIPTION’ ...
  
✔  checking for file ‘/tmp/RtmpAAhBAV/remotes666710de7251/TaddyLab-maptpx-089f681/DESCRIPTION’
## 
  
─  preparing ‘maptpx’:
## 
  
   checking DESCRIPTION meta-information ...
  
✔  checking DESCRIPTION meta-information
## 
  
─  cleaning src
## 
  
─  checking for LF line-endings in source and make files and shell scripts
## 
  
─  checking for empty or unneeded directories
## 
  
─  building ‘maptpx_1.9-5.tar.gz’
## 
  
   
## 

Then one can install the package from Bioc as follows

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

The development version of the CountClust package is available on Github, along with some data packages used in examples for this vignette.

install_github('kkdey/CountClust')

Then load the package with:

library(CountClust)

3 Data Preparation

We install data packages as expressionSet objects for bulk RNA-seq reads data from Brain tissue samples of human donors under GTEx (Genotype Tissue Expression) V6 Project (GTEx Consortium, 2013) (GTEx Consortium 2013 )and a singlecell RNA-seq reads data across developmental stages in mouse embryo due to Deng et al 2014 (Deng et al. 2014).

Deng et al 2014 singleCellRNASeqMouseDeng2014 data package is a processed version of the data publicly available at Gene Expression Omnibus (GEO:GSE45719)[http://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE45719].

library(devtools)

read.data1 = function() {
x = tempfile()
download.file(
'https://cdn.rawgit.com/kkdey/singleCellRNASeqMouseDeng2014/master/data/Deng2014MouseEsc.rda',
destfile=x, quiet=TRUE)
z = get(load((x)))
return(z)
}

Deng2014MouseESC <- read.data1()
## Alternatively,
# install_github('kkdey/singleCellRNASeqMouseDeng2014')

GTExV6Brain The data package for GTEx V6 Brain sample data is also a processed version of the data publicly available at the GTEx Portal (dbGaP accession phs000424.v6.p1, release date: Oct 19, 2015).

read.data2 = function() {
x = tempfile()
download.file(
'https://cdn.rawgit.com/kkdey/GTExV6Brain/master/data/GTExV6Brain.rda',
destfile = x, quiet=TRUE)
z = get(load((x)))
return(z)
}

GTExV6Brain <- read.data2()
## Alternatively
# install_github('kkdey/GTExV6Brain')

deng.counts <- Biobase::exprs(Deng2014MouseESC)
deng.meta_data <- Biobase::pData(Deng2014MouseESC)
deng.gene_names <- rownames(deng.counts)

gtex.counts <- Biobase::exprs(GTExV6Brain)
gtex.meta_data <- Biobase::pData(GTExV6Brain)
gtex.gene_names <- rownames(gtex.counts)

4 Fitting the GoM Model

We use a wrapper function of the topics() function in the maptpx due to Matt Taddy (Taddy - International Conference on Artificial Intelligence and and 2012 2012).

As an example, we fit the topic model for k=4 on the GTEx V6 Brain data and save the GoM model output file to user-defined directory.

FitGoM(t(gtex.counts),
            K=4, tol=1,
            path_rda="../data/GTExV6Brain.FitGoM.rda")

One can also input a vector of clusters under nclus_vec as we do for a list of cluster numbers from \(2\) to \(7\) for Deng et al 2014 data.

FitGoM(t(deng.counts),
            K=2:7, tol=0.1,
            path_rda="../data/MouseDeng2014.FitGoM.rda")

5 Structure plot visualization

Now we perform the visualization for k=6 for the Deng et al 2014 data.

We load the GoM fit for k=6.

data("MouseDeng2014.FitGoM")
names(MouseDeng2014.FitGoM$clust_6)

## [1] "K"     "theta" "omega" "BF"    "D"

omega <- MouseDeng2014.FitGoM$clust_6$omega

We prepare the annotations for the visualization.

annotation <- data.frame(
  sample_id = paste0("X", c(1:NROW(omega))),
  tissue_label = factor(rownames(omega),
                        levels = rev( c("zy", "early2cell",
                                        "mid2cell", "late2cell",
                                        "4cell", "8cell", "16cell",
                                        "earlyblast","midblast",
                                         "lateblast") ) ) )

rownames(omega) <- annotation$sample_id;

Now we perform the visualization.

StructureGGplot(omega = omega,
                annotation = annotation,
                palette = RColorBrewer::brewer.pal(8, "Accent"),
                yaxis_label = "Development Phase",
                order_sample = TRUE,
                axis_tick = list(axis_ticks_length = .1,
                                 axis_ticks_lwd_y = .1,
                                 axis_ticks_lwd_x = .1,
                                 axis_label_size = 7,
                                 axis_label_face = "bold"))

In the above plot, the samples in each batch have been sorted by the proportional memebership of the most representative cluster in that batch. One can also use order_sample=FALSE for the un-ordered version, which retains the order as in the data (see Supplementary analysis for example).

Now we perform the Structure plot visualization for k=4 for GTEx V6 data for Brain samples .

We load the GoM fit for k=4.

data("GTExV6Brain.FitGoM")
omega <- GTExV6Brain.FitGoM$omega;
dim(omega)

## [1] 1259    4

colnames(omega) <- c(1:NCOL(omega))

We now prepare the annotations for visualization GTEx brain tissue results.

tissue_labels <- gtex.meta_data[,3];

annotation <- data.frame(
    sample_id = paste0("X", 1:length(tissue_labels)),
    tissue_label = factor(tissue_labels,
                          levels = rev(unique(tissue_labels) ) ) );

cols <- c("blue", "darkgoldenrod1", "cyan", "red")

Now we perform the visualization.

StructureGGplot(omega = omega,
                annotation= annotation,
                palette = cols,
                yaxis_label = "",
                order_sample = TRUE,
                split_line = list(split_lwd = .4,
                                  split_col = "white"),
                axis_tick = list(axis_ticks_length = .1,
                                 axis_ticks_lwd_y = .1,
                                 axis_ticks_lwd_x = .1,
                                 axis_label_size = 7,
                                 axis_label_face = "bold"))

6 Cluster Annotations

We extract the top genes driving each cluster using the ExtractTopFeatures functionality of the CountClust package. We first perform the cluster annotations from the GoM model fit with $k=6` on the single cell RNA-seq data due to Deng et al.

data("MouseDeng2014.FitGoM")
theta_mat <- MouseDeng2014.FitGoM$clust_6$theta;
top_features <- ExtractTopFeatures(theta_mat, top_features=100,
                                   method="poisson", options="min");
gene_list <- do.call(rbind, lapply(1:dim(top_features$indices)[1],
                        function(x) deng.gene_names[top_features$indices[x,]]))

We tabulate the top \(5\) genes for these \(6\) clusters.

tmp <- do.call(rbind, lapply(1:5, function(i) toString(gene_list[,i])))
rownames(tmp) <- paste("Cluster", c(1:5))
tmp %>%
  kable("html") %>%
  kable_styling()

We next perform the same for the topic model fit on the GTEx V6 Brain samples data with k=4 clusters.

data("GTExV6Brain.FitGoM")
theta_mat <- GTExV6Brain.FitGoM$theta;
top_features <- ExtractTopFeatures(theta_mat, top_features=100,
                                   method="poisson", options="min");
gene_list <- do.call(rbind, lapply(1:dim(top_features$indices)[1],
                        function(x) gtex.gene_names[top_features$indices[x,]]))

The top \(3\) genes (ensemble IDs) driving these \(4\) clusters.

tmp <- do.call(rbind, lapply(1:3, function(i) toString(gene_list[,i])))
rownames(tmp) <- paste("Cluster", c(1:3))
tmp %>%
  kable("html") %>%
  kable_styling()

7 Supplementary analysis

As an additional analysis, we apply the CountClust tools on another single-cell RNA-seq data from mouse spleen due to Jaitin et al 2014 (Jaitin et al. 2014). The data had technical effects in the form of amplification batch which the user may want to correct for.

We first install and load the data.

read.data3 = function() {
x = tempfile()
download.file(
'https://cdn.rawgit.com/jhsiao999/singleCellRNASeqMouseJaitinSpleen/master/data/MouseJaitinSpleen.rda',
destfile = x, quiet=TRUE)
z = get(load((x)))
return(z)
}

MouseJaitinSpleen <- read.data3()
## Alternatively
# devtools::install_github('jhsiao999/singleCellRNASeqMouseJaitinSpleen')

jaitin.counts <- Biobase::exprs(MouseJaitinSpleen)
jaitin.meta_data <- Biobase::pData(MouseJaitinSpleen)
jaitin.gene_names <- rownames(jaitin.counts)

Extracting the non-ERCC genes satisfying some quality measures.

ENSG_genes_index <- grep("ERCC", jaitin.gene_names, invert = TRUE)
jaitin.counts_ensg <- jaitin.counts[ENSG_genes_index, ]
filter_genes <- c("M34473","abParts","M13680","Tmsb4x",
                  "S100a4","B2m","Atpase6","Rpl23","Rps18",
                  "Rpl13","Rps19","H2-Ab1","Rplp1","Rpl4",
                  "Rps26","EF437368")
fcounts <- jaitin.counts_ensg[ -match(filter_genes, rownames(jaitin.counts_ensg)), ]
sample_counts <- colSums(fcounts)

filter_sample_index <- which(jaitin.meta_data$number_of_cells == 1 &
                              jaitin.meta_data$group_name == "CD11c+" &
                                 sample_counts > 600)
fcounts.filtered <- fcounts[,filter_sample_index];

We filter the metadata likewise.

jaitin.meta_data_filtered <- jaitin.meta_data[filter_sample_index, ]

We fit the GoM model for k=7 and plot the Structure plot visualization to show that the amplification batch indeed drives the clustering patterns.

StructureObj(t(fcounts),
            nclus_vec=7, tol=0.1,
             path_rda="../data/MouseJaitinSpleen.FitGoM.rda")

Load results of completed analysis.

data("MouseJaitinSpleen.FitGoM")
names(MouseJaitinSpleen.FitGoM$clust_7)

## [1] "K"     "theta" "omega" "BF"    "D"     "X"

omega <- MouseJaitinSpleen.FitGoM$clust_7$omega

amp_batch <- as.numeric(jaitin.meta_data_filtered[ , "amplification_batch"])
annotation <- data.frame(
    sample_id = paste0("X", c(1:NROW(omega)) ),
    tissue_label = factor(amp_batch,
                          levels = rev(sort(unique(amp_batch))) ) )

Visualize the sample expression profile.

StructureGGplot(omega = omega,
                annotation = annotation,
                palette = RColorBrewer::brewer.pal(9, "Set1"),
                yaxis_label = "Amplification batch",
                order_sample = FALSE,
                axis_tick = list(axis_ticks_length = .1,
                                 axis_ticks_lwd_y = .1,
                                 axis_ticks_lwd_x = .1,
                                 axis_label_size = 7,
                                 axis_label_face = "bold"))

It seems from the above Structure plot that amplification batch drives the clusters. To remove the effect of amplification batch, one can use. For this, we use the BatchCorrectedCounts() functionality of the package.

batchcorrect.fcounts <- BatchCorrectedCounts(t(fcounts.filtered),
                                          amp_batch, use_parallel = FALSE);
dim(batchcorrect.fcounts)

8 Acknowledgements

We would like to thank Deng et al and the GTEx Consortium for having making the data publicly available. We would like to thank Matt Taddy, Amos Tanay, Po Yuan Tung and Raman Shah for helpful discussions related to the project and the package.

9 Session Info

sessionInfo()

## R version 3.6.0 (2019-04-26)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.2 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.9-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.9-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] CountClust_1.12.0 ggplot2_3.1.1     usethis_1.5.0     devtools_2.0.2   
## [5] kableExtra_1.1.0  knitr_1.22        BiocStyle_2.12.0 
## 
## loaded via a namespace (and not attached):
##  [1] maptpx_1.9-5        nlme_3.1-139        fs_1.3.0           
##  [4] webshot_0.5.1       RColorBrewer_1.1-2  httr_1.4.0         
##  [7] rprojroot_1.3-2     tools_3.6.0         backports_1.1.4    
## [10] R6_2.4.0            vegan_2.5-4         lazyeval_0.2.2     
## [13] BiocGenerics_0.30.0 mgcv_1.8-28         colorspace_1.4-1   
## [16] permute_0.9-5       nnet_7.3-12         withr_2.1.2        
## [19] tidyselect_0.2.5    prettyunits_1.0.2   processx_3.3.0     
## [22] curl_3.3            compiler_3.6.0      cli_1.1.0          
## [25] rvest_0.3.3         Biobase_2.44.0      xml2_1.2.0         
## [28] desc_1.2.0          bookdown_0.9        slam_0.1-45        
## [31] scales_1.0.0        SQUAREM_2017.10-1   readr_1.3.1        
## [34] callr_3.2.0         stringr_1.4.0       digest_0.6.18      
## [37] rmarkdown_1.12      pkgconfig_2.0.2     htmltools_0.3.6    
## [40] sessioninfo_1.1.1   highr_0.8           limma_3.40.0       
## [43] rlang_0.3.4         rstudioapi_0.10     gtools_3.8.1       
## [46] dplyr_0.8.0.1       magrittr_1.5        modeltools_0.2-22  
## [49] Matrix_1.2-17       Rcpp_1.0.1          munsell_0.5.0      
## [52] ape_5.3             stringi_1.4.3       yaml_2.2.0         
## [55] MASS_7.3-51.4       flexmix_2.3-15      pkgbuild_1.0.3     
## [58] plyr_1.8.4          grid_3.6.0          parallel_3.6.0     
## [61] crayon_1.3.4        lattice_0.20-38     cowplot_0.9.4      
## [64] splines_3.6.0       hms_0.4.2           ps_1.3.0           
## [67] pillar_1.3.1        boot_1.3-22         reshape2_1.4.3     
## [70] stats4_3.6.0        pkgload_1.0.2       picante_1.8        
## [73] glue_1.3.1          evaluate_0.13       remotes_2.0.4      
## [76] BiocManager_1.30.4  testthat_2.1.1      gtable_0.3.0       
## [79] purrr_0.3.2         assertthat_0.2.1    xfun_0.6           
## [82] viridisLite_0.3.0   tibble_2.1.1        memoise_1.1.0      
## [85] cluster_2.0.9