% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fastMNN.R
\name{fastMNN}
\alias{fastMNN}
\title{Fast mutual nearest neighbors correction}
\usage{
fastMNN(
  ...,
  batch = NULL,
  k = 20,
  prop.k = NULL,
  restrict = NULL,
  cos.norm = TRUE,
  ndist = 3,
  d = 50,
  weights = NULL,
  merge.order = NULL,
  auto.merge = FALSE,
  auto.order = NULL,
  min.batch.skip = 0,
  subset.row = NULL,
  correct.all = FALSE,
  pc.input = FALSE,
  assay.type = "logcounts",
  get.spikes = FALSE,
  use.dimred = NULL,
  BSPARAM = IrlbaParam(deferred = TRUE),
  BNPARAM = KmknnParam(),
  BPPARAM = SerialParam()
)
}
\arguments{
\item{...}{One or more log-expression matrices where genes correspond to rows and cells correspond to columns.
Each matrix should contain the same number of rows, corresponding to the same genes in the same order.

Alternatively, one or more \linkS4class{SingleCellExperiment} objects can be supplied containing a log-expression matrix in the \code{assay.type} assay.
Note the same restrictions described above for gene expression matrix inputs.

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, \code{batch} should also be specified.}

\item{batch}{A factor specifying the batch of origin for all cells when only a single object is supplied in \code{...}.
This is ignored if multiple objects are present.}

\item{k}{An integer scalar specifying the number of nearest neighbors to consider when identifying MNNs.}

\item{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, \code{k} for the search in each batch is redefined as \code{max(k, prop.k*N)} where \code{N} is the number of cells in that batch.}

\item{restrict}{A list of length equal to the number of objects in \code{...}.
Each entry of the list corresponds to one batch and specifies the cells to use when computing the correction.}

\item{cos.norm}{A logical scalar indicating whether cosine normalization should be performed on the input data prior to PCA.}

\item{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.}

\item{d}{Number of dimensions to use for dimensionality reduction in \code{\link{multiBatchPCA}}.}

\item{weights}{Numeric scalar of weights to use in \code{\link{multiBatchPCA}}.}

\item{merge.order}{An integer vector containing the linear merge order of batches in \code{...}.
Alternatively, a list of lists representing a tree structure specifying a hierarchical merge order.}

\item{auto.merge}{Logical scalar indicating whether to automatically identify the \dQuote{best} merge order.}

\item{auto.order}{Deprecated, use \code{merge.order} or \code{auto.merge} instead.}

\item{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.}

\item{subset.row}{A vector specifying which features to use for correction.}

\item{correct.all}{Logical scalar indicating whether a rotation matrix should be computed for genes not in \code{subset.row}.}

\item{pc.input}{Deprecated, use \code{\link{reducedMNN}} instead.}

\item{assay.type}{A string or integer scalar specifying the assay containing the log-expression values.
Only used for SingleCellExperiment inputs.}

\item{get.spikes}{Deprecated.}

\item{use.dimred}{Deprecated, use \code{\link{reducedMNN}} instead.}

\item{BSPARAM}{A \linkS4class{BiocSingularParam} object specifying the algorithm to use for PCA.
This uses a fast approximate algorithm from \pkg{irlba} by default, see \code{\link{multiBatchPCA}} for details.}

\item{BNPARAM}{A \linkS4class{BiocNeighborParam} object specifying the nearest neighbor algorithm.}

\item{BPPARAM}{A \linkS4class{BiocParallelParam} object specifying whether the PCA and nearest-neighbor searches should be parallelized.}
}
\value{
A \linkS4class{SingleCellExperiment} is returned where each row is a gene and each column is a cell. 
This contains:
\itemize{
\item A \code{corrected} matrix in the \code{reducedDims} slot, containing corrected low-dimensional coordinates for each cell.
This has number of columns equal to \code{d} and number of rows equal to the total number of cells in \code{...}.
\item A \code{batch} column in the \code{colData} slot, containing the batch of origin for each row (i.e., cell) in \code{corrected}.
\item A \code{rotation} column the \code{rowData} slot, containing the rotation matrix used for the PCA.
This has \code{d} columns and number of rows equal to the number of genes to report (see the \dQuote{Choice of genes} section).
\item A \code{reconstructed} matrix in the \code{assays} slot, containing the low-rank reconstruction of the expression matrix.
This can be interpreted as per-gene corrected log-expression values (after cosine normalization, if \code{cos.norm=TRUE}) but should not be used for quantitative analyses.
This has number of rows equal to the number of input genes if \code{subset.row=NULL} or \code{correct.all=TRUE},
otherwise each row corresponds to a gene in \code{subset.row}.
}

Cells in the output object are always ordered in the same manner as supplied in \code{...}.
For a single input object, cells will be reported in the same order as they are arranged in that object.
In cases with multiple input objects, the cell identities are simply concatenated from successive objects,
i.e., all cells from the first object (in their provided order), then all cells from the second object, and so on.
This is true regardless of the value of \code{merge.order} and \code{auto.merge},
which only affects the internal merge order of the batches.

The metadata of the output object contains \code{merge.info}, 
a \linkS4class{DataFrame} of diagnostic information about each merge step.
See the \dQuote{Merge diagnostics} section for more details.
}
\description{
Correct for batch effects in single-cell expression data using a fast version of the mutual nearest neighbors (MNN) method.
}
\details{
This function provides a variant of the \code{\link{mnnCorrect}} function, modified for speed and more robust performance.
In particular:
\itemize{
\item It performs a multi-sample PCA via \code{\link{multiBatchPCA}} and subsequently performs all calculations in the PC space.
This reduces computational work and provides some denoising for improved neighbour detection. 
As a result, though, the corrected output cannot be interpreted on a gene level and is useful only for cell-level comparisons, e.g., clustering and visualization.
\item The correction vector for each cell is directly computed from its \code{k} nearest neighbours in the same batch.
Specifically, only the \code{k} nearest neighbouring cells that \emph{also} participate in MNN pairs are used.
Each MNN-participating neighbour is weighted by distance from the current cell, using a tricube scheme with bandwidth equal to the median distance multiplied by \code{ndist}.
This ensures that the correction vector only uses information from the closest cells, improving the fidelity of local correction.
\item Issues with \dQuote{kissing} are avoided with a two-step procedure that removes variation along the batch effect vector.
First, the average correction vector across all MNN pairs is computed.
Cell coordinates are adjusted such that all cells in a single batch have the same position along this vector.
The correction vectors are then recalculated with the adjusted coordinates (but the same MNN pairs).
}

The default setting of \code{cos.norm=TRUE} provides some protection against differences in scaling between log-expression matrices from batches that are normalized separately
(see \code{\link{cosineNorm}} for details).
However, if possible, we recommend using the output of \code{\link{multiBatchNorm}} as input to \code{fastMNN}.
This will equalize coverage on the count level before the log-transformation, which is a more accurate rescaling than cosine normalization on the log-values.

The \code{batch} argument allows users to easily perform batch correction when all cells have already been combined into a single object.
This avoids the need to manually split the matrix or SingleCellExperiment object into separate objects for input into \code{fastMNN}.
In this situation, the order of input batches is defined by the order of levels in \code{batch}.
}
\section{Controlling the merge order}{

By default, batches are merged in the user-supplied order, 
i.e., the first batch is merged with the second batch, 
the third batch is merged with the combined first-second batch,
the fourth batch is merged with the combined first-second-third batch and so on.
We refer to this approach as a progressive merge.

If \code{merge.order} is an integer vector, it is treated as an ordering permutation with which to perform a progressive merge.
For example, if \code{merge.order=c(4,1,3,2)}, batches 4 and 1 in \code{...} are merged first;
batch 3 is merged with the combined 4+1 batch; 
and then batch 2 is merged with the combined 4+1+3 batch.
This is often more convenient than changing the order manually in \code{...}, 
which would alter the order of batches in the output \code{corrected} matrix.

If \code{merge.order} is a character vector, it is treated as an ordering permutation for named batches.

If \code{merge.order} is a nested list, it is treated as a tree that specifies a hierarchical merge.
Each element of the list should either be a string or integer scalar, corresponding to a leaf node that specifies a batch;
or another list, corresponding to an internal node that should contain at least two children;
or an integer or character vector of length 2 or more, again corresponding to an internal node.
\itemize{
\item For example, \code{list(list(1,2), list(3,4))} indicates that batch 1 should be merged with batch 2;
batch 3 should be merged with batch 4; and that, finally, the combined batches 1+2 and 3+4 should be merged.
\item More than two children per node are supported and will result in a progressive merge within that node.
For example, \code{list(list(1,2,3), list(4,5,6))} will merge batch 1 with 2, then 1+2 with 3;
batch 4 with 5, and then 4+5 with 6; and finally, 1+2+3 with 4+5+6.
\item The same approach can be used for integer or character vectors, e.g., \code{list(1:3, 4:6)} has the same effect as above.
}
Note that, while batches can be specified by name (character) or index (integer), users cannot use both in the same tree.

The merge order may occasionally be important as it determines the number of MNN pairs available at each merge step.
MNN pairs results in greater stability of the batch vectors and increased likelihood of identifying shared subpopulations,
which are important to the precision and accuracy of the MNN-based correction, respectively.
\itemize{
\item  In a progressive merge, the reference increases in size at each step,
ensuring that more cells are available to identify MNN pairs in later merges.
We suggest setting the largest, most heterogeneous batch as the first reference,
which favors detection of sufficient MNN pairs between the first and other batches.
Conversely, if two small batches without shared populations are supplied first, 
the wrong MNN pairs will be detected and the result of the merge will be incorrect.
\item A merge tree is useful for merging together batches that are known to be more closely related (e.g., replicates)
before attempting difficult merges involving more dissimilar batches.
The idea is to increase the number of cells and thus MNN pairs prior to merging batches with few shared subpopulations.
By comparison, performing the more difficult merges first is more likely to introduce errors whereby distinct subpopulations are incorrectly placed together, which is propagated to later steps as the initial merge is used as a reference for subsequent merges.
\item If \code{auto.merge=TRUE}, merge steps are chosen to maximize the number of MNN pairs at each step.
The aim is to improve the stability of the correction by first merging more similar batches with more MNN pairs.
This can be somewhat time-consuming as MNN pairs need to be iteratively recomputed for all possible batch pairings.
}

The order of cells in the output is \emph{never} affected by the setting of \code{merge.order} or \code{auto.order}.
It depends only on the order of objects in \code{...} and the order of cells within each object.
}

