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

### 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.
`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 by default (tunable by setting `combine.coldata`). If any existing field is named `"batch"`, it will be ignored in favor of that produced by `batchCorrect` and a warning is emitted.

Row metadata is only included in the merged object if `include.rowdata=TRUE` and all row metadata objects are identical across objects in `...`. If not, a warning is emitted and no row metadata is attached to the merged object.

### 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.2.4 Index]