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

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

- All assays shared across the original objects are `cbind`ed 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.

### 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`, for another method to combine uncorrected assay values.

### Examples

    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)

[Package batchelor version 1.8.1 Index]