% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/AllGenerics.R, R/runUMAP.R
\name{calculateUMAP}
\alias{calculateUMAP}
\alias{runUMAP}
\alias{calculateUMAP,ANY-method}
\alias{calculateUMAP,SummarizedExperiment-method}
\alias{calculateUMAP,SingleCellExperiment-method}
\title{Perform UMAP on cell-level data}
\usage{
calculateUMAP(x, ...)

\S4method{calculateUMAP}{ANY}(
  x,
  ncomponents = 2,
  ntop = 500,
  subset_row = NULL,
  scale = FALSE,
  transposed = FALSE,
  pca = if (transposed) NULL else 50,
  n_neighbors = 15,
  n_threads = NULL,
  ...,
  external_neighbors = FALSE,
  BNPARAM = KmknnParam(),
  BPPARAM = SerialParam(),
  use_densvis = FALSE,
  dens_frac = 0.3,
  dens_lambda = 0.1
)

\S4method{calculateUMAP}{SummarizedExperiment}(x, ..., exprs_values = "logcounts", assay.type = exprs_values)

\S4method{calculateUMAP}{SingleCellExperiment}(
  x,
  ...,
  pca = if (!is.null(dimred)) NULL else 50,
  exprs_values = "logcounts",
  dimred = NULL,
  n_dimred = NULL,
  assay.type = exprs_values
)

runUMAP(x, ..., altexp = NULL, name = "UMAP")
}
\arguments{
\item{x}{For \code{calculateUMAP}, a numeric matrix of log-expression values where rows are features and columns are cells.
Alternatively, a \linkS4class{SummarizedExperiment} or \linkS4class{SingleCellExperiment} containing such a matrix.

For \code{runTSNE}, a \linkS4class{SingleCellExperiment} object containing such a matrix.}

\item{...}{For the \code{calculateUMAP} generic, additional arguments to pass to specific methods.
For the ANY method, additional arguments to pass to \code{\link[uwot]{umap}}.
For the SummarizedExperiment and SingleCellExperiment methods, additional arguments to pass to the ANY method.

For \code{runUMAP}, additional arguments to pass to \code{calculateUMAP}.}

\item{ncomponents}{Numeric scalar indicating the number of UMAP dimensions to obtain.}

\item{ntop}{Numeric scalar specifying the number of features with the highest variances to use for dimensionality reduction.}

\item{subset_row}{Vector specifying the subset of features to use for dimensionality reduction.
This can be a character vector of row names, an integer vector of row indices or a logical vector.}

\item{scale}{Logical scalar, should the expression values be standardized?}

\item{transposed}{Logical scalar, is \code{x} transposed with cells in rows?}

\item{pca}{Integer scalar specifying how many PCs should be used as input into the UMAP algorithm.
By default, no PCA is performed if the input is a dimensionality reduction result.}

\item{n_neighbors}{Integer scalar, number of nearest neighbors to identify when constructing the initial graph.}

\item{n_threads}{Integer scalar specifying the number of threads to use in \code{\link[uwot]{umap}}.
If \code{NULL} and \code{BPPARAM} is a \linkS4class{MulticoreParam}, it is set to the number of workers in \code{BPPARAM};
otherwise, the \code{\link[uwot]{umap}} defaults are used.}

\item{external_neighbors}{Logical scalar indicating whether a nearest neighbors search should be computed externally with \code{\link{findKNN}}.}

\item{BNPARAM}{A \linkS4class{BiocNeighborParam} object specifying the neighbor search algorithm to use when \code{external_neighbors=TRUE}.}

\item{BPPARAM}{A \linkS4class{BiocParallelParam} object specifying whether the PCA should be parallelized.}

\item{use_densvis}{Logical scalar indicating whether \code{\link[densvis]{densne}} should be used to perform density-preserving t-SNE.}

\item{dens_frac, dens_lambda}{See \code{\link[densvis]{densne}}}

\item{exprs_values}{Alias to \code{assay.type}.}

\item{assay.type}{Integer scalar or string indicating which assay of \code{x} contains the expression values.}

\item{dimred}{String or integer scalar specifying the existing dimensionality reduction results to use.}

\item{n_dimred}{Integer scalar or vector specifying the dimensions to use if \code{dimred} is specified.}

\item{altexp}{String or integer scalar specifying an alternative experiment containing the input data.}

\item{name}{String specifying the name to be used to store the result in the \code{\link{reducedDims}} of the output.}
}
\value{
For \code{calculateUMAP}, a matrix is returned containing the UMAP coordinates for each cell (row) and dimension (column).

For \code{runUMAP}, a modified \code{x} is returned that contains the UMAP coordinates in \code{\link{reducedDim}(x, name)}.
}
\description{
Perform uniform manifold approximation and projection (UMAP) for the cells, based on the data in a SingleCellExperiment object.
}
\details{
The function \code{\link[uwot]{umap}} is used internally to compute the UMAP. 
Note that the algorithm is not deterministic, so different runs of the function will produce differing results. 
Users are advised to test multiple random seeds, and then use \code{\link{set.seed}} to set a random seed for replicable results. 

If \code{external_neighbors=TRUE}, the nearest neighbor search is conducted using a different algorithm to that in the \code{\link[uwot]{umap}} function.
This can be parallelized or approximate to achieve greater speed for large data sets.
The neighbor search results are then used directly to create the UMAP embedding.
}
\section{Feature selection}{

This section is relevant if \code{x} is a numeric matrix of (log-)expression values with features in rows and cells in columns;
or if \code{x} is a \linkS4class{SingleCellExperiment} and \code{dimred=NULL}.
In the latter, the expression values are obtained from the assay specified by \code{assay.type}.

The \code{subset_row} argument specifies the features to use for dimensionality reduction.
The aim is to allow users to specify highly variable features to improve the signal/noise ratio,
or to specify genes in a pathway of interest to focus on particular aspects of heterogeneity.

If \code{subset_row=NULL}, the \code{ntop} features with the largest variances are used instead.
We literally compute the variances from the expression values without considering any mean-variance trend,
so often a more considered choice of genes is possible, e.g., with \pkg{scran} functions.
Note that the value of \code{ntop} is ignored if \code{subset_row} is specified.

If \code{scale=TRUE}, the expression values for each feature are standardized so that their variance is unity.
This will also remove features with standard deviations below 1e-8.
}

