R: Find sets of samples that stay together across clusterings

makeConsensus,matrix,missing-method {clusterExperiment}

R Documentation

Find sets of samples that stay together across clusterings

Description

Find sets of samples that stay together across clusterings in order to define a new clustering vector.

Usage

## S4 method for signature 'matrix,missing'
makeConsensus(x, whichClusters, proportion,
  clusterFunction = "hierarchical01", propUnassigned = 0.5, minSize = 5,
  ...)

## S4 method for signature 'ClusterExperiment,numeric'
makeConsensus(x, whichClusters,
  eraseOld = FALSE, clusterLabel = "makeConsensus", ...)

## S4 method for signature 'ClusterExperiment,character'
makeConsensus(x, whichClusters, ...)

## S4 method for signature 'ClusterExperiment,missing'
makeConsensus(x, whichClusters, ...)

Arguments

`x`	a matrix or `ClusterExperiment` object.
`whichClusters`	argument that can be either numeric or character value indicating the clusters to be used. If numeric, gives the indices of the `clusterMatrix` to return; this can also be used to defined an ordering for the clusterings (as relevant). `whichClusters` can be a character value identifying the `clusterTypes` to be used, or if not matching `clusterTypes` then `clusterLabels`; alternatively `whichClusters` can be either 'all' or 'workflow' or 'primary' to indicate choosing all clusterings or choosing all `workflowClusters` clusterings or choosing the 'primary' clustering, respectively. If missing, the entire matrix of all clusterings is returned.
`proportion`	The proportion of times that two sets of samples should be together in order to be grouped into a cluster (if <1, passed to mainClustering via alpha = 1 - proportion)
`clusterFunction`	the clustering to use (passed to `mainClustering`); currently must be of type '01'.
`propUnassigned`	samples with greater than this proportion of assignments equal to '-1' are assigned a '-1' cluster value as a last step (only if proportion < 1)
`minSize`	minimum size required for a set of samples to be considered in a cluster because of shared clustering, passed to `mainClustering`
`...`	arguments to be passed on to the method for signature `matrix,missing`.
`eraseOld`	logical. Only relevant if input `x` is of class `ClusterExperiment`. If TRUE, will erase existing workflow results (clusterMany as well as mergeClusters and makeConsensus). If FALSE, existing workflow results will have "`_i`" added to the clusterTypes value, where `i` is one more than the largest such existing workflow clusterTypes.
`clusterLabel`	a string used to describe the type of clustering. By default it is equal to "makeConsensus", to indicate that this clustering is the result of a call to makeConsensus. However, a more informative label can be set (see vignette).

Details

This function was previously called combineMany (versions <= 2.0.0). combineMany is still available, but is considered defunct and users should update their code accordingly.

The function tries to find a consensus cluster across many different clusterings of the same samples. It does so by creating a nSamples x nSamples matrix of the percentage of co-occurance of each sample and then calling mainClustering to cluster the co-occurance matrix. The function assumes that '-1' labels indicate clusters that are not assigned to a cluster. Co-occurance with the unassigned cluster is treated differently than other clusters. The percent co-occurance is taken only with respect to those clusterings where both samples were assigned. Then samples with more than propUnassigned values that are '-1' across all of the clusterings are assigned a '-1' regardless of their cluster assignment.

The method calls mainClustering on the proportion matrix with clusterFunction as the 01 clustering algorithm, alpha=1-proportion, minSize=minSize, and evalClusterMethod=c("average"). See help of mainClustering for more details.

Value

If x is a matrix, a list with values

clustering vector of cluster assignments, with "-1" implying unassigned
percentageShared a nSample x nSample matrix of the percent co-occurance across clusters used to find the final clusters. Percentage is out of those not '-1'
noUnassignedCorrection a vector of cluster assignments before samples were converted to '-1' because had >propUnassigned '-1' values (i.e. the direct output of the mainClustering output.)

If x is a ClusterExperiment, a ClusterExperiment object, with an added clustering of clusterTypes equal to makeConsensus and the percentageShared matrix stored in the coClustering slot.

Examples

data(simData)

cl <- clusterMany(simData,nReducedDims=c(5,10,50),  reduceMethod="PCA",
clusterFunction="pam", ks=2:4, findBestK=c(FALSE), removeSil=TRUE,
subsample=FALSE)

#make names shorter for plotting
clMat <- clusterMatrix(cl)
colnames(clMat) <- gsub("TRUE", "T", colnames(clMat))
colnames(clMat) <- gsub("FALSE", "F", colnames(clMat))
colnames(clMat) <- gsub("k=NA,", "", colnames(clMat))

#require 100% agreement -- very strict
clCommon100 <- makeConsensus(clMat, proportion=1, minSize=10)

#require 70% agreement based on clustering of overlap
clCommon70 <- makeConsensus(clMat, proportion=0.7, minSize=10)

oldpar <- par()
par(mar=c(1.1, 12.1, 1.1, 1.1))
plotClusters(cbind("70%Similarity"=clCommon70$clustering, clMat,
"100%Similarity"=clCommon100$clustering), axisLine=-2)

#method for ClusterExperiment object
clCommon <- makeConsensus(cl, whichClusters="workflow", proportion=0.7,
minSize=10)
plotClusters(clCommon)
par(oldpar)

[Package clusterExperiment version 2.2.0 Index]