Skip to contents

Precompute reusable UMAP graph state from KNN

Source: R/fast_knn_umap.R
prepare_umap_knn.Rd

prepare_umap_knn() builds the CSR graph once from a KNN object or index and distance matrices. The result can be passed to umap_knn() repeatedly with different seeds without rebuilding the graph or recomputing epochs_per_sample.

Usage

prepare_umap_knn(
  indices,
  distances = NULL,
  backend = NULL,
  n.cores = NULL,
  graph_mode = c("fuzzy", "binary")
)

Arguments

indices

Integer matrix of nearest-neighbor indices, one row per observation, or a KNN object containing indices and distances. One-based and zero-based indices are accepted. A self-neighbor first column is removed automatically.

distances

Numeric matrix matching indices. Leave as NULL when indices is a KNN object.

backend

Execution backend: "cpu", "cuda", or "metal".

n.cores

Requested CPU core count. CPU UMAP currently uses at most four workers and records both requested and effective values. NULL selects a size-aware default from one to four workers. Native GPU backends ignore this argument.

graph_mode

Graph weighting mode. "fuzzy" (the default) uses standard UMAP fuzzy graph weights. "binary" uses a symmetric unit-weight sensitivity graph.

Value

A prepared UMAP object containing the KNN, CSR graph, and resolved UMAP graph schedule.

Examples

x <- scale(as.matrix(iris[, 1:4]))
d <- as.matrix(stats::dist(x))
diag(d) <- Inf
k <- 15L
idx <- t(apply(d, 1L, order))[, seq_len(k), drop = FALSE]
dst <- matrix(d[cbind(rep(seq_len(nrow(d)), each = k), as.vector(t(idx)))],
    nrow = nrow(d), byrow = TRUE
)
prep <- prepare_umap_knn(idx, dst)
y1 <- umap_knn(prep, seed = 1)
y2 <- umap_knn(prep, seed = 2)