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,
      scale = FALSE,
      zlim = NULL,
      color = NULL,
      color_columns_by = NULL,
      column_annotation_colors = list(),
      color_rows_by = NULL,
      row_annotation_colors = list(),
      order_columns_by = NULL,
      by_exprs_values = exprs_values,
      show_colnames = FALSE,
      cluster_cols = is.null(order_columns_by),
      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.
`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.
`center` | A logical scalar indicating whether each feature should have its mean expression centered at zero prior to plotting.
`scale` | A logical scalar specifying whether each feature should have its expression values scaled to have 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.
`color_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.
`column_annotation_colors` | A named list of color scales to be used for the column annotations specified in `color_columns_by`. Names should be character values present in `color_columns_by`, If a color scale is not specified for a particular annotation, a default color scale is chosen. The full list of colour maps is passed to `pheatmap` as the `annotation_colours` argument.
`color_rows_by` | Similar to `color_columns_by` but for rows rather than columns. Each entry of the list can be any acceptable input to the `by` argument in `?retrieveFeatureInfo`.
`row_annotation_colors` | Similar to `column_annotation_colors` but relating to row annotation rather than column annotation.
`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 `color_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`.
`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.

### 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 avoids the need to set `color_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)

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

[Package scater version 1.22.0 Index]