retrieveCellInfo: Cell-based data retrieval
In scater: Single-Cell Analysis Toolkit for Gene Expression Data in R

Description Usage Arguments Details Value Author(s) See Also Examples

Retrieves a per-cell (meta)data field from a SingleCellExperiment based on a single keyword, typically for use in visualization functions.

retrieveCellInfo(
  x,
  by,
  search = c("colData", "assays", "altExps"),
  exprs_values = "logcounts",
  swap_rownames = NULL
)

`x`	A SingleCellExperiment object.
`by`	A string specifying the field to extract (see Details). Alternatively, a data.frame, DataFrame or an AsIs vector.
`search`	Character vector specifying the types of data or metadata to use.
`exprs_values`	String or integer scalar specifying the assay from which expression values should be extracted.
`swap_rownames`	Column name of `rowData(object)` to be used to identify features instead of `rownames(object)` when labelling plot elements.

Given an AsIs-wrapped vector in by, this function will directly return the vector values as value, while name is set to an empty string. For data.frame or DataFrame instances with a single column, this function will return the vector from that column as value and the column name as name. This allows downstream visualization functions to accommodate arbitrary inputs for adjusting aesthetics.

Given a character string in by, this function will:

Search colData for a column named by, and return the corresponding field as the output value. We do not consider nested elements within the colData.
Search assay(x, exprs_values) for a row named by, and return the expression vector for this feature as the output value.
Search each alternative experiment in altExps(x) for a row names by, and return the expression vector for this feature at exprs_values as the output value.

Any match will cause the function to return without considering later possibilities. The search can be modified by changing the presence and ordering of elements in search.

If there is a name clash that results in retrieval of an unintended field, users should explicitly set by to a data.frame, DataFrame or AsIs-wrapped vector containing the desired values. Developers can also consider setting search to control the fields that are returned.

A list containing name, a string with the name of the extracted field (usually identically to by); and value, a vector of length equal to ncol(x) containing per-cell (meta)data values. If by=NULL, both name and value are set to NULL.

Aaron Lun

makePerCellDF, which provides a more user-friendly interface to this function.

plotColData, plotReducedDim, plotExpression, plotPlatePosition, and most other cell-based plotting functions.

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

retrieveCellInfo(example_sce, "Cell_Cycle")
retrieveCellInfo(example_sce, "Gene_0001")

arbitrary.field <- rnorm(ncol(example_sce))
retrieveCellInfo(example_sce, I(arbitrary.field))
retrieveCellInfo(example_sce, data.frame(stuff=arbitrary.field))