plotDots {scater}R Documentation

Create a dot plot of expression values

Description

Create a dot plot of expression values for a grouping of cells, where the size and color of each dot represents the proportion of detected expression values and the average expression, respectively, for each feature in each group of cells.

Usage

plotDots(
  object,
  features,
  group = NULL,
  block = NULL,
  exprs_values = "logcounts",
  detection_limit = 0,
  zlim = NULL,
  color = NULL,
  max_detected = NULL,
  other_fields = list(),
  by_exprs_values = exprs_values,
  swap_rownames = NULL,
  center = FALSE,
  scale = FALSE,
  low_color = NULL,
  high_color = NULL,
  max_ave = 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.

group

String specifying the field of colData(object) containing the grouping factor, e.g., cell types or clusters. Alternatively, any value that can be used in the by argument to retrieveCellInfo.

block

String specifying the field of colData(object) containing a blocking factor (e.g., batch of origin). Alternatively, any value that can be used in the by argument to retrieveCellInfo.

exprs_values

A string or integer scalar indicating which assay of object should be used as expression values.

detection_limit

Numeric scalar providing the value above which observations are deemed to be expressed.

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.

max_detected

Numeric value specifying the cap on the proportion of detected expression values.

other_fields

Additional feature-based fields to include in the data.frame, see ?"scater-plot-args" for details. Note that any AsIs vectors or data.frames must be of length equal to nrow(object), not features.

by_exprs_values

A string or integer scalar specifying which assay to obtain expression values from, for entries of other_fields.

swap_rownames

Column name of rowData(object) to be used to identify features instead of rownames(object) when labelling plot elements.

center

A logical scalar indicating whether each feature should have its mean expression (specifically, the mean of averages across all groups) centered at zero prior to plotting.

scale

A logical scalar specifying whether each row should have its average expression values scaled to unit variance prior to plotting.

low_color, high_color, max_ave

Deprecated arguments.

Details

This implements a Seurat-style “dot plot” that creates a dot for each feature (row) in each group of cells (column). The proportion of detected expression values and the average expression for each feature in each group of cells is visualized efficiently using the size and colour, respectively, of each dot. If block is specified, batch-corrected averages for each group are computed with correctGroupSummary.

Some caution is required during interpretation due to the difficulty of simultaneously interpreting both size and color. For example, if we colored by z-score on a conventional blue-white-red color axis, a gene that is downregulated in a group of cells would show up as a small blue dot. If the background color was also white, this could be easily mistaken for a gene that is not downregulated at all. We suggest choosing a color scale that remains distinguishable from the background color at all points. Admittedly, that is easier said than done as many color scales will approach a lighter color at some stage, so some magnifying glasses may be required.

We can also cap the color and size scales using zlim and max_detected, respectively. This aims to preserve resolution for low-abundance genes by preventing domination of the scales by high-abundance features.

Value

A ggplot object containing a dot plot.

Author(s)

Aaron Lun

See Also

plotExpression and plotHeatmap, for alternatives to visualizing group-level expression values.

Examples

sce <- mockSCE()
sce <- logNormCounts(sce)

plotDots(sce, features=rownames(sce)[1:10], group="Cell_Cycle")
plotDots(sce, features=rownames(sce)[1:10], group="Cell_Cycle", center=TRUE)
plotDots(sce, features=rownames(sce)[1:10], group="Cell_Cycle", scale=TRUE)
plotDots(sce, features=rownames(sce)[1:10], group="Cell_Cycle", center=TRUE, scale=TRUE)

plotDots(sce, features=rownames(sce)[1:10], group="Treatment", block="Cell_Cycle")


[Package scater version 1.20.1 Index]