Runs consensus clustering across subsamples, algorithms, and number of clusters (k).

  reps = 10,
  algorithms = NULL,
  k.method = NULL,
  nmf.method = c("brunet", "lee"),
  hc.method = "average",
  distance = "euclidean",
  cons.funs = c("kmodes", "majority", "CSPA", "LCE", "LCA"),
  sim.mat = c("cts", "srs", "asrs"), = c("none", "full", "sampled"),
  min.var = 1,
  seed = 1,
  trim = FALSE,
  reweigh = FALSE,
  n = 5,
  evaluate = TRUE,
  plot = FALSE, = NULL,
  progress = TRUE



data matrix with rows as samples and columns as variables


number of clusters (k) requested; can specify a single integer or a range of integers to compute multiple k


number of subsamples


vector of clustering algorithms for performing consensus clustering. Must be any number of the following: "nmf", "hc", "diana", "km", "pam", "ap", "sc", "gmm", "block", "som", "cmeans", "hdbscan". A custom clustering algorithm can be used.


determines the method to choose k when no reference class is given. When is not NULL, k is the number of distinct classes of Otherwise the input from k.method chooses k. The default is to use the PAC to choose the best k(s). Specifying an integer as a user-desired k will override the best k chosen by PAC. Finally, specifying "all" will produce consensus results for all k. The "all" method is implicitly performed when there is only one k used.


specify NMF-based algorithms to run. By default the "brunet" and "lee" algorithms are called. See NMF::nmf() for details.


agglomeration method for hierarchical clustering. The the "average" method is used by default. Seestats::hclust() for details.


a vector of distance functions. Defaults to "euclidean". Other options are given in stats::dist(). A custom distance function can be used.


consensus functions to use. Current options are "kmodes" (k-modes), "majority" (majority voting), "CSPA" (Cluster-based Similarity Partitioning Algorithm), "LCE" (linkage clustering ensemble), "LCA" (latent class analysis)


similarity matrix; choices are "cts", "srs", "asrs".

Prepare the data on the "full" dataset, the "sampled" dataset, or "none" (default).


minimum variability measure threshold used to filter the feature space for only highly variable features. Only features with a minimum variability measure across all samples greater than min.var will be used. If type = "conventional", the standard deviation is the measure used, and if type = "robust", the MAD is the measure used.


random seed for knn imputation reproducibility


logical; if TRUE, algorithms that score low on internal indices will be trimmed out


logical; if TRUE, after trimming out poor performing algorithms, each algorithm is reweighed depending on its internal indices.


an integer specifying the top n algorithms to keep after trimming off the poor performing ones using Rank Aggregation. If the total number of algorithms is less than n no trimming is done.


logical; if TRUE (default), validity indices are returned. Internal validity indices are always computed. If is not NULL, then external validity indices will also be computed.


logical; if TRUE, graph_all is called and a summary evaluation heatmap of ranked algorithms vs. internal validity indices is plotted as well.

reference class


logical; should a progress bar be displayed?


A list with the following elements


raw clustering ensemble object


clustering ensemble object with knn imputation used on E


flattened ensemble object with remaining missing entries imputed by majority voting


final clustering assignment from the diverse clustering ensemble method


if evaluate = TRUE, shows cluster evaluation indices; otherwise NULL


There are three ways to handle the input data before clustering via argument The default is to use the raw data as-is ("none"). Or, we can enact prepare_data() on the full dataset ("full"), or the bootstrap sampled datasets ("sampled").


Aline Talhouk, Derek Chiu


#> Attaching package: ‘dplyr’
#> The following object is masked from ‘package:MASS’:
#>     select
#> The following object is masked from ‘package:testthat’:
#>     matches
#> The following object is masked from ‘package:Biobase’:
#>     combine
#> The following objects are masked from ‘package:BiocGenerics’:
#>     combine, intersect, setdiff, union
#> The following objects are masked from ‘package:stats’:
#>     filter, lag
#> The following objects are masked from ‘package:base’:
#>     intersect, setdiff, setequal, union
dat <- hgsc[1:100, 1:50] <- strsplit(rownames(dat), "_") %>%
  purrr::map_chr(2) %>%
  factor() %>%
dice.obj <- dice(dat, nk = 4, reps = 5, algorithms = "hc", cons.funs =
"kmodes", =, progress = FALSE)
str(dice.obj, max.level = 2)
#> List of 5
#>  $ E       : int [1:100, 1:5, 1, 1] 1 1 NA NA NA 1 1 NA 1 NA ...
#>   ..- attr(*, "dimnames")=List of 4
#>  $ Eknn    : int [1:100, 1:5, 1, 1] 1 1 1 1 1 1 1 1 1 3 ...
#>   ..- attr(*, "dimnames")=List of 4
#>  $ Ecomp   : num [1:100, 1:5, 1] 1 1 1 1 1 1 1 1 1 3 ...
#>   ..- attr(*, "dimnames")=List of 3
#>  $ clusters: int [1:100, 1:2] 4 3 1 3 3 4 1 3 2 4 ...
#>   ..- attr(*, "dimnames")=List of 2
#>  $ indices :List of 5
#>   ..$ k   : int 4
#>   ..$ pac :'data.frame':	1 obs. of  2 variables:
#>   ..$ ii  :List of 1
#>   ..$ ei  :List of 1
#>   ..$ trim:List of 5