\section{Choice of genes}{

All genes are used with the default setting of \code{subset.row=NULL}.
Users can set \code{subset.row} to subset the inputs to highly variable genes or marker genes.
This improves the quality of the PCA and identification of MNN pairs by reducing the noise from irrelevant genes.
Note that users should not be too restrictive with subsetting, 
as high dimensionality is required to satisfy the orthogonality assumption in MNN detection.

By default, only the selected genes are used to compute rotation vectors and a low-rank corrected expression matrix.
However, setting \code{correct.all=TRUE} will return rotation vectors that span all genes in the supplied input data.
This is useful for ensuring that corrected values are returned for all input genes, e.g., in \code{\link{correctExperiments}}.
Note that this setting will not affect the corrected low-dimension coordinates or the rotation values for the selected genes.
}

\section{Using restriction}{

See \code{?"\link{batchelor-restrict}"} for a description of the \code{restrict} argument.
Specifically, \code{fastMNN} will only use the restricted subset of cells in each batch to identify MNN pairs and the center of the orthogonalization.
It will then extrapolate the correction to all cells in each batch.

Note that \emph{all} cells are used to perform the PCA, regardless of whether \code{restrict} is set.
This is generally desirable in applications where \code{restrict} is useful.
For example, constructing the projection vectors with only control cells will not guarantee resolution of unique non-control populations in each batch.

However, this also means that the corrected values for the restricted cells will differ from the output when the inputs are directly subsetted to only contain the restricted cells.
If this is not desirable, users can perform the PCA manually and apply \code{\link{reducedMNN}} instead.
}

