batchCorrect {batchelor} | R Documentation

## Batch correction methods

### Description

A common interface for single-cell batch correction methods.

### Usage

    batchCorrect(
      ...,
      batch = NULL,
      restrict = NULL,
      subset.row = NULL,
      correct.all = FALSE,
      assay.type = NULL,
      PARAM
    )

    ## S4 method for signature 'ClassicMnnParam'
    batchCorrect(
      ...,
      batch = NULL,
      restrict = NULL,
      subset.row = NULL,
      correct.all = FALSE,
      assay.type = "logcounts",
      PARAM
    )

    ## S4 method for signature 'FastMnnParam'
    batchCorrect(
      ...,
      batch = NULL,
      restrict = NULL,
      subset.row = NULL,
      correct.all = FALSE,
      assay.type = "logcounts",
      PARAM
    )

    ## S4 method for signature 'RescaleParam'
    batchCorrect(
      ...,
      batch = NULL,
      restrict = NULL,
      subset.row = NULL,
      correct.all = FALSE,
      assay.type = "logcounts",
      PARAM
    )

    ## S4 method for signature 'RegressParam'
    batchCorrect(
      ...,
      batch = NULL,
      restrict = NULL,
      subset.row = NULL,
      correct.all = FALSE,
      assay.type = "logcounts",
      PARAM
    )

    ## S4 method for signature 'NoCorrectParam'
    batchCorrect(
      ...,
      batch = NULL,
      restrict = NULL,
      subset.row = NULL,
      correct.all = FALSE,
      assay.type = "logcounts",
      PARAM
    )

### Arguments

`...` | One or more matrix-like objects containing single-cell gene expression matrices. Alternatively, one or more SingleCellExperiment objects can be supplied. If multiple objects are supplied, each object is assumed to contain all and only cells from a single batch. Objects of different types can be mixed together. 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. Only used for SingleCellExperiment inputs.
`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`.

### Details

Users can pass parameters to each method directly via `...` or via the constructors for `PARAM`. While there is no restriction on which parameters go where, we recommend only passing data-agnostic and method-specific parameters to `PARAM`. Data-dependent parameters - and indeed, the data themselves - should be passed in via `...`. This means that different data sets can be used without modifying `PARAM`, allowing users to switch to a different algorithm by only changing `PARAM`.

### Value

A SingleCellExperiment where the first assay contains corrected gene expression values for all genes. Corrected values should be returned for all genes if `subset.row=NULL` or if `correct.all=TRUE`; otherwise they should only be returned for the genes in the subset.

Cells should be reported in the same order that they are supplied. In cases with multiple batches, the cell identities are simply concatenated from successive objects in their specified order, i.e., all cells from the first object (in their provided order), then all cells from the second object, and so on. For a single input object, cells should be reported in the same order as the input.

The `colData` slot should contain `batch`, a vector specifying the batch of origin for each cell.

### Author(s)

Aaron Lun

### See Also

BatchelorParam classes to determine dispatch.

`correctExperiments`, to obtain corrected values while retaining the original expression data.

### Examples

    B1 <- matrix(rnorm(10000), ncol=50) # Batch 1
    B2 <- matrix(rnorm(10000), ncol=50) # Batch 2

    # Switching easily between batch correction methods.
    m.out <- batchCorrect(B1, B2, PARAM=ClassicMnnParam())
    f.out <- batchCorrect(B1, B2, PARAM=FastMnnParam(d=20))
    r.out <- batchCorrect(B1, B2, PARAM=RescaleParam(pseudo.count=0))
    n.out <- batchCorrect(B1, B2, PARAM=NoCorrectParam())

[Package batchelor version 1.4.0 Index]