Merge clusters based on dendrogram
Description
Takes an input of hierarchical clusterings of clusters and returns estimates of number of proportion of nonnull and merges those below a certain cutoff.
Usage
1 2 3 4 5 6 7 8 9 10  ## S4 method for signature 'matrix'
mergeClusters(x, cl, dendro = NULL,
mergeMethod = c("none", "adjP", "locfdr", "MB", "JC"),
plotType = c("none", "all", "mergeMethod", "adjP", "locfdr", "MB", "JC"),
cutoff = 0.1, doPlot = TRUE, isCount = TRUE, ...)
## S4 method for signature 'ClusterExperiment'
mergeClusters(x, eraseOld = FALSE,
isCount = FALSE, mergeMethod = "none", plotType = "all",
clusterLabel = "mergeClusters", ...)

Arguments
x 
data to perform the test on. It can be a matrix or a

cl 
A numeric vector with cluster assignments to compare to. “1” indicates the sample was not assigned to a cluster. 
dendro 
dendrogram providing hierarchical clustering of clusters in cl;
The default for matrix (NULL) is to recalculate it with the given (x, cl)
pair. If x is a 
mergeMethod 
method for calculating proportion of nonnull that will be used to merge clusters (if 'none', no merging will be done). See details for description of methods. 
plotType 
what type of plotting of dendrogram. If 'all', then all the estimates of proportion nonnull will be plotted; if 'mergeMethod', then only the value used in the merging is plotted for each node. 
cutoff 
minimimum value required for NOT merging a cluster, i.e. two clusters with the proportion of DE below cutoff will be merged. Must be a value between 0, 1, where lower values will make it harder to merge clusters. 
doPlot 
logical as to whether to plot the dendrogram (overrides

isCount 
logical as to whether input data is a count matrix. See details. 
... 
for signature 
eraseOld 
logical. Only relevant if input 
clusterLabel 
a string used to describe the type of clustering. By default it is equal to "mergeClusters", to indicate that this clustering is the result of a call to mergeClusters. 
Details
If isCount=TRUE
, and the input is a matrix,
log2(count + 1)
will be used for makeDendrogram
and the
original data with voom correction will be used in
getBestFeatures
). If input is
ClusterExperiment
, then setting isCount=TRUE
also means
that the log2(1+count) will be used as the transformation, like for
the matrix case as well as the voom calculation, and will NOT use the
transformation stored in the object. If FALSE, then transform(x) will be
given to the input and will be used for both makeDendrogram
and
getBestFeatures
, with no voom correction.
"JC" refers to the method of Ji and Cai (2007), and implementation
of "JC" method is copied from code available on Jiashin Ji's website,
December 16, 2015
(http://www.stat.cmu.edu/~jiashun/Research/software/NullandProp/). "locfdr"
refers to the method of Efron (2004) and is implemented in the package
locfdr
. "MB" refers to the method of Meinshausen and Buhlmann
(2005) and is implemented in the package howmany
. "adjP"
refers to the proportion of genes that are found significant based on a FDR
adjusted pvalues (method "BH") and a cutoff of 0.05.
If mergeMethod
is not equal to 'none' then the plotting will
indicate where the clusters will be merged (assuming plotType
is not 'none').
Value
If 'x' is a matrix, it returns (invisibly) a list with elements
clustering
a vector of length equal to ncol(x) giving the integervalued cluster ids for each sample. "1" indicates the sample was not clustered.oldClToNew
A table of the old cluster labels to the new cluster labels.propDE
A table of the proportions that are DE on each node.originalClusterDendro
The dendrogram on which the merging was based (based on the original clustering).
If 'x' is a ClusterExperiment
, it returns a new
ClusterExperiment
object with an additional clustering based on the
merging. This becomes the new primary clustering.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16  data(simData)
#create a clustering, for 8 clusters (truth was 3)
cl<clusterSingle(simData, clusterFunction="pam", subsample=FALSE,
sequential=FALSE, clusterDArgs=list(k=8))
#make dendrogram
cl < makeDendrogram(cl)
#merge clusters with plotting. Note argument 'use.edge.length' can improve
#readability
merged < mergeClusters(cl, plot=TRUE, plotType="all",
mergeMethod="adjP", use.edge.length=FALSE)
#compare merged to original
table(primaryCluster(cl), primaryCluster(merged))