\section{Merge diagnostics}{

We can consider \code{fastMNN}'s operation in terms of pairwise merge steps.
Each merge step involves two mutually exclusive sets of cells, a \dQuote{left} set and \dQuote{right} set.
Each set may consist of cells from different batches if those batches were merged in a previous step.
The merge will then create a new set of cells that combines the left and right sets.
Iteratively repeating this process with the newly formed sets will eventually merge all batches together.

The output metadata contains \code{merge.info}, a DataFrame where each row corresponds to a merge step.
It contains the following fields:
\itemize{
\item \code{left}, a \linkS4class{List} of integer or character vectors.
Each vector specifies the batches in the left set at a given merge step. 
\item \code{right}, a similar List of integer or character vectors.
Each vector specifies the batches in the right set at a given merge step. 
\item \code{pairs}, a List of DataFrames specifying which pairs of cells were identified as MNNs at each step.
In each DataFrame, each row corresponds to a single MNN pair and specifies the
paired cells that were in the left and right sets, respectively.
Note that the indices refer to those paired cells in the \emph{output} ordering of cells,
i.e., users can identify the paired cells at each step by column-indexing the output of the \code{fastMNN} function.
\item \code{batch.size}, a numeric vector specifying the relative magnitude of the batch effect at each merge,
see \dQuote{Orthogonalization details}.
\item \code{skipped}, a logical vector indicating whether the correction was skipped 
if the magnitude of the batch effect was below \code{min.batch.skip}.
\item \code{lost.var}, a numeric matrix specifying the percentage of variance lost due to orthogonalization at each merge step.
This is reported separately for each batch (columns, ordered according to the input order, \emph{not} the merge order).
}
}

