% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/retrieveCellInfo.R
\name{retrieveCellInfo}
\alias{retrieveCellInfo}
\title{Cell-based data retrieval}
\usage{
retrieveCellInfo(
  x,
  by,
  search = c("colData", "assays", "altExps"),
  exprs_values = "logcounts",
  swap_rownames = NULL
)
}
\arguments{
\item{x}{A \linkS4class{SingleCellExperiment} object.}

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

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

\item{exprs_values}{String or integer scalar specifying the assay from which expression values should be extracted.}

\item{swap_rownames}{Column name of \code{rowData(object)} to be used to 
identify features instead of \code{rownames(object)} when labelling plot 
elements.}
}
\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-cell (meta)data values.
If \code{by=NULL}, both \code{name} and \code{value} are set to \code{NULL}.
}
\description{
Retrieves a per-cell (meta)data field from a \linkS4class{SingleCellExperiment} based on a single keyword,
typically for use in visualization functions.
}
\details{
Given an \link{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{colData}} 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{colData}.
\item Search \code{\link{assay}(x, exprs_values)} for a row named \code{by}, 
and return the expression vector for this feature as the output \code{value}.
\item Search each alternative experiment in \code{\link{altExps}(x)} for a row names \code{by},
and return the expression vector for this feature at \code{exprs_values} 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)

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

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

\code{\link{plotColData}}, 
\code{\link{plotReducedDim}}, 
\code{\link{plotExpression}}, 
\code{\link{plotPlatePosition}},
and most other cell-based plotting functions.
}
\author{
Aaron Lun
}
