plotHeatmap: Heatmap for showing clustering results and more

In clusterExperiment: Compare Clusterings for Single-Cell Sequencing

Description

Make heatmap with color scale from one matrix and hiearchical clustering of samples/features from another. Also built in functionality for showing the clusterings with the heatmap. Builds on aheatmap function of NMF package.

Usage

## S4 method for signature 'SingleCellExperiment'
plotHeatmap(data, isCount = FALSE, transFun = NULL, ...)

## S4 method for signature 'SummarizedExperiment'
plotHeatmap(data, isCount = FALSE, transFun = NULL, ...)

## S4 method for signature 'table'
plotHeatmap(data, ...)

## S4 method for signature 'ClusterExperiment'
plotHeatmap(
  data,
  clusterSamplesData = c("dendrogramValue", "hclust", "orderSamplesValue",
    "primaryCluster"),
  clusterFeaturesData = "var",
  nFeatures = NA,
  visualizeData = c("transformed", "centeredAndScaled", "original"),
  whichClusters = c("primary", "workflow", "all", "none"),
  colData = NULL,
  clusterFeatures = TRUE,
  nBlankLines = 2,
  colorScale,
  whichAssay = 1,
  ...
)

## S4 method for signature 'data.frame'
plotHeatmap(data, ...)

## S4 method for signature 'ExpressionSet'
plotHeatmap(data, ...)

## S4 method for signature 'matrixOrHDF5'
plotHeatmap(
  data,
  colData = NULL,
  clusterSamplesData = NULL,
  clusterFeaturesData = NULL,
  whColDataCont = NULL,
  clusterSamples = TRUE,
  showSampleNames = FALSE,
  clusterFeatures = TRUE,
  showFeatureNames = FALSE,
  colorScale = seqPal5,
  clusterLegend = NULL,
  alignColData = FALSE,
  unassignedColor = "white",
  missingColor = "grey",
  breaks = NA,
  symmetricBreaks = FALSE,
  capBreaksLegend = FALSE,
  isSymmetric = FALSE,
  overRideClusterLimit = FALSE,
  plot = TRUE,
  labelTracks = TRUE,
  ...
)

## S4 method for signature 'ClusterExperiment'
plotCoClustering(data, invert, saveDistance = FALSE, ...)

Arguments

