% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/correctExperiments.R
\name{correctExperiments}
\alias{correctExperiments}
\title{Correct SingleCellExperiment objects}
\usage{
correctExperiments(
  ...,
  batch = NULL,
  restrict = NULL,
  subset.row = NULL,
  correct.all = FALSE,
  assay.type = "logcounts",
  PARAM = FastMnnParam(),
  combine.assays = NULL,
  combine.coldata = NULL,
  include.rowdata = TRUE
)
}
\arguments{
\item{...}{One or more \linkS4class{SingleCellExperiment} objects.
If multiple objects are supplied, each object is assumed to contain all and only cells from a single batch.
If a single object is supplied, \code{batch} should also be specified.}

\item{batch}{A factor specifying the batch of origin for each cell if only one batch is supplied in \code{...}.
This will be ignored if two or more batches are supplied.}

\item{restrict}{A list of length equal to the number of objects in \code{...}.
Each entry of the list corresponds to one batch and specifies the cells to use when computing the correction.}

\item{subset.row}{A vector specifying the subset of genes to use for correction.
Defaults to \code{NULL}, in which case all genes are used.}

\item{correct.all}{A logical scalar indicating whether to return corrected expression values for all genes, even if \code{subset.row} is set.
Used to ensure that the output is of the same dimensionality as the input.}

\item{assay.type}{A string or integer scalar specifying the assay to use for correction.}

\item{PARAM}{A \linkS4class{BatchelorParam} object specifying the batch correction method to dispatch to, and the parameters with which it should be run.
\linkS4class{ClassicMnnParam} will dispatch to \code{\link{mnnCorrect}};
\linkS4class{FastMnnParam} will dispatch to \code{\link{fastMNN}};
\linkS4class{RescaleParam} will dispatch to \code{\link{rescaleBatches}};
and \linkS4class{RegressParam} will dispatch to \code{\link{regressBatches}}.}

\item{combine.assays}{Character vector specifying the assays from each entry of \code{...} to combine together without correction.
By default, any named assay that is present in all entries of \code{...} are combined.
This can be set to \code{character(0)} to avoid combining any assays.}

\item{combine.coldata}{Character vector specifying the column metadata fields from each entry of \code{...} to combine together.
By default, any column metadata field that is present in all entries of \code{...} is combined.
This can be set to \code{character(0)} to avoid combining any metadata.}

\item{include.rowdata}{Logical scalar indicating whether the function should attempt to include \code{\link{rowRanges}}.}
}
\value{
A SingleCellExperiment containing the merged expression values in the first assay
and a \code{batch} column metadata field specifying the batch of origin for each cell,
as described in \code{\link{batchCorrect}}.
}
\description{
Apply a correction to multiple \linkS4class{SingleCellExperiment} objects,
while also combining the assay data and column metadata for easy use.
}
\details{
This function makes it easy to retain information from the original SingleCellExperiment objects in the post-merge object.
Operations like differential expression analyses can be easily performed on the uncorrected expression values,
while common annotation can be leveraged in cell-based analyses like clustering.

Additional assays may be added to the merged object, depending on \code{combine.assays}.
This will usually contain uncorrected values from each batch that have been simply \code{cbind}ed together.
If \code{combine.assays} contains a field that overlaps with the name of the corrected assay from \code{\link{batchCorrect}},
a warning will be raised and the corrected assay will be preferentially retained.

Any column metadata fields that are shared will also be included in the merged object by default (tunable by setting \code{combine.coldata}).
If any existing field is named \code{"batch"}, it will be ignored in favor of that produced by \code{\link{batchCorrect}} and a warning is emitted.

Row metadata is only included in the merged object if \code{include.rowdata=TRUE} \emph{and} all row metadata objects are identical across objects in \code{...}.
If not, a warning is emitted and no row metadata is attached to the merged object.
}
\examples{
sce1 <- scater::mockSCE()
sce1 <- scater::logNormCounts(sce1)
sce2 <- scater::mockSCE()
sce2 <- scater::logNormCounts(sce2)

f.out <- correctExperiments(sce1, sce2)
colData(f.out)
assayNames(f.out)

}
\seealso{
\code{\link{batchCorrect}}, which does the correction inside this function.

\code{\link{noCorrect}}, used to combine uncorrected values for the other assays.
}
\author{
Aaron Lun
}
