reducedMNN: MNN correction in reduced dimensions
In batchelor: Single-Cell Batch Correction Methods

Description Usage Arguments Details Value Author(s) See Also Examples

MNN correction in reduced dimensions

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

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

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.

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.

Aaron Lun

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.

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