Contents

1 Introduction

This vignette describes how each of the included clustering methods was applied to the collection of data sets in order to generate the clustering result summaries provided with the package. It also shows how to apply a new clustering method to the included data sets, to generate results that can be compared to those already included.

2 Applying a new clustering algorithm to a provided data set

The code below describes how we applied each of the included clustering methods to the data sets for our paper (Duò, Robinson, and Soneson 2018). The apply_*() functions, describing how the respective clustering methods were run, are available from the GitHub repository corresponding to the publication. In order to apply a new clustering algorithm to one of the data sets using the same framework, it is necessary to generate a function with the same format. The input arguments to this function should be:

The function should return a list with three elements:

If the method does not allow specification of the desired number of clusters, but has another parameter affecting the resolution, this can be accommodated as well (see the solution for Seurat in the code below).

First, load the package and define the data set and clustering method to use (note that in order to apply a method named <method>, there has to be a function named apply_<method>(), with the above specifications, available in the workspace).

suppressPackageStartupMessages({
  library(DuoClustering2018)
})

scename <- "sce_filteredExpr10_Koh"
sce <- sce_filteredExpr10_Koh()
## see ?DuoClustering2018 and browseVignettes('DuoClustering2018') for documentation
## loading from cache
method <- "PCAHC"

Next, define the list of hyperparameter values. The package contains the hyperparameter values for the methods included in our paper.

## Load parameter files. General dataset and method parameters as well as
## dataset/method-specific parameters
params <- duo_clustering_all_parameter_settings_v2()[[paste0(scename, "_", 
                                                             method)]]
## see ?DuoClustering2018 and browseVignettes('DuoClustering2018') for documentation
## loading from cache
params
## $nPC
## [1] 30
## 
## $range_clusters
##  [1]  2  3  4  5  6  7  8  9 10 11 12 13 14 15

Finally, define the number of times to apply the clustering method (for each value of the number of clusters), and run the clustering across a range of imposed numbers of clusters (defined in the parameter list).

## Set number of times to run clustering for each k
n_rep <- 5

## Run clustering
set.seed(1234)
L <- lapply(seq_len(n_rep), function(i) {  ## For each run
  cat(paste0("run = ", i, "\n"))
  if (method == "Seurat") {
    tmp <- lapply(params$range_resolutions, function(resolution) {  
      ## For each resolution
      cat(paste0("resolution = ", resolution, "\n"))
      ## Run clustering
      res <- get(paste0("apply_", method))(sce = sce, params = params, 
                                           resolution = resolution)
      
      ## Put output in data frame
      df <- data.frame(dataset = scename, 
                       method = method, 
                       cell = names(res$cluster),
                       run = i,
                       k = length(unique(res$cluster)),
                       resolution = resolution,
                       cluster = res$cluster,
                       stringsAsFactors = FALSE, row.names = NULL)
      tm <- data.frame(dataset = scename, 
                       method = method,
                       run = i, 
                       k = length(unique(res$cluster)),
                       resolution = resolution,
                       user.self = res$st[["user.self"]],
                       sys.self = res$st[["sys.self"]],
                       user.child = res$st[["user.child"]],
                       sys.child = res$st[["sys.child"]],
                       elapsed = res$st[["elapsed"]],
                       stringsAsFactors = FALSE, row.names = NULL)
      kest <- data.frame(dataset = scename, 
                         method = method,
                         run = i, 
                         k = length(unique(res$cluster)),
                         resolution = resolution,
                         est_k = res$est_k,
                         stringsAsFactors = FALSE, row.names = NULL)
      list(clusters = df, timing = tm, kest = kest)
    })  ## End for each resolution
  } else {
    tmp <- lapply(params$range_clusters, function(k) {  ## For each k
      cat(paste0("k = ", k, "\n"))
      ## Run clustering
      res <- get(paste0("apply_", method))(sce = sce, params = params, k = k)
      
      ## Put output in data frame
      df <- data.frame(dataset = scename, 
                       method = method, 
                       cell = names(res$cluster),
                       run = i,
                       k = k,
                       resolution = NA,
                       cluster = res$cluster,
                       stringsAsFactors = FALSE, row.names = NULL)
      tm <- data.frame(dataset = scename, 
                       method = method,
                       run = i, 
                       k = k,
                       resolution = NA,
                       user.self = res$st[["user.self"]],
                       sys.self = res$st[["sys.self"]],
                       user.child = res$st[["user.child"]],
                       sys.child = res$st[["sys.child"]],
                       elapsed = res$st[["elapsed"]],
                       stringsAsFactors = FALSE, row.names = NULL)
      kest <- data.frame(dataset = scename, 
                         method = method,
                         run = i, 
                         k = k,
                         resolution = NA,
                         est_k = res$est_k,
                         stringsAsFactors = FALSE, row.names = NULL)
      list(clusters = df, timing = tm, kest = kest)
    })  ## End for each k
  }
  
  ## Summarize across different values of k
  assignments <- do.call(rbind, lapply(tmp, function(w) w$clusters))
  timings <- do.call(rbind, lapply(tmp, function(w) w$timing))
  k_estimates <- do.call(rbind, lapply(tmp, function(w) w$kest))
  list(assignments = assignments, timings = timings, k_estimates = k_estimates)
})  ## End for each run

