plotHeatmap {clusterExperiment} | R Documentation

## Heatmap for showing clustering results and more

### 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)

[Package clusterExperiment version 2.10.1 Index]