scater-vis-var {scater}R Documentation

Variable selection for visualization

Description

A number of scater functions accept a SingleCellExperiment object and extract (meta)data from it for use in a plot. These values are then used on the x- or y-axes (e.g., plotColData) or for tuning visual parameters, e.g., colour_by, shape_by, size_by. This page describes how the selection of these values can be controlled by the user, by passing appropriate values to the arguments of the desired plotting function.

When plotting by cells

Here, we assume that each visual feature of interest (e.g., point or line) corresponds to a cell in the SingleCellExperiment object sce. We will also assume that the user wants to change the colour of each feature according to the cell (meta)data. To do so, the user can pass as an argument:

The same logic applies for other visualization parameters such as shape_by and size_by. Other arguments may also use the same scheme, but this depends on the context; see the documentation for each function for details. In particular, if an argument explicitly refers to a metadata field, any names for the character string will be ignored. Similarly, a character vector of length > 1 is not allowed for an argument that explicitly refers to expression values.

When plotting by features

Here, we assume that each visual feature of interest (e.g., point or line) corresponds to a feature in the SingleCellExperiment object sce. The scheme is mostly the same as described above, with a few differences:

Miscellaneous details

Most functions will have a by_exprs_values parameter. This defines the assay of the SingleCellExperiment object from which expression values are extracted for use in colouring, shaping or sizing the points. The setting of by_exprs_values will usually default to "logcounts", or to the value of exprs_values in functions such as plotExpression. However, it can be specified separately from exprs_values, which is useful for visualizing two different types of expression values on the same plot.

Most functions will also have a by_show_single parameter. If FALSE, variables with only one level are not used for visualization, i.e., the visual aspect (colour or shape or size) is set to the default for all points. No guide is created for this aspect, avoiding clutter in the legend when that aspect provides no information. If TRUE, all supplied variables are used for visualization, regardless of how many levels they have.

See Also

plotColData, plotRowData, plotReducedDim, plotExpression, plotPlatePosition, and most other plotting functions.


[Package scater version 1.12.2 Index]