reducedMNN {batchelor} | R Documentation

## MNN correction in reduced dimensions

### Description

MNN correction in reduced dimensions

### Usage

    reducedMNN(
      ...,
      batch = NULL,
      k = 20,
      prop.k = NULL,
      restrict = NULL,
      ndist = 3,
      merge.order = NULL,
      auto.merge = FALSE,
      min.batch.skip = 0,
      BNPARAM = KmknnParam(),
      BPPARAM = SerialParam()
    )

### Arguments

`...` | One or more matrices of low-dimensional representations where rows are cells and columns are dimensions. Each object should contain the same number of columns, corresponding to the same dimensions. These should have been generated by a single call to `multiBatchPCA`. 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, any number of lists of such objects. this is flattened as if the objects inside each list were passed directly to `...`.
`batch` | A factor specifying the batch of origin for all cells when only a single object is supplied in `...`. This is ignored if multiple objects are present.
`k` | An integer scalar specifying the number of nearest neighbors to consider when identifying MNNs.
`prop.k` | A numeric scalar in (0, 1) specifying the proportion of cells in each dataset to use for mutual nearest neighbor searching. If set, the number of nearest neighbors used for the MNN search in each batch is redefined as `max(k, prop.k*N)` where `N` is the number of cells in that batch.
`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.
`ndist` | A numeric scalar specifying the threshold beyond which neighbours are to be ignored when computing correction vectors. Each threshold is defined as a multiple of the number of median distances.
`merge.order` | An integer vector containing the linear merge order of batches in `...`. Alternatively, a list of lists representing a tree structure specifying a hierarchical merge order.
`auto.merge` | Logical scalar indicating whether to automatically identify the “best” merge order.
`min.batch.skip` | Numeric scalar specifying the minimum relative magnitude of the batch effect, below which no correction will be performed at a given merge step.
`BNPARAM` | A BiocNeighborParam object specifying the nearest neighbor algorithm.
`BPPARAM` | A BiocParallelParam object specifying whether the PCA and nearest-neighbor searches should be parallelized.

### Details

`reducedMNN` performs the same operations as `fastMNN` but assumes that the PCA has already been performed. This is useful as the PCA (via `multiBatchPCA`) is often the most time-consuming step. By performing the PCA once, `reducedMNN` allows the MNN correction to be quickly repeated with different parameters.

`reducedMNN` operates on the same principles as `fastMNN`, so users are referred to the documentation for the latter for more details on the effect of each of the arguments. Obviously, any arguments pertaining to gene-based steps in `fastMNN` are not relevant here.

Note that `multiBatchPCA` will not perform cosine-normalization, so it is the responsibility of the user to cosine-normalize each batch beforehand with `cosineNorm` to recapitulate results of `fastMNN` with `cos.norm=TRUE`. In addition, `multiBatchPCA` must be run on all samples at once, to ensure that all cells are projected to the same low-dimensional space.

### Value

A DataFrame is returned where each row corresponds to a cell, containing:

- `corrected`, the matrix of corrected low-dimensional coordinates for each cell.

- `batch`, the Rle specifying the batch of origin for each row.

Cells in the output object are always ordered in the same manner as supplied in `...`. The metadata on this object is the same as that in the output of `fastMNN`.

### Author(s)

Aaron Lun

### See Also

`multiBatchPCA`, to obtain the values to be corrected.

`fastMNN`, for the version that operates on gene-expression values.

`clusterMNN`, for an application on cluster centroids.

### Examples

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

    # Equivalent to fastMNN().
    cB1 <- cosineNorm(B1)
    cB2 <- cosineNorm(B2)
    pcs <- multiBatchPCA(cB1, cB2)
    out2 <- reducedMNN(pcs[[1]], pcs[[2]])

[Package batchelor version 1.6.3 Index]