plotHeatmap {scater} | R Documentation

## Plot heatmap of gene expression values

### Description

Create a heatmap of expression values for each cell and specified features in a SingleCellExperiment object.

### Usage

    plotHeatmap(
      object,
      features,
      columns = NULL,
      exprs_values = "logcounts",
      center = FALSE,
      zlim = NULL,
      symmetric = FALSE,
      color = NULL,
      colour_columns_by = NULL,
      order_columns_by = NULL,
      by_exprs_values = exprs_values,
      show_colnames = FALSE,
      cluster_cols = is.null(order_columns_by),
      ...
    )

### Arguments

`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.
`columns` | A vector specifying the subset of columns in `object` to show as columns in the heatmap. Also specifies the column order if `cluster_cols=FALSE` and `order_columns_by=NULL`. By default, all columns are used.
`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 the expression values. This winsorizes the expression matrix prior to plotting (but after centering, if `center=TRUE`). 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`.
`colour_columns_by` | A list of values specifying how the columns should be annotated with colours. Each entry of the list can be any acceptable input to the `by` argument in `?retrieveCellInfo`. A character vector can also be supplied and will be treated as a list of strings.
`order_columns_by` | A list of values specifying how the columns should be ordered. Each entry of the list can be any acceptable input to the `by` argument in `?retrieveCellInfo`. A character vector can also be supplied and will be treated as a list of strings. This argument is automatically appended to `colour_columns_by`.
`by_exprs_values` | A string or integer scalar specifying which assay to obtain expression values from, for colouring of column-level data - see the `exprs_values` argument in `?retrieveCellInfo`.
`show_colnames, cluster_cols, ...` | Additional arguments to pass to `pheatmap`.

### Details

Setting `center=TRUE` is useful for examining log-fold changes of each cell's expression profile from the average across all cells. 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.

Setting `order_columns_by` is useful for automatically ordering the heatmap by one or more factors of interest, e.g., cluster identity. This the need to set `colour_columns_by`, `cluster_cols` and `columns` to achieve the same effect.

### Value

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

### Author(s)

Aaron Lun

### See Also

`pheatmap`

### Examples

    example_sce <- mockSCE()
    example_sce <- logNormCounts(example_sce)

    plotHeatmap(example_sce, features=rownames(example_sce)[1:10])

    plotHeatmap(example_sce, features=rownames(example_sce)[1:10],
        center=TRUE, symmetric=TRUE)

    plotHeatmap(example_sce, features=rownames(example_sce)[1:10],
        colour_columns_by=c("Mutation_Status", "Cell_Cycle"))

[Package scater version 1.16.2 Index]