plotClustersTable: Plot heatmap of cross-tabs of 2 clusterings

In epurdom/clusterExperiment: Compare Clusterings for Single-Cell Sequencing

Plot heatmap of cross-tabs of 2 clusterings

Description

Plot heatmap of cross-tabulations of two clusterings

Usage

## S4 method for signature 'ClusterExperiment'
plotClustersTable(
  object,
  whichClusters,
  ignoreUnassigned = FALSE,
  margin = NA,
  ...
)

## S4 method for signature 'table'
plotClustersTable(
  object,
  plotType = c("heatmap", "bubble"),
  main = "",
  xlab = NULL,
  ylab = NULL,
  legend = TRUE,
  cluster = FALSE,
  clusterLegend = NULL,
  sizeTable = NULL,
  ...
)

## S4 method for signature 'ClusterExperiment'
tableClusters(
  object,
  whichClusters = "primary",
  useNames = TRUE,
  tableMethod = c("intersect", "union"),
  ...
)

## S4 method for signature 'table,table'
bubblePlot(
  propTable,
  sizeTable,
  gridColor = rgb(0, 0, 0, 0.05),
  maxCex = 8,
  cexFactor,
  ylab,
  xlab,
  propLabel = "Value of %",
  legend = TRUE,
  las = 2,
  colorScale = RColorBrewer::brewer.pal(11, "Spectral")[-6]
)

Arguments

object	ClusterExperiment object (or matrix with table result)
whichClusters	argument that can be either numeric or character vector indicating the clusterings to be used. See details of getClusterIndex.
ignoreUnassigned	logical as to whether to ignore unassigned clusters in the plotting. This means they will also be ignored in the calculations of the proportions (if margin not NA).
margin	if NA, the actual counts from tableClusters will be plotted. Otherwise, prop.table will be called and the argument margin will be passed to prop.table to determine whether proportions should be calculated. If '1', then the proportions in the rows sum to 1, if '2' the proportions in the columns sum to 1. If 'NULL' then the proportion across the entire matrix will sum to 1. An additional option has been added so that if you set margin=0, the entry displayed in each cell will be the proportion equal to the size of the intersection over the size of the union of the clusters (a Jaccard similarity between the clusters), in which case each entry is a value between 0 and 1 but no combination of the entries sum to 1.
...	arguments passed on to plotHeatmap or bubblePlot depending on choice of plotType. Note that these functions take different arguments so that switching from one to the other may not take all arguments. In particular bubblePlot calls plot while plotHeatmap calls NMF{aheatmap}.
plotType	type of plot. If "heatmap", then a heatmap will be created of the values of the contingency table of the two clusters (calculated as determined by the argument "margin") using plotHeatmap. If "bubble", then a plot will be created using bubblePlot, which will create circles for each cell of the contingencey table whose size corresponds to the number of samples shared and the color based on the value of the proportion (as chosen by the argument margin).
main	title of plot, passed to plotHeatmap or to the argument propLabel in bubblePlot
xlab	label for labeling clustering on the x-axis. If NULL, will determine names. If set to NA no label for clustering on the x-axis will be plotted (to turn off legend of the clusterings in heatmap, set legend=FALSE).
ylab	label for labeling clustering on the y-axis. If NULL, will determine names. If set to NA no label for clustering on the y-axis will be plotted (to turn off legend of the clusterings in heatmap, set legend=FALSE).
legend	whether to draw legend along top (bubble plot) or the color legend (heatmap)
cluster	logical, whether to cluster the rows and columns of the table. Passed to arguments clusterFeatures AND clusterSamples of plotHeatmap.
clusterLegend	list in clusterLegend format that gives colors for the clusters tabulated.
sizeTable	table of sizes (only for use in bubblePlot or plotType="bubble"). See details.
useNames	for tableClusters, whether the output should be tabled with names (useNames=TRUE) or ids (useNames=FALSE)
tableMethod	the type of table calculation to perform. "intersect" refers to the standard contingency table (table), where each entry of the resulting table is the number of objects in both clusters. "union" instead gives for each entry the number of objects that are in the union of both clusters.
propTable	table of proportions (bubblePlot))
gridColor	color for grid lines (bubblePlot))
maxCex	largest value of cex for any point (others will scale proportionally smaller) (bubblePlot)).
cexFactor	factor to multiple by to get values of circles. If missing, finds value automatically, namely by using the maxCex value default. Overrides value of maxCex. (bubblePlot))
propLabel	the label to go with the legend of the color of the bubbles/circles
las	the value for the las value in the call to axis in labeling the clusters in the bubble plot. Determines whether parallel or perpindicular labels to the axis (see par).
colorScale	the color scale for the values of the proportion table