## Summarize across different runs
assignments <- do.call(rbind, lapply(L, function(w) w$assignments))
timings <- do.call(rbind, lapply(L, function(w) w$timings))
k_estimates <- do.call(rbind, lapply(L, function(w) w$k_estimates))

## Add true group for each cell
truth <- data.frame(cell = as.character(rownames(colData(sce))),
                    trueclass = as.character(colData(sce)$phenoid),
                    stringsAsFactors = FALSE)
assignments$trueclass <- truth$trueclass[match(assignments$cell, truth$cell)]

## Combine results
res <- list(assignments = assignments, timings = timings,
            k_estimates = k_estimates)

df <- dplyr::full_join(res$assignments %>%
                         dplyr::select(dataset, method, cell, run, k, 
                                       resolution, cluster, trueclass),
                       res$k_estimates %>%
                         dplyr::select(dataset, method, run, k, 
                                       resolution, est_k)
) %>% dplyr::full_join(res$timings %>% dplyr::select(dataset, method, run, k,
                                                     resolution, elapsed))

The resulting df data frames can then be combined across data sets, filterings and methods and used as input to the provided plotting functions.

3 Session info

sessionInfo()
## R version 4.2.1 (2022-06-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.5 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.16-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.16-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              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] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] plyr_1.8.7                  ExperimentHub_2.6.0        
##  [3] AnnotationHub_3.6.0         BiocFileCache_2.6.0        
##  [5] dbplyr_2.2.1                tidyr_1.2.1                
##  [7] dplyr_1.0.10                DuoClustering2018_1.16.0   
##  [9] SingleCellExperiment_1.20.0 SummarizedExperiment_1.28.0
## [11] Biobase_2.58.0              GenomicRanges_1.50.0       
## [13] GenomeInfoDb_1.34.0         IRanges_2.32.0             
## [15] S4Vectors_0.36.0            BiocGenerics_0.44.0        
## [17] MatrixGenerics_1.10.0       matrixStats_0.62.0         
## [19] BiocStyle_2.26.0           
## 
## loaded via a namespace (and not attached):
##  [1] bitops_1.0-7                  bit64_4.0.5                  
##  [3] filelock_1.0.2                httr_1.4.4                   
##  [5] tools_4.2.1                   bslib_0.4.0                  
##  [7] utf8_1.2.2                    R6_2.5.1                     
##  [9] DBI_1.1.3                     colorspace_2.0-3             
## [11] withr_2.5.0                   tidyselect_1.2.0             
## [13] gridExtra_2.3                 bit_4.0.4                    
## [15] curl_4.3.3                    compiler_4.2.1               
## [17] cli_3.4.1                     DelayedArray_0.24.0          
## [19] labeling_0.4.2                bookdown_0.29                
## [21] sass_0.4.2                    scales_1.2.1                 
## [23] rappdirs_0.3.3                stringr_1.4.1                
## [25] digest_0.6.30                 rmarkdown_2.17               
## [27] XVector_0.38.0                pkgconfig_2.0.3              
## [29] htmltools_0.5.3               highr_0.9                    
## [31] fastmap_1.1.0                 rlang_1.0.6                  
## [33] ggthemes_4.2.4                RSQLite_2.2.18               
## [35] shiny_1.7.3                   farver_2.1.1                 
## [37] jquerylib_0.1.4               generics_0.1.3               
## [39] jsonlite_1.8.3                mclust_6.0.0                 
## [41] RCurl_1.98-1.9                magrittr_2.0.3               
## [43] GenomeInfoDbData_1.2.9        Matrix_1.5-1                 
## [45] Rcpp_1.0.9                    munsell_0.5.0                
## [47] fansi_1.0.3                   viridis_0.6.2                
## [49] lifecycle_1.0.3               stringi_1.7.8                
## [51] yaml_2.3.6                    zlibbioc_1.44.0              
## [53] grid_4.2.1                    blob_1.2.3                   
## [55] promises_1.2.0.1              crayon_1.5.2                 
## [57] lattice_0.20-45               Biostrings_2.66.0            
## [59] KEGGREST_1.38.0               magick_2.7.3                 
## [61] knitr_1.40                    pillar_1.8.1                 
## [63] reshape2_1.4.4                glue_1.6.2                   
## [65] BiocVersion_3.16.0            evaluate_0.17                
## [67] BiocManager_1.30.19           png_0.1-7                    
## [69] vctrs_0.5.0                   httpuv_1.6.6                 
## [71] gtable_0.3.1                  purrr_0.3.5                  
## [73] assertthat_0.2.1              cachem_1.0.6                 
## [75] ggplot2_3.3.6                 xfun_0.34                    
## [77] mime_0.12                     xtable_1.8-4                 
## [79] later_1.3.0                   viridisLite_0.4.1            
## [81] tibble_3.1.8                  AnnotationDbi_1.60.0         
## [83] memoise_2.0.1                 ellipsis_0.3.2               
## [85] interactiveDisplayBase_1.36.0

References

Duò, A, MD Robinson, and D Soneson. 2018. “A Systematic Performance Evaluation of Clustering Methods for Single-Cell RNA-seq Data.” F1000Research 7: 1141.