\section{Using reduced dimensions}{

If \code{x} is a \linkS4class{SingleCellExperiment}, the method can be applied on existing dimensionality reduction results in \code{x} by setting the \code{dimred} argument.
This is typically used to run slower non-linear algorithms (t-SNE, UMAP) on the results of fast linear decompositions (PCA).
We might also use this with existing reduced dimensions computed from \emph{a priori} knowledge (e.g., gene set scores), where further dimensionality reduction could be applied to compress the data.

The matrix of existing reduced dimensions is taken from \code{\link{reducedDim}(x, dimred)}.
By default, all dimensions are used to compute the second set of reduced dimensions.
If \code{n_dimred} is also specified, only the first \code{n_dimred} columns are used.
Alternatively, \code{n_dimred} can be an integer vector specifying the column indices of the dimensions to use.

When \code{dimred} is specified, no additional feature selection or standardization is performed.
This means that any settings of \code{ntop}, \code{subset_row} and \code{scale} are ignored.

If \code{x} is a numeric matrix, setting \code{transposed=TRUE} will treat the rows as cells and the columns as the variables/diemnsions.
This allows users to manually pass in dimensionality reduction results without needing to wrap them in a \linkS4class{SingleCellExperiment}.
As such, no feature selection or standardization is performed, i.e., \code{ntop}, \code{subset_row} and \code{scale} are ignored.
}

\section{Using alternative Experiments}{

This section is relevant if \code{x} is a \linkS4class{SingleCellExperiment} and \code{altexp} is not \code{NULL}.
In such cases, the method is run on data from an alternative \linkS4class{SummarizedExperiment} nested within \code{x}.
This is useful for performing dimensionality reduction on other features stored in \code{\link{altExp}(x, altexp)}, e.g., antibody tags. 

Setting \code{altexp} with \code{assay.type} will use the specified assay from the alternative SummarizedExperiment.
If the alternative is a SingleCellExperiment, setting \code{dimred} will use the specified dimensionality reduction results from the alternative. 
This option will also interact as expected with \code{n_dimred}.

Note that the output is still stored in the \code{\link{reducedDims}} of the output SingleCellExperiment.
It is advisable to use a different \code{name} to distinguish this output from the results generated from the main experiment's assay values.
}

\examples{
example_sce <- mockSCE() 
example_sce <- logNormCounts(example_sce)

example_sce <- runUMAP(example_sce)
reducedDimNames(example_sce)
head(reducedDim(example_sce))
}
\references{
McInnes L, Healy J, Melville J (2018).
UMAP: uniform manifold approximation and projection for dimension reduction.
arXiv.
}
\seealso{
\code{\link[uwot]{umap}}, for the underlying calculations.

\code{\link{plotUMAP}}, to quickly visualize the results.
}
\author{
Aaron Lun
}