data	data to use to determine the heatmap. Can be a matrix, ClusterExperiment, SingleCellExperiment or SummarizedExperiment object. The interpretation of parameters depends on the type of the input to data.
isCount	if transFun=NULL, then isCount=TRUE will determine the transformation as defined by function(x){log2(x+1)}, and isCount=FALSE will give a transformation function function(x){x}. Ignored if transFun=NULL. If object is of class ClusterExperiment, the stored transformation will be used and giving this parameter will result in an error.
transFun	a transformation function to be applied to the data. If the transformation applied to the data creates an error or NA values, then the function will throw an error. If object is of class ClusterExperiment, the stored transformation will be used and giving this parameter will result in an error.
...	for signature matrix, arguments passed to aheatmap. For the other signatures, passed to the method for signature matrix. Not all arguments can be passed to aheatmap effectively, see details.
clusterSamplesData	If data is a matrix, clusterSamplesData is either a matrix that will be used by hclust to define the hiearchical clustering of samples (e.g. normalized data) or a pre-existing dendrogram (of class dendrogram) that clusters the samples. If data is a ClusterExperiment object, clusterSamplesData should be either character or integers or logical which indicates how (and whether) the samples should be clustered (or gives indices of the order for the samples). See details.
clusterFeaturesData	If data is a matrix, either a matrix that will be used in hclust to define the hiearchical clustering of features (e.g. normalized data) or a pre-existing dendrogram that clusters the features. If data is a ClusterExperiment object, the input should be either character or integers indicating which features should be used (see details).
nFeatures	integer indicating how many features should be used (if clusterFeaturesData is 'var' or 'PCA').
visualizeData	either a character string, indicating what form of the data should be used for visualizing the data (i.e. for making the color-scale), or a data.frame/matrix with same number of samples as assay(data). If a new data.frame/matrix, any character arguments to clusterFeaturesData will be ignored.
whichClusters	argument that can be either numeric or character vector indicating the clusterings to be used. See details of getClusterIndex.
colData	If input to data is either a ClusterExperiment,or SummarizedExperiment object or SingleCellExperiment, then colData must index the colData stored as a DataFrame in colData slot of the object. Whether that data is continuous or not will be determined by the properties of colData (no user input is needed). If input to data is matrix, colData is a matrix of additional data on the samples to show above heatmap. In this case, unless indicated by whColDataCont, colData will be converted into factors, even if numeric. “-1” indicates the sample was not assigned to a cluster and gets color ‘unassignedColor’ and “-2“ gets the color 'missingColor'.
clusterFeatures	Logical as to whether to do hiearchical clustering of features (if FALSE, any input to clusterFeaturesData is ignored).
nBlankLines	Only applicable if input is ClusterExperiment object. Indicates the number of lines to put between groups of features if clusterFeaturesData gives groups of genes (see details and makeBlankData).
colorScale	palette of colors for the color scale of the heatmap.
whichAssay	numeric or character specifying which assay to use. See assay for details.
whColDataCont	Which of the colData columns are continuous and should not be converted to counts. NULL indicates no additional colData. Only used if data input is matrix.
clusterSamples	Logical as to whether to do hierarchical clustering of cells (if FALSE, any input to clusterSamplesData is ignored).
showSampleNames	Logical as to whether show sample names.
showFeatureNames	Logical as to whether show feature names.
clusterLegend	Assignment of colors to the clusters. If NULL, colData columns will be assigned colors internally. See details for more.
alignColData	Logical as to whether should align the colors of the colData (only if clusterLegend not given and colData is not NULL).
unassignedColor	color assigned to cluster values of '-1' ("unassigned").
missingColor	color assigned to cluster values of '-2' ("missing").
breaks	Either a vector of breaks (should be equal to length 52), or a number between 0 and 1, indicating that the breaks should be equally spaced (based on the range in the data) upto the ‘breaks’ quantile, see setBreaks
symmetricBreaks	logical as to whether the breaks created for the color scale should be symmetrical around 0
capBreaksLegend	logical as to whether the legend for the breaks should be capped. Only relevant if breaks is a value < 1, in which case if capBreaksLegend=TRUE, only the values between the quantiles requested will show in the color scale legend.
isSymmetric	logical. if TRUE indicates that the input matrix is symmetric. Useful when plotting a co-clustering matrix or other sample by sample matrices (e.g., correlation).
overRideClusterLimit	logical. Whether to override the internal limit that only allows 10 clusterings/annotations. If overridden, may result in incomprehensible errors from aheatmap. Only override this if you have a very large plotting device and want to see if aheatmap can render it.
plot	logical indicating whether to plot the heatmap. Mainly useful for package mantaince to avoid calls to aheatmap on unit tests that take a long time.
labelTracks	logical, whether to put labels next to the color tracks corresponding to the colData.
invert	logical determining whether the coClustering matrix should be inverted to be 1-coClustering for plotting. By default, if the diagonal elements are all zero, invert=TRUE, and otherwise invert=FALSE. If coClustering matrix is not a 0-1 matrix (e.g. if equal to a distance matrix output from clusterSingle, then the user should manually set this parameter to FALSE.)
saveDistance	logical. When the coClustering slot contains indices of the clusterings or a NxB set of clusterings, the hamming distance will be calculated before running the plot. This argument determines whether the ClusterExperiment object with that distance in coClustering slot should be returned (so as to avoid re-calculating it in the future) or not.

Details

The plotHeatmap function calls aheatmap to draw the heatmap. The main points of plotHeatmap are to 1) allow for different matrix inputs, separating out the color scale visualization and the clustering of the samples/features. 2) to visualize the clusters and meta data with the heatmap. The intended use case is to allow the user to visualize the original count scale of the data (on the log-scale), but create the hierarchical clustering on another, more appropriate dataset for clustering, such as normalized data. Similarly, some of the palettes in the package were developed assuming that the visualization might be on unscaled/uncentered data, rather than the residual from the mean of the gene, and thus palettes need to take on a greater range of relevant values so as to show meaningful comparisons with genes on very different scales.

