plotScoreHeatmap {SingleR} | R Documentation

## Plot a score heatmap

### Description

Create a heatmap of the `SingleR` assignment scores across all cell-label combinations.

### Usage

    plotScoreHeatmap(
      results,
      cells.use = NULL,
      labels.use = NULL,
      clusters = NULL,
      show.labels = TRUE,
      show.pruned = FALSE,
      max.labels = 40,
      normalize = TRUE,
      cells.order = NULL,
      order.by = c("labels", "clusters"),
      scores.use = NULL,
      calls.use = 0,
      na.color = "gray30",
      cluster_cols = FALSE,
      annotation_col = NULL,
      show_colnames = FALSE,
      color = (grDevices::colorRampPalette(c("#D1147E", "white", "#00A44B")))(100),
      silent = FALSE,
      ...,
      grid.vars = list()
    )

### Arguments

`results` | A DataFrame containing the output from `SingleR`, `classifySingleR`, `combineCommonResults`, or `combineRecomputedResults`.
`cells.use` | Integer or string vector specifying the single cells to show. If `NULL`, all cells are presented.
`labels.use` | String vector indicating what labels to show. If `NULL`, all labels available in the target `results` are presented.
`clusters` | String vector or factor containing cell cluster assignments, to be shown as an annotation bar in the heatmap.
`show.labels` | Logical indicating whether the chosen labels of cells should be shown as an annotation bar.
`show.pruned` | Logical indicating whether the pruning status of the cell labels, as defined by `pruneScores`, should be shown as an annotation bar.
`max.labels` | Integer scalar specifying the maximum number of labels to show.
`normalize` | Logical specifying whether correlations should be normalized to lie in [0, 1].
`cells.order` | Integer or String vector specifying how to order the cells/columns of the heatmap. Regardless of `cells.use`, this input should be the the same length as the total number of cells. Subordinate to `cluster_cols`.
`order.by` | String providing the annotation to be used for cells/columns ordering. Can be "labels" (default) or "clusters" (when provided). Subordinate to `cells.order` and `cluster_cols`.
`scores.use` | Integer scalar specifying which scores to use. This can refer to any column index of `results$orig.results` to use scores from individual references of a combined prediction (see `?combine-predictions`), or to the top-level `results` which is indicated by the value 0. Alternatively, `scores.use` can be an integer vector containing multiple such column indices (or zero). In such cases, multiple heatmaps will be created showing multiple sets of scores. Default setting, `scores.use=NULL`, will create heatmaps for scores from both the top-level results and the individual references.
`calls.use` | Integer scalar specifying which labels to use, defaulting to those from the top-level `results` which is indicated by the value 0. However, this can also refer to any column index of `results$orig.results` to use labels from individual references of a combined prediction (see `?combine-predictions`). Alternatively, an integer vector of the same length as `scores.use`, specifying the labels to use in each heatmap generated by `scores.use`.
`na.color` | String specifying the color for non-calculated scores of combined `results`.
`annotation_col, cluster_cols, show_colnames, color, silent, ...` | Additional parameters for heatmap control passed to `pheatmap`.
`grid.vars` | A named list of extra variables to pass to `grid.arrange`, used when `scores.use` is of length greater than 1. If `NULL`, the function will not arrange plots on a grid and will instead output them as a list.

### Details

This function creates a heatmap containing the `SingleR` initial assignment scores for each cell (columns) to each reference label (rows). Users can then easily identify the high-scoring labels associated with each cell and/or cluster of cells.

If `show.labels=TRUE`, an annotation bar will be added to the heatmap indicating labels assigned to the cells. Note that scores shown in the heatmap are initial scores prior to the fine-tuning step, so the reported labels may not match up to the visual maximum for each cell in the heatmap.

If `max.labels` is less than the total number of unique labels, only the top labels are shown in the plot. Labels that were called most frequently are prioritized. Then remaining labels are selected based on:

- General case: Labels with max z-scores after per-cell centering and scaling of the scores matrix.

- Recomputed scores of combined predictions: Labels which were suggested most frequently by individual references.

### Value

