dittoHeatmap {dittoSeq}R Documentation

Outputs a heatmap of given genes

Description

Given a set of genes, cells/samples, and metadata names for column annotations, this function will retrieve the expression data for those genes and cells, and the annotation data for those cells. It will then utilize these data to make a heatmap using the pheatmap function of the pheatmap package.

Usage

dittoHeatmap(
  object,
  genes = getGenes(object, assay),
  cells.use = NULL,
  annot.by = NULL,
  order.by = .default_order(object, annot.by),
  main = NA,
  cell.names.meta = NULL,
  assay = .default_assay(object),
  slot = .default_slot(object),
  heatmap.colors = colorRampPalette(c("blue", "white", "red"))(50),
  scaled.to.max = FALSE,
  heatmap.colors.max.scaled = colorRampPalette(c("white", "red"))(25),
  annot.colors = c(dittoColors(), dittoColors(1)[seq_len(7)]),
  annotation_col = NULL,
  annotation_colors = NULL,
  data.out = FALSE,
  highlight.genes = NULL,
  show_colnames = isBulk(object),
  show_rownames = TRUE,
  scale = "row",
  cluster_cols = isBulk(object),
  border_color = NA,
  legend_breaks = NA,
  breaks = NA,
  ...
)

Arguments

object

A Seurat or SingleCellExperiment object to work with

genes

String vector, c("gene1","gene2","gene3",...) = the list of genes to put in the heatmap. If not provided, defaults to all genes of the object / assay.

cells.use

String vector of cells'/samples' names which should be included.

Alternatively, a Logical vector, the same length as the number of cells in the object, which sets which cells to include.

For the typically easier logical method, provide USE in colnames(object)[USE] OR object@cell.names[USE].

annot.by

String name of any metadata slots containing how the cells/samples should be annotated.

order.by

Single string or numeric vector which sets the ordering of cells/samples. Can be the name of a gene, or metadata slot. Alternatively, can be a numeric vector of length equal to the total number of cells/samples in object.

main

String that sets the title for the heatmap.

cell.names.meta

quoted "name" of a meta.data slot to use for naming the columns instead of using the raw cell/sample names.

assay, slot

single strings or integer that set which expression data to use. See gene for more information about how defaults for these are filled in when not provided.

heatmap.colors

the colors to use within the heatmap when (default setting) scaled.to.max is set to FALSE. Default is a ramp from navy to white to red with 50 slices.

scaled.to.max

Logical, FALSE by default, which sets whether expression shoud be scaled between [0, 1]. This is recommended for single-cell datasets as they are generally enriched in 0s.

heatmap.colors.max.scaled

the colors to use within the heatmap when scaled.to.max is set to TRUE. Default is a ramp from white to red with 25 slices.

annot.colors

String (color) vector where each color will be assigned to an individual annotation in the generated annotation bars.

data.out

Logical. When set to TRUE, changes the output from the heatmat itself, to a list containing all arguments that would have be passed to pheatmap for heatmap generation. (Can be useful for troubleshooting or customization.)

highlight.genes

String vector of genes whose names you would like to show. Only these genes will be named in the resulting heatmap.

show_colnames, show_rownames, scale, annotation_col, annotation_colors

arguments passed to pheatmap that are over-ruled by certain dittoHeatmap functionality:

  • show_colnames (& labels_col): if cell.names.meta is provided, pheatmaps's labels_col is utilized to show these names and show_colnames parameter is set to TRUE.

  • show_rownames (& labels_row): if feature names are provided to highlight.genes, pheatmap's labels_row is utilized to show just these features' names and show_rownames parameter is set to TRUE.

  • scale: when parameter scaled.to.max is set to true, pheatmap's scale is set to "none" and the max scaling is performed prior to the pheatmap call.

  • annotation_col: Can be provided as normal by the user and any metadata given to annot.by will then be appended.

  • annotation_colors: dittoHeatmap fills this complicated-to-produce input in automatically by pulling from the colors given to annot.colors, but it is possible to set all or some manually. dittoSeq will just fill any left out annotations. Format is a named (annotation_col & annotation_row colnames) character vector list where individual color values can also be named.

cluster_cols, border_color, legend_breaks, breaks, ...

other arguments passed to pheatmap directly.

Details

This function serves as a wrapper for creating heatmaps from bulk or single-cell RNAseq data with pheatmap, by essentially automating the data extraction and annotation building steps.

The function will extract the expression matrix for a set of genes and/or an optional subset of cells / samples to use via cells.use, This matrix is either left as is, default (for scaling within the ultimate call to pheatmap), or if scaled.to.max = TRUE, is scaled by dividing each row by its maximum value.

When provided with a set of metadata slot names to use for building annotations (with the annot.by input), the relevant metadata is retrieved from the object and compiled into a pheatmap-ready annotation_col input. The input annot.colors is used to establish the set of colors that should be used for building a pheatmap-ready annotation_colors input as well, unless such an input has been provided by the user. See below for further details.

Value

A pheatmap object.

Alternatively, if data.out was set to TRUE, a list containing all arguments that would have be passed to pheatmap to generate such a heatmap.

Many additional characteristics of the plot can be adjusted using discrete inputs

Customized annotations

In typical operation, dittoHeatmap pulls metadata annotations given to annot.by to build a pheatmap-annotation_col input, then it uses the colors provided to annot.colors to create the pheatmap-annotation_colors input which sets the annotation coloring. Specifically...

To customize colors or add additional column or row annotations, users can also provide annotation_colors, annotation_col, or annotation_row pheatmap-inputs directly. General structure is described below, but see pheatmap for additional details and examples.

Author(s)

Daniel Bunis

See Also

pheatmap, for how to add additional heatmap tweaks.

metaLevels for helping to create manual annotation_colors inputs. This function universally checks the options/levels of a string, factor (filled only by default), or numerical metadata.

Examples

# dittoSeq handles bulk and single-cell data quit similarly.
# The SingleCellExperiment object structure is used for both,
# but all functions can be used similarly directly on Seurat
# objects as well.

example(importDittoBulk, echo = FALSE)
myRNA
scRNA <- setBulk(myRNA, FALSE)

# Pick a set of genes
genes <- getGenes(myRNA)[1:30]

# Make a heatmap with cells/samples annotated by their clusters
dittoHeatmap(myRNA, genes,
    annot.by = "clustering")

# For single-cell data, you will typically have more cells than can be
# clustered quickly. Thus, cell clustering is turned off by default for
# single-cell data.
dittoHeatmap(scRNA, genes,
    annot.by = "clustering")

# Using the 'order.by' input:
#   ordering by a useful metadata or gene is generally more helpful
#   For single-cell data, order.by defaults to the first element given to
#     annot.by.
#   For bulk data, order.by must be set separately.
dittoHeatmap(myRNA, genes,
    annot.by = "clustering",
    order.by = "clustering")

# When there are many cells, showing names becomes less useful.
#   Names can be turned off with the show_colnames parameter.
dittoHeatmap(myRNA, genes,
    annot.by = "groups",
    order.by = "groups",
    show_colnames = FALSE)

# Additionally, it is recommended for single-cell data that the parameter
#   scaled.to.max be set to TRUE, or scale be "none" and turned off altogether,
#   because these data are generally enriched for zeros that otherwise get
#   scaled to a negative value.
dittoHeatmap(myRNA, genes, annot.by = "groups",
    order.by = "groups", show_colnames = FALSE,
    scaled.to.max = TRUE)


[Package dittoSeq version 1.0.2 Index]