If data is a ClusterExperiment object, visualizeData indicates what kind of transformation should be done to assay(data) for calculating the color scale. The features will be clustered based on these data as well. A different data.frame or matrix can be given for the visualization. For example, if the ClusterExperiment object contains normalized data, but the user wishes that the color scale be based on the log-counts for easier interpretation, visualizeData could be set to be the log2(counts + 1).

If data is a ClusterExperiment object, clusterSamplesData can be used to indicate the type of clustering for the samples. If equal to 'dendrogramValue' the dendrogram stored in data will be used; if dendrogram is missing, a new one will be created based on the primaryCluster of data using makeDendrogram, assuming no errors are created (if errors are created, then clusterSamplesData will be set to "primaryCluster"). If clusterSamplesData is equal to "hclust", then standard hierachical clustering of the transformed data will be used. If clusterSamplesData is equal to 'orderSamplesValue' no clustering of the samples will be done, and instead the samples will be ordered as in the slot orderSamples of data. If clusterSamplesData is equal to 'primaryCluster', again no clustering will be done, and instead the samples will be ordered based on grouping the samples to match the primaryCluster of data; however, if the primaryCluster of data is only one cluster or consists soley of -1/-2 values, clusterSamplesData will be set to "hclust". If clusterSamplesData is not a character value, clusterSamplesData can be a integer valued vector giving the order of the samples.

If data is a matrix, then colData is a data.frame of annotation data to be plotted above the heatmap and whColDataCont gives the index of the column(s) of this dataset that should be consider continuous. Otherwise the annotation data for colData will be forced into a factor (which will be nonsensical for continous data). If data is a ClusterExperiment object, colData should refer to a index or column name of the colData slot of data. In this case colData will be added to any choices of clusterings chosen by the whichClusters argument (if any). If both clusterings and sample data are chosen, the clusterings will be shown closest to data (i.e. on bottom).

If data is a ClusterExperiment object, clusterFeaturesData is not a dataset, but instead indicates which features should be shown in the heatmap. In this case clusterFeatures can be one of the following:

• "all" All rows/genes will be shown

• character giving dimensionality reductionShould match one of values saved in reducedDims slot or a builtin function in listBuiltInReducedDims(). nFeatures then gives the number of dimensions to show. The heatmap will then be of the dimension reduction vectors

• character giving filtering Should match one of values saved in filterStats slot or a builtin function in listBuiltInFilterStats(). nFeatures gives the number of genes to keep after filtering.

• character giving gene/row names

• vector of integers giving row indices

• a list of indices or rownamesThis is used to indicate that the features should be grouped according to the elements of the list, with blank (white) space between them (see makeBlankData for more details). In this case, no clustering is done of the features.

If breaks is a numeric value between 0 and 1, then breaks is assumed to indicate the upper quantile (on the log scale) at which the heatmap color scale should stop. For example, if breaks=0.9, then the breaks will evenly spaced up until the 0.9 upper quantile of data, and then all values after the 0.9 quantile will be absorbed by the upper-most color bin. This can help to reduce the visual impact of a few highly expressed genes (features).

Note that plotHeatmap calls aheatmap under the hood. This allows you to plot multiple heatmaps via par(mfrow=c(2,2)), etc. However, the dendrograms do not resize if you change the size of your plot window in an interactive session of R (this might be a problem for RStudio if you want to pop it out into a large window...). Also, plotting to a pdf adds a blank page; see help pages of aheatmap for how to turn this off.

