% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/integration.R
\name{TransferData}
\alias{TransferData}
\title{Transfer data}
\usage{
TransferData(
  anchorset,
  refdata,
  weight.reduction = "pcaproject",
  l2.norm = FALSE,
  dims = 1:30,
  k.weight = 50,
  sd.weight = 1,
  eps = 0,
  do.cpp = TRUE,
  verbose = TRUE,
  slot = "data",
  prediction.assay = FALSE
)
}
\arguments{
\item{anchorset}{An \code{\link{AnchorSet}} object generated by
\code{\link{FindTransferAnchors}}}

\item{refdata}{Data to transfer. Should be either a vector where the names
correspond to reference cells, or a matrix, where the column names correspond
to the reference cells.}

\item{weight.reduction}{Dimensional reduction to use for the weighting
anchors. Options are:
\itemize{
   \item{pcaproject: Use the projected PCA used for anchor building}
   \item{pca: Use an internal PCA on the query only}
   \item{cca: Use the CCA used for anchor building}
   \item{custom DimReduc: User provided \code{\link{DimReduc}} object
   computed on the query cells}
}}

\item{l2.norm}{Perform L2 normalization on the cell embeddings after
dimensional reduction}

\item{dims}{Number of dimensions to use in the anchor weighting procedure}

\item{k.weight}{Number of neighbors to consider when weighting anchors}

\item{sd.weight}{Controls the bandwidth of the Gaussian kernel for weighting}

\item{eps}{Error bound on the neighbor finding algorithm (from
\code{\link{RANN}})}

\item{do.cpp}{Run cpp code where applicable. This argument is being
deprecated and will be set to TRUE by default.}

\item{verbose}{Print progress bars and output}

\item{slot}{Slot to store the imputed data. Must be either "data" (default)
or "counts"}

\item{prediction.assay}{Return an \code{Assay} object with the prediction
scores for each class stored in the \code{data} slot.}
}
\value{
If \code{refdata} is a vector, returns a data.frame with label
predictions. If \code{refdata} is a matrix, returns an Assay object where the
imputed data has been stored in the provided slot.
}
\description{
Transfer categorical or continuous data across single-cell datasets. For
transferring categorical information, pass a vector from the reference
dataset (e.g. \code{refdata = reference$celltype}). For transferring
continuous information, pass a matrix from the reference dataset (e.g.
\code{refdata = GetAssayData(reference[['RNA']])}).
}
\details{
The main steps of this procedure are outlined below. For a more detailed
description of the methodology, please see Stuart, Butler, et al Cell 2019.
\url{https://doi.org/10.1016/j.cell.2019.05.031};
\url{https://doi.org/10.1101/460147}

For both transferring discrete labels and also feature imputation, we first
compute the weights matrix.

\itemize{
  \item{Construct a weights matrix that defines the association between each
  query cell and each anchor. These weights are computed as 1 - the distance
  between the query cell and the anchor divided by the distance of the query
  cell to the \code{k.weight}th anchor multiplied by the anchor score
  computed in \code{\link{FindIntegrationAnchors}}. We then apply a Gaussian
  kernel width a bandwidth defined by \code{sd.weight} and normalize across
  all \code{k.weight} anchors.}
}

The main difference between label transfer (classification) and feature
imputation is what gets multiplied by the weights matrix. For label transfer,
we perform the following steps:

\itemize{
  \item{Create a binary classification matrix, the rows corresponding to each
  possible class and the columns corresponding to the anchors. If the
  reference cell in the anchor pair is a member of a certain class, that
  matrix entry is filled with a 1, otherwise 0.}
  \item{Multiply this classification matrix by the transpose of weights
  matrix to compute a prediction score for each class for each cell in the
  query dataset.}
}

For feature imputation, we perform the following step:
\itemize{
  \item{Multiply the expression matrix for the reference anchor cells by the
  weights matrix. This returns a predicted expression matrix for the
  specified features for each cell in the query dataset.}
}
}
\examples{
\dontrun{
# to install the SeuratData package see https://github.com/satijalab/seurat-data
library(SeuratData)
data("pbmc3k")

# for demonstration, split the object into reference and query
pbmc.reference <- pbmc3k[, 1:1350]
pbmc.query <- pbmc3k[, 1351:2700]

# perform standard preprocessing on each object
pbmc.reference <- NormalizeData(pbmc.reference)
pbmc.reference <- FindVariableFeatures(pbmc.reference)
pbmc.reference <- ScaleData(pbmc.reference)

pbmc.query <- NormalizeData(pbmc.query)
pbmc.query <- FindVariableFeatures(pbmc.query)
pbmc.query <- ScaleData(pbmc.query)

# find anchors
anchors <- FindTransferAnchors(reference = pbmc.reference, query = pbmc.query)

# transfer labels
predictions <- TransferData(anchorset = anchors, refdata = pbmc.reference$seurat_annotations)
pbmc.query <- AddMetaData(object = pbmc.query, metadata = predictions)
}

}
\references{
Stuart T, Butler A, et al. Comprehensive Integration of
Single-Cell Data. Cell. 2019;177:1888-1902 \url{https://doi.org/10.1016/
j.cell.2019.05.031}
}
