retrieveFeatureInfo {scater} | R Documentation

## Feature-based data retrieval

### Description

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

### Usage

    retrieveFeatureInfo(
      x,
      by,
      search = c("rowData", "assays"),
      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 a 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 `rowData` for a column named `by`, and return the corresponding field as the output `value`. We do not consider nested elements within the `rowData`.

2. Search `assay(x, exprs_values)` for a column named `by`, and return the expression vector for this feature 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-feature (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

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

`plotRowData` and other feature-based plotting functions.

### Examples

    example_sce <- mockSCE()
    example_sce <- logNormCounts(example_sce)
    rowData(example_sce)$blah <- sample(LETTERS,
        nrow(example_sce), replace=TRUE)

    str(retrieveFeatureInfo(example_sce, "blah"))
    str(retrieveFeatureInfo(example_sce, "Cell_001"))

    arbitrary.field <- rnorm(nrow(example_sce))
    str(retrieveFeatureInfo(example_sce, I(arbitrary.field)))
    str(retrieveFeatureInfo(example_sce, data.frame(stuff=arbitrary.field)))

[Package scater version 1.16.2 Index]