clusterLegend takes the place of argument annColors from aheatmap for giving colors to the annotation on the heatmap. clusterLegend should be list of length equal to ncol(colData) with names equal to the colnames of colData. Each element of the list should be a either the format requested by aheatmap (a vector of colors with names corresponding to the levels of the column of colData), or should be format of the clusterLegend slot in a ClusterExperiment object. Color assignments to the rows/genes should also be passed via clusterLegend (assuming annRow is an argument passed to ...). If clusterFeaturesData is a named list describing groupings of genes then the colors for those groups can be given in clusterLegend under the name "Gene Group".

If you have a factor with many levels, it is important to note that aheatmap does not recycle colors across factors in the colData, and in fact runs out of colors and the remaining levels get the color white. Thus if you have many factors or many levels in those factors, you should set their colors via clusterLegend.

Many arguments can be passed on to aheatmap, however, some are set internally by plotHeatmap. In particular, setting the values of Rowv or Colv will cause errors. color in aheatmap is replaced by colorScale in plotHeatmap. The annCol to give annotation to the samples is replaced by the colData; moreover, the annColors option in aheatmap will also be set internally to give more vibrant colors than the default in aheatmap (for ClusterExperiment objects, these values can also be set in the clusterLegend slot ). Other options should be passed on to aheatmap, though they have not been all tested. Useful options include treeheight=0 to suppress plotting of the dendrograms, annLegend=FALSE to suppress the legend of factors shown beside columns/rows, and cexRow=0 or cexCol=0 to suppress plotting of row/column labels.

plotCoClustering is a convenience function to plot the heatmap of the co-clustering distance matrix from the coClustering slot of a ClusterExperiment object (either by calculating the hamming distance of the clusterings stored in the coClustering slot, or the distance stored in the coClustering slot if it has already been calculated.

Value

Returns (invisibly) a list with elements

• aheatmapOut The output from the final call of aheatmap.

• colData the annotation data.frame given to the argument annCol in aheatmap.

• clusterLegend the annotation colors given to the argument annColors aheatmap.

• breaks The breaks used for aheatmap, after adjusting for quantile.

Author(s)

Elizabeth Purdom

See Also

aheatmap, makeBlankData, showHeatmapPalettes, makeDendrogram, dendrogram

Examples

data(simData)

cl <- rep(1:3,each=100)
cl2 <- cl
changeAssign <- sample(1:length(cl), 80)
cl2[changeAssign] <- sample(cl[changeAssign])
ce <- ClusterExperiment(simCount, cl2, transformation=function(x){log2(x+1)})

#simple, minimal, example. Show counts, but cluster on underlying means
plotHeatmap(ce)

#assign cluster colors
colors <- bigPalette[20:23]
names(colors) <- 1:3
plotHeatmap(data=simCount, clusterSamplesData=simData,
colData=data.frame(cl), clusterLegend=list(colors))

#show two different clusters
anno <- data.frame(cluster1=cl, cluster2=cl2)
out <- plotHeatmap(simData, colData=anno)

#return the values to see format for giving colors to the annotations
out$clusterLegend

#assign colors to the clusters based on plotClusters algorithm
plotHeatmap(simData, colData=anno, alignColData=TRUE)

#assign colors manually
annoColors <- list(cluster1=c("black", "red", "green"),
cluster2=c("blue","purple","yellow"))

plotHeatmap(simData, colData=anno, clusterLegend=annoColors)

#give a continuous valued -- need to indicate columns
anno2 <- cbind(anno, Cont=c(rnorm(100, 0), rnorm(100, 2), rnorm(100, 3)))
plotHeatmap(simData, colData=anno2, whColDataCont=3)

#compare changing breaks quantile on visual effect
## Not run: 
par(mfrow=c(2,2))
plotHeatmap(simData, colorScale=seqPal1, breaks=1, main="Full length")
plotHeatmap(simData,colorScale=seqPal1, breaks=.99, main="0.99 Quantile Upper
Limit")
plotHeatmap(simData,colorScale=seqPal1, breaks=.95, main="0.95 Quantile Upper
Limit")
plotHeatmap(simData, colorScale=seqPal1, breaks=.90, main="0.90 Quantile
Upper Limit")

## End(Not run)

clusterExperiment documentation built on Feb. 11, 2021, 2 a.m.