retrieveCellInfo: Cell-based data retrieval

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

Cell-based data retrieval

Description

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

Usage

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

Arguments

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	Alias to assay.type.
swap_rownames	Column name of rowData(object) to be used to identify features instead of rownames(object) when labelling plot elements.
assay.type	String or integer scalar specifying the assay from which expression values should be extracted.

Details

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:

1. 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.

2. Search assay(x, assay.type) for a row named by, and return the expression vector for this feature as the output value.

3. Search each alternative experiment in altExps(x) for a row names by, and return the expression vector for this feature at assay.type 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.

Value

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.

Author(s)

Aaron Lun

See Also

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

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

Examples

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))

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