\section{Specifying the number of neighbors}{

The threshold to define nearest neighbors is defined by \code{k}, which is passed to \code{\link{findMutualNN}} to identify MNN pairs.
The size of \code{k} can be roughly interpreted as the anticipated minimum size of a shared subpopulation in each batch.
If a batch has fewer than \code{k} cells of a shared subpopulation, there is an increased risk that its counterparts in other batches will form incorrect MNN pairs.

From the perspective of the algorithm, larger values allow for more MNN pairs to be obtained, which improves the stability of the correction vectors.
Larger values also increase robustness against non-orthogonality, by ignoring a certain level of biological variation when identifying pairs.
This can be used to avoid the kissing problem where MNN pairs are only detected on the \dQuote{surface} of the distribution.
However, values of \code{k} should not be too large, as this would result in MNN pairs being inappropriately identified between biologically distinct populations.

In practice, increasing \code{k} will generally result in more aggressive merging as the algorithm is more generous in matching subpopulations across batches.
We suggest starting with the default \code{k} and increasing it if one is confident that the same cell types are not adequately merged across batches.
This is better than starting with a large \code{k} as incorrect merging is much harder to diagnose than insufficient merging.

An additional consideration is that the effect of any given \code{k} will vary with the number of cells in each batch.
With more cells, a larger \code{k} may be preferable to achieve better merging in the presence of non-orthogonality.
We can achieve this by setting \code{prop.k}, which allows the choice of \code{k} to adapt to the size of each batch at each merge step.
This also handles asymmetry in batch sizes via the \code{k1} and \code{k2} arguments in \code{\link{findMutualNN}}.
}

\section{Orthogonalization details}{

\code{fastMNN} will compute the percentage of variance that is lost from each batch during orthogonalization at each merge step.
This represents the variance in each batch that is parallel to the average correction vectors (and hence removed during orthogonalization) at each merge step.
Large proportions suggest that there is biological structure that is parallel to the batch effect, 
corresponding to violations of the assumption that the batch effect is orthogonal to the biological subspace.

If \code{fastMNN} is called with DataFrame inputs, each DataFrame is assumed to be the result of a previous \code{fastMNN} call
and have a set of vectors used for orthogonalization in the merge steps of that previous call.
In the current call, \code{fastMNN} will gather all such batch vectors across all DataFrame inputs.
Each batch is then re-orthogonalized with respect to each of these vectors.
This ensures that the same variation is removed from each batch prior to merging.
The variance lost due to this pre-correction orthogonalization is reported in the \code{pre.orthog} field in the output metadata.

Orthogonalization may cause problems if there is actually no batch effect, resulting in large losses of variance.
To avoid this, \code{fastMNN} will not perform any correction if the relative magnitude of the batch effect is less than \code{min.batch.skip}.
The relative magnitude is defined as the L2 norm of the average correction vector divided by the root-mean-square of the L2 norms of the per-MNN pair correction vectors.
This will be large when the per-pair vectors are all pointing in the same direction, 
and small when the per-pair vectors point in random directions due to the absence of a consistent batch effect.
If a large loss of variance is observed along with a small batch effect in a given merge step, users can set \code{min.batch.skip} to simply skip correction in that step.
}

\examples{
B1 <- matrix(rnorm(10000, -1), ncol=50) # Batch 1 
B2 <- matrix(rnorm(10000, 1), ncol=50) # Batch 2
out <- fastMNN(B1, B2)

# Corrected values for use in clustering, etc.
str(reducedDim(out)) 

# Extracting corrected expression values for gene 10.
summary(assay(out)[10,])

}
\references{
Haghverdi L, Lun ATL, Morgan MD, Marioni JC (2018).
Batch effects in single-cell RNA-sequencing data are corrected by matching mutual nearest neighbors.
\emph{Nat. Biotechnol.} 36(5):421

Lun ATL (2018).
Further MNN algorithm development.
\url{https://MarioniLab.github.io/FurtherMNN2018/theory/description.html}
}
\seealso{
\code{\link{cosineNorm}} and \code{\link{multiBatchPCA}}, to obtain the values to be corrected.

\code{\link{reducedMNN}}, for a version of the function that operates in low-dimensional space.

\code{\link{mnnCorrect}} for the \dQuote{classic} version of the MNN correction algorithm.
}
\author{
Aaron Lun
}
