runUMAP {scater} | R Documentation

## Perform UMAP on cell-level data

### Description

Perform uniform manifold approximation and projection (UMAP) for the cells, based on the data in a SingleCellExperiment object.

### Usage

    runUMAP(object, ncomponents = 2, ntop = 500, feature_set = NULL,
      exprs_values = "logcounts", scale_features = TRUE,
      use_dimred = NULL, n_dimred = NULL, pca = 50, n_neighbors = 15,
      external_neighbors = FALSE, BNPARAM = KmknnParam(),
      BPPARAM = SerialParam(), ...)

### Arguments

`object` | A SingleCellExperiment object.
`ncomponents` | Numeric scalar indicating the number of UMAP dimensions to obtain.
`ntop` | Numeric scalar specifying the number of most variable features to use for UMAP.
`feature_set` | Character vector of row names, a logical vector or a numeric vector of indices indicating a set of features to use for UMAP. This will override any `ntop` argument if specified.
`exprs_values` | Integer scalar or string indicating which assay of `object` should be used to obtain the expression values for the calculations.
`scale_features` | Logical scalar, should the expression values be standardised so that each feature has unit variance?
`use_dimred` | String or integer scalar specifying the entry of `reducedDims(object)` to use as input to `Rtsne`. Default is to not use existing reduced dimension results.
`n_dimred` | Integer scalar, number of dimensions of the reduced dimension slot to use when `use_dimred` is supplied. Defaults to all available dimensions.
`pca` | Integer scalar specifying how many PCs should be used as input into UMAP, if the PCA is to be recomputed on the subsetted expression matrix. Only used when codeuse_dimred=NULL, and if `pca=NULL`, no PCA is performed at all.
`n_neighbors` | Integer scalar, number of nearest neighbors to identify when constructing the initial graph.
`external_neighbors` | Logical scalar indicating whether a nearest neighbors search should be computed externally with `findKNN`.
`BNPARAM` | A BiocNeighborParam object specifying the neighbor search algorithm to use when `external_neighbors=TRUE`.
`BPPARAM` | A BiocParallelParam object specifying how the neighbor search should be parallelized when `external_neighbors=TRUE`.
`...` | Additional arguments to pass to `umap`.

### Details

The function `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 `set.seed` to set a random seed for replicable results.

Setting `use_dimred` allows users to easily perform UMAP on low-rank approximations of the original expression matrix (e.g., after PCA). In such cases, arguments such as `ntop`, `feature_set`, `exprs_values` and `scale_features` will be ignored.

If `external_neighbors=TRUE`, the nearest neighbor search step is conducted using a different algorithm to that in the `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.

### Value

A SingleCellExperiment object containing the coordinates of the first `ncomponent` UMAP dimensions for each cell. This is stored in the `"UMAP"` entry of the `reducedDims` slot.

### Author(s)

Aaron Lun

### References

McInnes L, Healy J (2018). UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction. arXiv.

### See Also

`umap`, `plotUMAP`

### Examples

    ## Set up an example SingleCellExperiment
    data("sc_example_counts")
    data("sc_example_cell_info")
    example_sce <- SingleCellExperiment(
        assays = list(counts = sc_example_counts),
        colData = sc_example_cell_info
    )
    example_sce <- normalize(example_sce)

    example_sce <- runUMAP(example_sce)
    reducedDimNames(example_sce)
    head(reducedDim(example_sce))

[Package scater version 1.12.2 Index]