plotReducedDim: Plot reduced dimensions

In davismcc/scater: Single-Cell Analysis Toolkit for Gene Expression Data in R

Plot reduced dimensions

Description

Plot cell-level reduced dimension results stored in a SingleCellExperiment object.

Usage

plotReducedDim(
  object,
  dimred,
  ncomponents = 2,
  percentVar = NULL,
  colour_by = color_by,
  shape_by = NULL,
  size_by = NULL,
  order_by = NULL,
  by_exprs_values = "logcounts",
  text_by = NULL,
  text_size = 5,
  text_colour = text_color,
  label_format = c("%s %i", " (%i%%)"),
  other_fields = list(),
  text_color = "black",
  color_by = NULL,
  swap_rownames = NULL,
  point.padding = NA,
  force = 1,
  rasterise = FALSE,
  scattermore = FALSE,
  bins = NULL,
  summary_fun = "sum",
  hex = FALSE,
  by.assay.type = by_exprs_values,
  ...
)

Arguments

object	A SingleCellExperiment object.
dimred	A string or integer scalar indicating the reduced dimension result in reducedDims(object) to plot.
ncomponents	A numeric scalar indicating the number of dimensions to plot, starting from the first dimension. Alternatively, a numeric vector specifying the dimensions to be plotted.
percentVar	A numeric vector giving the proportion of variance in expression explained by each reduced dimension. Only expected to be used in PCA settings, e.g., in the plotPCA function.
colour_by	Specification of a column metadata field or a feature to colour by, see the by argument in ?retrieveCellInfo for possible values.
shape_by	Specification of a column metadata field or a feature to shape by, see the by argument in ?retrieveCellInfo for possible values.
size_by	Specification of a column metadata field or a feature to size by, see the by argument in ?retrieveCellInfo for possible values.
order_by	Specification of a column metadata field or a feature to order points by, see the by argument in ?retrieveCellInfo for possible values.
by_exprs_values	Alias for by.assay.type.
text_by	String specifying the column metadata field with which to add text labels on the plot. This must refer to a categorical field, i.e., coercible into a factor. Alternatively, an AsIs vector or data.frame, see ?retrieveCellInfo.
text_size	Numeric scalar specifying the size of added text.
text_colour	String specifying the colour of the added text.
label_format	Character vector of length 2 containing format strings to use for the axis labels. The first string expects a string containing the result type (e.g., "PCA") and an integer containing the component number, while the second string shows the rounded percentage of variance explained and is only relevant when this information is provided in object.
other_fields	Additional cell-based fields to include in the data.frame, see ?"scater-plot-args" for details.
text_color	Alias to text_colour.
color_by	Alias to colour_by.
swap_rownames	Column name of rowData(object) to be used to identify features instead of rownames(object) when labelling plot elements.
point.padding, force	See ?ggrepel::geom_text_repel.
rasterise	Whether to rasterise the points in the plot with rasterise. To control the dpi, set options(ggrastr.default.dpi), for example options(ggrastr.default.dpi=300).
scattermore	Logical, whether to use the scattermore package to greatly speed up plotting a large number of cells. Use point_size = 0 for the most performance gain.
bins	Number of bins, can be different in x and y, to bin and summarize the points and their values, to avoid overplotting. If NULL (default), then the points are plotted without binning. Only used when both x and y are numeric.
summary_fun	Function to summarize the feature value of each point (e.g. gene expression of each cell) when the points binned, defaults to sum. Can be either the name of the function or the function itself.
hex	Logical, whether to use geom_hex.
by.assay.type	A string or integer scalar specifying which assay to obtain expression values from, for use in point aesthetics - see the assay.type argument in ?retrieveCellInfo.
...	Additional arguments for visualization, see ?"scater-plot-args" for details.

Details

If ncomponents is a scalar equal to 2, a scatterplot of the first two dimensions is produced. If ncomponents is greater than 2, a pairs plots for the top dimensions is produced.

Alternatively, if ncomponents is a vector of length 2, a scatterplot of the two specified dimensions is produced. If it is of length greater than 2, a pairs plot is produced containing all pairwise plots between the specified dimensions.

The text_by option will add factor levels as labels onto the plot, placed at the median coordinate across all points in that level. This is useful for annotating position-related metadata (e.g., clusters) when there are too many levels to distinguish by colour. It is only available for scatterplots.

Value

A ggplot object

Note

Arguments shape_by and size_by are ignored when scattermore = TRUE. Using scattermore is only recommended for very large datasets to speed up plotting. Small point size is also recommended. For larger point size, the point shape may be distorted. Also, when scattermore = TRUE, the point_size argument works differently.

Author(s)

Davis McCarthy, with modifications by Aaron Lun

Examples

example_sce <- mockSCE()
example_sce <- logNormCounts(example_sce)

example_sce <- runPCA(example_sce, ncomponents=5)
plotReducedDim(example_sce, "PCA")
plotReducedDim(example_sce, "PCA", colour_by="Cell_Cycle")
plotReducedDim(example_sce, "PCA", colour_by="Gene_0001")

plotReducedDim(example_sce, "PCA", ncomponents=5)
plotReducedDim(example_sce, "PCA", ncomponents=5, colour_by="Cell_Cycle",
    shape_by="Treatment")

# Use scattermore
plotPCA(example_sce, ncomponents = 4, scattermore = TRUE, point_size = 3)

# Bin to show point density
plotPCA(example_sce, bins = 10)
# Bin to summarize values (default is sum)
plotPCA(example_sce, bins = 10, colour_by = "Gene_0001")

davismcc/scater documentation built on July 19, 2024, 2:01 a.m.