% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/retrieveFeatureInfo.R
\name{retrieveFeatureInfo}
\alias{retrieveFeatureInfo}
\title{Feature-based data retrieval}
\usage{
retrieveFeatureInfo(
  x,
  by,
  search = c("rowData", "assays"),
  exprs_values = "logcounts",
  assay.type = exprs_values
)
}
\arguments{
\item{x}{A \link[SingleCellExperiment]{SingleCellExperiment-class} object.}

\item{by}{A string specifying the field to extract (see Details).
Alternatively, a data.frame, \link[S4Vectors]{DataFrame-class} or an \link{AsIs} vector.}

\item{search}{Character vector specifying the types of data or metadata to use.}

\item{exprs_values}{Alias to \code{assay.type}.}

\item{assay.type}{String or integer scalar specifying the assay from which expression values should be extracted.}
}
\value{
A list containing \code{name}, a string with the name of the extracted field (usually identically to \code{by});
and \code{value}, a vector of length equal to \code{ncol(x)} containing per-feature (meta)data values.
If \code{by=NULL}, both \code{name} and \code{value} are set to \code{NULL}.
}
\description{
Retrieves a per-feature (meta)data field from a \link[SingleCellExperiment]{SingleCellExperiment-class} based on a single keyword,
typically for use in visualization functions.
}
\details{
Given a AsIs-wrapped vector in \code{by}, this function will directly return the vector values as \code{value},
while \code{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 \code{value} and the column name as \code{name}.
This allows downstream visualization functions to accommodate arbitrary inputs for adjusting aesthetics.

Given a character string in \code{by}, this function will:
\enumerate{
\item Search \code{\link[SummarizedExperiment]{rowData}} for a column named \code{by}, 
and return the corresponding field as the output \code{value}.
We do not consider nested elements within the \code{rowData}.
\item Search \code{\link[SummarizedExperiment]{assay}(x, assay.type)} for a column named \code{by}, 
and return the expression vector for this feature as the output \code{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 \code{search}. 

If there is a name clash that results in retrieval of an unintended field,
users should explicitly set \code{by} to a data.frame, DataFrame or AsIs-wrapped vector containing the desired values.
Developers can also consider setting \code{search} to control the fields that are returned.
}
\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)))

}
\seealso{
\code{\link{makePerFeatureDF}}, which provides a more user-friendly interface to this function.

\code{\link{plotRowData}} and other feature-based plotting functions.
}
\author{
Aaron Lun
}
