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

- The cells can be ordered in a set way using the `order.by` input.

  Such ordering happens by default for single-cell RNAseq data when any metadata are provided to `annot.by` as it is often unfeasible to cluster thousands of cells.

- A plot title can be added with `main`.

- Gene or cell/sample names can be hidden with `show_rownames` and `show_colnames`, respectively, or...

  - Particular genes can also be selected for labeling using the `highlight.genes` input.

  - Names of all cells/samples can be replaced with the contents of a metadata slot using the `cell.names.meta` input.

- Additional tweaks are possible through use of `pheatmap` inputs which will be directly passed through. Some examples of useful `pheatmap` parameters are:

  - `cluster_cols` and `cluster_rows` for controlling clustering. Note: cluster_cols will always be over-written to be `FALSE` when the input `order.by` is used above.

  - `treeheight_row` and `treeheight_col` for setting how large the trees on the side/top should be drawn.

  - `cutree_col` and `cutree_row` for spliting the heatmap based on kmeans clustering

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

- colors for the values of discrete metadata are pulled from the start of the `annot.colors` vector, in the order that they are given to `annot.by`

- colors for the values of continuous metadata are pulled from the end of the `annot.colors` vector, in the order that they are given to `annot.by`

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.

- `annotation_col` = a data.frame with rownames of the barcodes/names of all cells/samples in the dataset & columns representing annotations. Names of columns are used as the annotation titles. *dittoSeq will append any `annot.by` annotations to this dataframe.

- `annotation_row` = a data.frame with rownames of the genes/feature of the dataset & columns representing annotations. Names of columns are used as the annotation titles.

- `annotation_colors` = a named list of string (color) vectors. Vectors must be named by the row or column annotation title that they are associated with. Optionally, individual colors can be named with the values that they should be associated with.

  Partial `annotation_colors` lists (containing vectors for only certain annotations) will have colors for left out annotations filled in automatically. For such filling, `annot.colors` are pulled for column annotations first, then for row annotations.

### 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]