plotGroupedHeatmap {scater} | R Documentation

## Plot heatmap of group-level expression averages

### Description

Create a heatmap of average expression values for each group of cells and specified features in a SingleCellExperiment object.

### Usage

    plotGroupedHeatmap(
      object,
      features,
      group,
      block = NULL,
      columns = NULL,
      exprs_values = "logcounts",
      center = FALSE,
      scale = FALSE,
      zlim = NULL,
      color = NULL,
      swap_rownames = NULL,
      symmetric = NULL,
      ...
    )

### Arguments

`object` | A SingleCellExperiment object.
`features` | A character vector of row names, a logical vector, or integer vector of indices specifying rows of `object` to visualize.
`group` | String specifying the field of `colData(object)` containing the grouping factor, e.g., cell types or clusters. Alternatively, any value that can be used in the `by` argument to `retrieveCellInfo`.
`block` | String specifying the field of `colData(object)` containing a blocking factor (e.g., batch of origin). Alternatively, any value that can be used in the `by` argument to `retrieveCellInfo`.
`columns` | A vector specifying the subset of columns in `object` to use when computing averages.
`exprs_values` | A string or integer scalar indicating which assay of `object` should be used as expression values.
`center` | A logical scalar indicating whether each feature should have its mean expression (specifically, the mean of averages across all groups) centered at zero prior to plotting.
`scale` | A logical scalar specifying whether each row should have its average expression values scaled to unit variance prior to plotting.
`zlim` | A numeric vector of length 2, specifying the upper and lower bounds for color mapping of expression values. Values outside this range are set to the most extreme color. If `NULL`, it defaults to the range of the expression matrix. If `center=TRUE`, this defaults to the range of the centered expression matrix, made symmetric around zero.
`color` | A vector of colours specifying the palette to use for increasing expression. This defaults to viridis if `center=FALSE`, and the the `"RdYlBu"` color palette from `brewer.pal` otherwise.
`swap_rownames` | Column name of `rowData(object)` to be used to identify features instead of `rownames(object)` when labelling plot elements.
`symmetric` | Deprecated and ignored.
`...` | Additional arguments to pass to `pheatmap`.

### Details

This function shows the average expression values for each group of cells on a heatmap, as defined using the `group` factor. A per-group visualization can be preferable to a per-cell visualization when dealing with large number of cells or groups with different size. If `block` is also specified, the block effect is regressed out of the averages with `correctGroupSummary` prior to visualization.

Setting `center=TRUE` is useful for examining log-fold changes of each group's expression profile from the average across all groups. This avoids issues with the entire row appearing a certain colour because the gene is highly/lowly expressed across all cells.

Setting `zlim` preserves the dynamic range of colours in the presence of outliers. Otherwise, the plot may be dominated by a few genes, which will “flatten” the observed colours for the rest of the heatmap.

### Value

A heatmap is produced on the current graphics device. The output of `pheatmap` is invisibly returned.

### Author(s)

Aaron Lun

### See Also

`pheatmap`, for the underlying function.

`plotHeatmap`, for a per-cell heatmap.

### Examples

    example_sce <- mockSCE()
    example_sce <- logNormCounts(example_sce)
    example_sce$Group <- paste0(example_sce$Treatment, "+", example_sce$Mutation_Status)

    plotGroupedHeatmap(example_sce, features=rownames(example_sce)[1:10],
        group="Group")

    plotGroupedHeatmap(example_sce, features=rownames(example_sce)[1:10],
        group="Group", center=TRUE)

    plotGroupedHeatmap(example_sce, features=rownames(example_sce)[1:10],
        group="Group", block="Cell_Cycle", center=TRUE)

[Package scater version 1.22.0 Index]