retrieveCellInfo {scater} | R Documentation

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

### 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` | 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, exprs_values)` 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 `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.

### 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` or was not found in `x`, both `name` and `value` are set to `NULL`.

### Author(s)

Aaron Lun

### See Also

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

[Package scater version 1.14.0 Index]