Skip to contents

Run UMAP

runUMAP.Rd

Run UMAP on SpatialMap objects, with parameters passed to the uwot implementation of the UMAP algorithm.

Usage

runUMAP(
  object,
  data.slot = "Data",
  name = "umap",
  PCA = T,
  scale = T,
  dims = NULL,
  features = NULL,
  analyze = NULL,
  cores = NULL,
  n_neighbors = 30,
  nn_method = "annoy",
  metric = "cosine",
  spread = 1,
  min_dist = 0.3,
  set_op_mix_ratio = 1,
  local_connectivity = 1,
  bandwidth = 1,
  ret_model = T,
  ret_nn = T,
  fast_sgd = FALSE,
  n_threads = NULL,
  n_sgd_threads = NULL,
  verbose = T,
  ...
)

Arguments

object

A SpatialMap object

data.slot

Which data slot the function will pull biomarker expressions from.

name

The name of the resulting Representation and NN in the returned SM object.

PCA

Whether to perform PCA first. Can also pass a string to this argument specifying the name of an already computed representation.

scale

When performing PCA, this is passed to runPCA

dims

How many principal components from a newly computed PCA to use for UMAP.

features

Which features to pass to PCA/UMAP

analyze

What to analyze (and how). The options are "regions", NULL (activeAnalysis), the name of a currently existing formal analysis, or the name of a column in object's projectMetadata (an "informal" analysis).

cores

Parallelization options

n_neighbors

The size of local neighborhood (in terms of number of neighboring sample points) used for manifold approximation. Larger values result in more global views of the manifold, while smaller values result in more local data being preserved. In general values should be in the range 2 to 100.

nn_method

Method for finding nearest neighbors. Options are:

  • "fnn". Use exact nearest neighbors via the FNN package.

  • "annoy" Use approximate nearest neighbors via the RcppAnnoy package.

  • "hnsw" Use approximate nearest neighbors with the Hierarchical Navigable Small World (HNSW) method (Malkov and Yashunin, 2018) via the RcppHNSW package. RcppHNSW is not a dependency of this package: this option is only available if you have installed RcppHNSW yourself. Also, HNSW only supports the following arguments for metric and target_metric: "euclidean", "cosine" and "correlation".

  • "nndescent" Use approximate nearest neighbors with the Nearest Neighbor Descent method (Dong et al., 2011) via the rnndescent package. rnndescent is not a dependency of this package: this option is only available if you have installed rnndescent yourself.

By default, if X has less than 4,096 vertices, the exact nearest neighbors are found. Otherwise, approximate nearest neighbors are used. You may also pass pre-calculated nearest neighbor data to this argument. It must be one of two formats, either a list consisting of two elements:

  • "idx". A n_vertices x n_neighbors matrix containing the integer indexes of the nearest neighbors in X. Each vertex is considered to be its own nearest neighbor, i.e. idx[, 1] == 1:n_vertices.

  • "dist". A n_vertices x n_neighbors matrix containing the distances of the nearest neighbors.

or a sparse distance matrix of type dgCMatrix, with dimensions n_vertices x n_vertices. Distances should be arranged by column, i.e. a non-zero entry in row j of the ith column indicates that the jth observation in X is a nearest neighbor of the ith observation with the distance given by the value of that element. The n_neighbors parameter is ignored when using precomputed nearest neighbor data. If using the sparse distance matrix input, each column can contain a different number of neighbors.

metric

Type of distance metric to use to find nearest neighbors. For nn_method = "annoy" this can be one of:

  • "euclidean" (the default)

  • "cosine"

  • "manhattan"

  • "hamming"

  • "correlation" (a distance based on the Pearson correlation)

  • "categorical" (see below)

For nn_method = "hnsw" this can be one of:

  • "euclidean"

  • "cosine"

  • "correlation"

If rnndescent is installed and nn_method = "nndescent" is specified then many more metrics are avaiable, including:

  • "braycurtis"

  • "canberra"

  • "chebyshev"

  • "dice"

  • "hamming"

  • "hellinger"

  • "jaccard"

  • "jensenshannon"

  • "kulsinski"

  • "rogerstanimoto"

  • "russellrao"

  • "sokalmichener"

  • "sokalsneath"

  • "spearmanr"

  • "symmetrickl"

  • "tsss"

  • "yule"

For more details see the package documentation of rnndescent. For nn_method = "fnn", the distance metric is always "euclidean".

If X is a data frame or matrix, then multiple metrics can be specified, by passing a list to this argument, where the name of each item in the list is one of the metric names above. The value of each list item should be a vector giving the names or integer ids of the columns to be included in a calculation, e.g. metric = list(euclidean = 1:4, manhattan = 5:10).

Each metric calculation results in a separate fuzzy simplicial set, which are intersected together to produce the final set. Metric names can be repeated. Because non-numeric columns are removed from the data frame, it is safer to use column names than integer ids.

Factor columns can also be used by specifying the metric name "categorical". Factor columns are treated different from numeric columns and although multiple factor columns can be specified in a vector, each factor column specified is processed individually. If you specify a non-factor column, it will be coerced to a factor.

