Rust-based densMAP

Performs densMAP dimensionality reduction on the input data. densMAP is UMAP with an added density-preserving term, so a tight cluster stays tight and a diffuse one stays diffuse. Plain UMAP gives you no such guarantee: relative sizes in the embedding mean nothing. This function provides a user-friendly interface with input validation before calling the Rust implementation.

Usage

densmap(
  data,
  knn = NULL,
  n_dim = 2L,
  k = 15L,
  min_dist = 0.5,
  spread = 1,
  knn_method = c("kmknn", "balltree", "hnsw", "annoy", "nndescent", "exhaustive", "ivf"),
  nn_params = params_nn(),
  umap_params = params_umap(),
  dens_params = params_densmap(),
  seed = 42L,
  use_high_precision = NULL,
  .verbose = TRUE
)

Arguments

data

Numerical matrix or data frame. The data to embed of shape samples x features. Will be coerced to a matrix.

knn

Optional NearestNeighbours class. If provided, densMAP will skip the k-nearest neighbour graph generation and use this one. Defaults to NULL.

n_dim

Integer. Number of dimensions in the embedding space. Defaults to 2L.

k

Integer. Number of nearest neighbours to consider for manifold approximation. Larger values result in more global structure being preserved. Defaults to 15L.

min_dist

Numeric. Minimum distance between points in the embedding. Controls how tightly points are packed. Smaller values result in more clustered embeddings. Must be >= 0. Defaults to 0.5. If you use SGD, consider reducing this!

spread

Numeric. Effective scale of embedded points. Determines the scale at which embedded points will be spread out. Defaults to 1.0.

knn_method

Character. (Approximate) Nearest neighbour method to use. One of "kmknn", "hnsw", "annoy", "nndescent", "balltree", "ivf" or "exhaustive". Defaults to "kmknn".

nn_params

Named list. Nearest neighbour search parameters, see params_nn().

umap_params

Named list. UMAP algorithm parameters, see params_umap().

dens_params

Named list. Density-preservation parameters, see params_densmap().

seed

Integer. Random seed for reproducibility. Defaults to 42L.

use_high_precision

Optional boolean. Gives fine-grained control over fp32 vs fp64 usage.

.verbose

Logical. Controls verbosity. Defaults to TRUE.

Value

A numerical matrix with dimensions samples x n_dim containing the densMAP embedding.

Details

Setting lambda to 0 in params_densmap() recovers plain umap() exactly. The density term is only active over the final frac of the epochs, which is why it costs comparatively little.

References

Narayan, Berger & Cho, Nat. Biotechnol., 2021