plotColData: Plot column metadata

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

Plot column metadata

Description

Plot column-level (i.e., cell) metadata in an SingleCellExperiment object.

Usage

plotColData(
  object,
  y,
  x = NULL,
  colour_by = color_by,
  shape_by = NULL,
  size_by = NULL,
  order_by = NULL,
  by_exprs_values = "logcounts",
  other_fields = list(),
  swap_rownames = NULL,
  color_by = NULL,
  point_fun = NULL,
  scattermore = FALSE,
  bins = NULL,
  summary_fun = "sum",
  hex = FALSE,
  by.assay.type = by_exprs_values,
  ...
)

Arguments

object	A SingleCellExperiment object containing expression values and experimental information.
y	String specifying the column-level metadata field to show on the y-axis. Alternatively, an AsIs vector or data.frame, see ?retrieveCellInfo.
x	String specifying the column-level metadata to show on the x-axis. Alternatively, an AsIs vector or data.frame, see ?retrieveCellInfo. If NULL, nothing is shown on the x-axis.
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.
other_fields	Additional cell-based fields to include in the data.frame, see ?"scater-plot-args" for details.
swap_rownames	Column name of rowData(object) to be used to identify features instead of rownames(object) when labelling plot elements.
color_by	Alias to colour_by.
point_fun	Function used to create a geom that shows individual cells. Should take ... args and return a ggplot2 geom. For example, point_fun=function(...) geom_quasirandom(...).
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 ?retrieveCellInfo for details (also alias by_exprs_values is accepted for this argument).
...	Additional arguments for visualization, see ?"scater-plot-args" for details.

Details

If y is continuous and x=NULL, a violin plot is generated. If x is categorical, a grouped violin plot will be generated, with one violin for each level of x. If x is continuous, a scatter plot will be generated.

If y is categorical and x is continuous, horizontal violin plots will be generated. If x is missing or categorical, rectangule plots will be generated where the area of a rectangle is proportional to the number of points for a combination of factors.

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)
colData(example_sce) <- cbind(colData(example_sce),
    perCellQCMetrics(example_sce))

plotColData(example_sce, y = "detected", x = "sum",
   colour_by = "Mutation_Status") + scale_x_log10()

plotColData(example_sce, y = "detected", x = "sum",
   colour_by = "Mutation_Status", size_by = "Gene_0001",
   shape_by = "Treatment") + scale_x_log10()

plotColData(example_sce, y = "Treatment", x = "sum",
   colour_by = "Mutation_Status") + scale_y_log10() # flipped violin.

plotColData(example_sce, y = "detected",
   x = "Cell_Cycle", colour_by = "Mutation_Status")
# With scattermore
plotColData(example_sce, x = "sum", y = "detected", scattermore = TRUE,
   point_size = 2)
# Bin to show point density
plotColData(example_sce, x = "sum", y = "detected", bins = 10)
# Bin to summarize value (default is sum)
plotColData(example_sce, x = "sum", y = "detected", bins = 10, colour_by = "total")

Alanocallaghan/scater documentation built on July 18, 2024, 10:58 p.m.