For a given data block, you may override the pca and pca_center arguments for that block, by providing a list with one unnamed item containing the column names or ids, and then any of the pca or pca_center overrides as named items, e.g. metric = list(euclidean = 1:4, manhattan = list(5:10, pca_center = FALSE)). This exists to allow mixed binary and real-valued data to be included and to have PCA applied to both, but with centering applied only to the real-valued data (it is typical not to apply centering to binary data before PCA is applied).

spread

The effective scale of embedded points. In combination with min_dist, this determines how clustered/clumped the embedded points are.

min_dist

The effective minimum distance between embedded points. Smaller values will result in a more clustered/clumped embedding where nearby points on the manifold are drawn closer together, while larger values will result on a more even dispersal of points. The value should be set relative to the spread value, which determines the scale at which embedded points will be spread out.

set_op_mix_ratio

Interpolate between (fuzzy) union and intersection as the set operation used to combine local fuzzy simplicial sets to obtain a global fuzzy simplicial sets. Both fuzzy set operations use the product t-norm. The value of this parameter should be between 0.0 and 1.0; a value of 1.0 will use a pure fuzzy union, while 0.0 will use a pure fuzzy intersection.

local_connectivity

The local connectivity required -- i.e. the number of nearest neighbors that should be assumed to be connected at a local level. The higher this value the more connected the manifold becomes locally. In practice this should be not more than the local intrinsic dimension of the manifold.

bandwidth

The effective bandwidth of the kernel if we view the algorithm as similar to Laplacian Eigenmaps. Larger values induce more connectivity and a more global view of the data, smaller values concentrate more locally.

ret_model

If TRUE, then return extra data that can be used to add new data to an existing embedding via umap_transform. The embedded coordinates are returned as the list item embedding. If FALSE, just return the coordinates. This parameter can be used in conjunction with ret_nn and ret_extra. Note that some settings are incompatible with the production of a UMAP model: external neighbor data (passed via a list to nn_method), and factor columns that were included via the metric parameter. In the latter case, the model produced is based only on the numeric data. A transformation using new data is possible, but the factor columns in the new data are ignored. Note that setting ret_model = TRUE forces the use of the approximate nearest neighbors method. Because small datasets would otherwise use exact nearest neighbor calculations, setting ret_model = TRUE means that different results may be returned for small datasets in terms of both the returned nearest neighbors (if requested) and the final embedded coordinates, compared to ret_model = FALSE, even if the random number seed is fixed. To avoid this, explicitly set nn_method = "annoy" in the ret_model = FALSE case.

ret_nn

If TRUE, then in addition to the embedding, also return nearest neighbor data that can be used as input to nn_method to avoid the overhead of repeatedly calculating the nearest neighbors when manipulating unrelated parameters (e.g. min_dist, n_epochs, init). See the "Value" section for the names of the list items. If FALSE, just return the coordinates. Note that the nearest neighbors could be sensitive to data scaling, so be wary of reusing nearest neighbor data if modifying the scale parameter. This parameter can be used in conjunction with ret_model and ret_extra.

fast_sgd

If TRUE, then the following combination of parameters is set: pcg_rand = TRUE, n_sgd_threads = "auto" and approx_pow = TRUE. The default is FALSE. Setting this to TRUE will speed up the stochastic optimization phase, but give a potentially less accurate embedding, and which will not be exactly reproducible even with a fixed seed. For visualization, fast_sgd = TRUE will give perfectly good results. For more generic dimensionality reduction, it's safer to leave fast_sgd = FALSE. If fast_sgd = TRUE, then user-supplied values of pcg_rand, n_sgd_threads, and approx_pow are ignored.

n_threads

Number of threads to use (except during stochastic gradient descent). Default is half the number of concurrent threads supported by the system. For nearest neighbor search, only applies if nn_method = "annoy". If n_threads > 1, then the Annoy index will be temporarily written to disk in the location determined by tempfile.

n_sgd_threads

Number of threads to use during stochastic gradient descent. If set to > 1, then be aware that if batch = FALSE, results will not be reproducible, even if set.seed is called with a fixed seed before running. Set to "auto" to use the same value as n_threads.

verbose

If TRUE, log details to the console.

...

additional arguments passed to uwot::umap

Value

A SpatialMap object with new NNs and representations created:

  1. If PCA = T, then a new representation named "pca" will be added containing the first n principle components depending on the value set to dim

  2. A new representation named name ("umap" by default) will be added containing a 2D UMAP embedding

  3. A new NN named name ("umap" by default) will be added containing the n_neighbors nearest neighbors of each cell in biomarker expression space (computed as an intermediate by uwot::umap and useful later for clustering).

If analyze = "regions" or the activeAnalysis is "regions", then the algorithm will be run on a region-by-region basis, and these NNs and representations will be added to each Region. If analyze is a formal analysis (e.g. "combined"), or the activeAnalysis is set to a formal analysis, then the NN and representations will be added to that Analysis.

Details

See vignette("AnalysisGuide3_Unsupervised_clustering") & vignette("AnalysisGuide4_Subsetting_and_subclustering") for a representative workflow that uses this function.

Scroll to top