correctExperiments {batchelor} | R Documentation

## Correct SingleCellExperiment objects

### Description

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.

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

`...` | 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 `...` are 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`.

### 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 `combine.assays`. This will usually contain uncorrected values from each batch that have been simply `cbind`ed together. If `combine.assays` contains a field that overlaps with the name of the corrected assay from `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 if `combine.coldata=TRUE`. 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 `...`.

### Value

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`.

### Author(s)

Aaron Lun

### See Also

`batchCorrect`, which does the correction inside this function.

`noCorrect`, used to combine uncorrected values for the other assays.

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

[Package batchelor version 1.4.0 Index]