plotGroupedHeatmap: Plot heatmap of group-level expression averages
In scater: Single-Cell Analysis Toolkit for Gene Expression Data in R

Description Usage Arguments Details Value Author(s) See Also Examples

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

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

`object`	A SingleCellExperiment object.
`features`	A character vector of row names, a logical vector of integer vector of indices specifying rows of `object` to show in the heatmap.
`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 for colouring in the heatmap.
`center`	A logical scalar indicating whether each row should have its mean expression centered at zero 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.
`symmetric`	A logical scalar specifying whether the default `zlim` should be symmetric around zero. If `TRUE`, the maximum absolute value of `zlim` will be computed and multiplied by `c(-1, 1)` to redefine `zlim`.
`color`	A vector of colours specifying the palette to use for mapping expression values to colours. This defaults to the default setting in `pheatmap`.
`swap_rownames`	String containing the field of `rowData(object)` to be used to identify features instead of `rownames(object)` when labelling plot elements.
`...`	Additional arguments to pass to `pheatmap`.

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 batchCorrectedAverages 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.

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

Aaron Lun

pheatmap, for the underlying function.

plotHeatmap, for a per-cell heatmap.

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, symmetric=TRUE)

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