correctExperiments: Correct SingleCellExperiment objects
In batchelor: Single-Cell Batch Correction Methods

Description Usage Arguments Details Value Author(s) See Also Examples

Apply a correction to multiple SingleCellExperiment objects, while also combining the assay data and column metadata for easy downstream use. This augments the simpler batchCorrect function, which returns only the corrected values.

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,
  add.single = TRUE
)

`...`	One or more 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, `batch` should also be specified. Alternatively, one or more lists of SingleCellExperiments can be provided; this is flattened so that it is as if the objects inside were passed directly to `...`.
`batch`	A factor specifying the batch of origin for each cell if only one batch is supplied in `...`. This will be ignored if two or more batches are supplied.
`restrict`	A list of length equal to the number of objects in `...`. Each entry of the list corresponds to one batch and specifies the cells to use when computing the correction.
`subset.row`	A vector specifying the subset of genes to use for correction. Defaults to `NULL`, in which case all genes are used.
`correct.all`	A logical scalar indicating whether to return corrected expression values for all genes, even if `subset.row` is set. Used to ensure that the output is of the same dimensionality as the input.
`assay.type`	A string or integer scalar specifying the assay to use for correction.
`PARAM`	A BatchelorParam object specifying the batch correction method to dispatch to, and the parameters with which it should be run. ClassicMnnParam will dispatch to `mnnCorrect`; FastMnnParam will dispatch to `fastMNN`; RescaleParam will dispatch to `rescaleBatches`; and RegressParam will dispatch to `regressBatches`.
`combine.assays`	Character vector specifying the assays from each entry of `...` to combine together without correction. By default, any named assay that is present in all entries of `...` is combined. This can be set to `character(0)` to avoid combining any assays.
`combine.coldata`	Character vector specifying the column metadata fields from each entry of `...` to combine together. By default, any column metadata field that is present in all entries of `...` is combined. This can be set to `character(0)` to avoid combining any metadata.
`include.rowdata`	Logical scalar indicating whether the function should attempt to include `rowRanges`.
`add.single`	Logical scalar indicating whether merged fields should be added to the original SingleCellExperiment. Only relevant when a single object is provided in `...`. If `TRUE`, `combine.assays`, `combine.coldata` and `include.rowdata` are ignored.

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.

All assays shared across the original objects are cbinded and added to the merged object. This can be controlled with combine.assays. Any original assay with the same name as an assay in the output of batchCorrect will be ignored with a warning.
Any column metadata fields that are shared will also be included in the merged object. This can be controlled with combine.coldata. If any existing field has the same name as any colData field produced by batchCorrect, it will be ignored in favor of the latter.
Row metadata from ... is included in the merged object if include.rowdata=TRUE. In such cases, only non-conflicting row data fields are preserved, i.e., fields with different names or identically named fields with the same values between objects in .... Any conflicting fields are ignored with a warning. rowRanges are only preserved if they are identical (ignoring the mcols) for all objects in ....

If a single SingleCellExperiment object was supplied in ..., the default behavior is to prepend all assays, reducedDims, colData, rowData and metadata fields from the merged object into the original (removing any original entries with names that overlap those of the merged object). This is useful as it preserves all (non-overlapping) aspects of the original object, especially the reduced dimensions that cannot, in general, be sensibly combined across multiple objects. Setting add.single=FALSE will force the creation of a new SingleCellExperiment rather than prepending.

A SingleCellExperiment containing the merged expression values in the first assay and a batch column metadata field specifying the batch of origin for each cell, as described in batchCorrect.

Aaron Lun

batchCorrect, which does the correction inside this function.

noCorrect, for another method to combine uncorrected assay values.

sce1 <- scuttle::mockSCE()
sce1 <- scuttle::logNormCounts(sce1)
sce2 <- scuttle::mockSCE()
sce2 <- scuttle::logNormCounts(sce2)

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