Details

For plotClustersTable applied to the class table, sizeTable is passed to bubblePlot to indicate the size of the circle. If sizeTable=NULL, then it is assumed that the object argument is the table of counts and both the propTable and sizeTable are set to the same value (hence turning off the coloring of the circle/bubbles). This is equivalent effect to the margin=NA option of plotClustersTable applied to the ClusterExperiment class.

Note that the cluster labels in plotClustersTable and tableClusters are converted to "proper" R names via make.names. This is because tableClusters calls the R function table, which makes this conversion

For plotClustersTable, whichClusters should define 2 clusters, while for tableClusters it can indicate arbitrary number.

bubblePlot is mainly used internally by plotClustersTable but is made public for users who want more control and to allow documentation of the arguments. bubblePlot plots a circle for each intersection of two clusters, where the color of the circle is based on the value in propTable and the size of the circle is based on the value in sizeTable. If propTable is equal to sizeTable, then the propTable is ignored and the coloring of the circles is not performed, only the adjusting of the size of the circles based on the total size. The size is determined by setting the cex value of the point as $sqrt(sizeTable[i,j])/sqrt(max(sizeTable))*cexFactor$.

Value

tableClusters returns an object of class table (see table).

plotClustersTables returns invisibly the plotted proportion table. In particular, this is the result of applying prop.table to the results of tableClusters (after removing unclustered samples if ignoreUnassigned=TRUE).

Author(s)

Kelly Street, Elizabeth Purdom

See Also

plotHeatmap

table

prop.table

Examples

#clustering using pam: try using different dimensions of pca and different k
data(simData)

cl <- clusterMany(simData, nReducedDims=c(5, 10, 50), reducedDim="PCA",
clusterFunction="pam", ks=2:4, findBestK=c(TRUE,FALSE),
removeSil=c(TRUE,FALSE), makeMissingDiss=TRUE)
#give arbitrary names to clusters for demonstration
cl<-renameClusters(cl,value=letters[1:nClusters(cl)[1]],whichCluster=1)
tableClusters(cl,whichClusters=1:2)
#show options of margin in heatmap format:
par(mfrow=c(2,3))
plotClustersTable(cl,whichClusters=1:2, margin=NA, legend=FALSE,
  ignoreUnassigned=TRUE)
plotClustersTable(cl,whichClusters=1:2, margin=0, legend=FALSE,
  ignoreUnassigned=TRUE)
plotClustersTable(cl,whichClusters=1:2, margin=1, legend=FALSE,
  ignoreUnassigned=TRUE)
plotClustersTable(cl,whichClusters=1:2, margin=2, legend=FALSE,
  ignoreUnassigned=TRUE)
plotClustersTable(cl,whichClusters=1:2, margin=NULL, legend=FALSE,
  ignoreUnassigned=TRUE)

#show options of margin in bubble format:
par(mfrow=c(2,3))
plotClustersTable(cl,whichClusters=1:2, margin=NA, 
   ignoreUnassigned=TRUE, plotType="bubble")
plotClustersTable(cl,whichClusters=1:2, margin=0,
   ignoreUnassigned=TRUE, plotType="bubble")
plotClustersTable(cl,whichClusters=1:2, margin=1,
   ignoreUnassigned=TRUE, plotType="bubble")
plotClustersTable(cl,whichClusters=1:2, margin=2,
   ignoreUnassigned=TRUE, plotType="bubble")
plotClustersTable(cl,whichClusters=1:2, margin=NULL,
   ignoreUnassigned=TRUE, plotType="bubble")

epurdom/clusterExperiment documentation built on April 28, 2024, 8:17 p.m.