One or more heatmaps of assignment scores, generated by `pheatmap`, are returned on the current graphics device. Or a list of such heatmaps are output if `scores.use` is of length greater than 1, and `grid.vars` is set to `NULL`.

### Working with combined results

When `results` are the output of a combined prediction (see `?combine-predictions`), `scores.use` and `calls.use` are used to indicate which prediction's scores or labels should be presented.

- `scores.use` sets which prediction's scores to create a heatmap for.

- `calls.use` sets which prediction's label (and pruning) calls to show as annotations above the heatmap.

Values of these inputs can be:

- 0: the top-level "combined" scores or calls.

- Any positive integer: indicates the index of an individual prediction within `results$orig.results`.

### Tweaking the output

Additional arguments can be passed to `pheatmap` for further tweaking of the heatmap. Particularly useful parameters are `show_colnames`, which can be used to display cell/cluster names; `treeheight_row`, which sets the width of the clustering tree; and `annotation_col`, which can be used to add extra annotation layers. Clustering, pruning and label annotations are automatically generated and appended to `annotation_col` when available.

### Normalization of colors

If `normalize=TRUE`, scores will be linearly adjusted for each cell so that the smallest score is 0 and the largest score is 1. This is followed by cubing of the adjusted scores to improve dynamic range near 1. Visually, the color scheme is changed to a blue-green-yellow scale.

The adjustment is intended to inflate differences between scores within a given cell for easier visualization. This is because the scores are often systematically shifted between cells, making the raw values difficult to directly compare. However, it may be somewhat misleading; fine-tuning may appear to assign a cell to a label with much lower score whereas the actual scores are much closer. It is for this reason that the color bar values are not shown as the absolute values of the score have little meaning.

Also note that this transformation is done after the choice of the top `max.labels` labels.

### Author(s)

Daniel Bunis, based on code by Dvir Aran.

### See Also

`SingleR`, to generate `scores`.

`pruneScores`, to remove low-quality labels based on the scores.

`pheatmap`, for additional tweaks to the heatmap.

`grid.arrange`, for tweaks to the how heatmaps are arranged when multiple are output together.

### Examples

    # Running the SingleR() example.
    example(SingleR, echo=FALSE)
    # Grab the original identities of the cells as mock clusters
    clusts <- g

    # Creating a heatmap with just the labels.
    plotScoreHeatmap(pred)

    # Creating a heatmap with clusters also displayed.
    plotScoreHeatmap(pred,
        clusters=clusts)

    # Creating a heatmap with whether cells were pruned displayed.
    plotScoreHeatmap(pred,
        show.pruned = TRUE)

    # We can also turn off the normalization with Normalize = FALSE
    plotScoreHeatmap(pred, clusters=clusts,
        normalize = FALSE)

    # To only show certain labels, you can use labels.use or max.labels
    plotScoreHeatmap(pred, clusters=clusts,
        labels.use = c("A","B","D"))
    plotScoreHeatmap(pred, clusters=clusts,
        max.labels = 4)

    # We can pass extra tweaks the heatmap as well
    plotScoreHeatmap(pred, clusters=clusts,
        fontsize_row = 20)
    plotScoreHeatmap(pred, clusters=clusts,
        treeheight_row = 15)
    plotScoreHeatmap(pred, clusters=clusts, cluster_col = TRUE,
        cutree_cols = 5)

    ### Multi-Reference Compatibility ###

    example(combineRecomputedResults, echo = FALSE)
    plotScoreHeatmap(combined)

    # 'scores.use' sets which particular run's scores to show, and can be multiple
    plotScoreHeatmap(combined,
        scores.use = 1)
    plotScoreHeatmap(combined,
        scores.use = c(0,2))

    # 'calls.use' adjusts which run's labels and pruning calls to display.
    plotScoreHeatmap(combined,
        calls.use = 1)

    # To have plots output in a grid rather than as separate pages, provide,
    # a list of inputs for gridExtra::grid.arrange() to 'grids.vars'.
    plotScoreHeatmap(combined,
        grid.vars = list(ncol = 1))

    # An empty list will use grid.arrange defaluts
    plotScoreHeatmap(combined,
        grid.vars = list())

[Package SingleR version 1.2.4 Index]