Run UMAP from precomputed nearest neighbors

Usage

umap_knn(
  indices,
  distances = NULL,
  n_components = 2L,
  seed = 42L,
  verbose = FALSE,
  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.
n_components: Output dimensionality. The CPU backend supports positive dimensions. Metal and CUDA support two- and three-dimensional embeddings.
seed: Integer random seed.
verbose: Print native optimizer progress.
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

An embedding matrix with nrow(indices) rows and n_components columns. Float32 KNN input returns a float::float32 layout; ordinary R input returns a numeric matrix. Resolved settings are stored in attr(layout, "fastEmbedR_config").

Details

This KNN-input function exposes the same deliberately constrained optimizer policy as umap(). It reuses the supplied neighbors but still selects epochs, minimum distance, spread, learning rate, repulsion strength, negative-sample rate, spectral iterations, and backend update mode internally. The resolved configuration is attached as attr(layout, "fastEmbedR_config"). Pass an object from umap_init() to reuse both the prepared graph and package-native initialization. Prepared CUDA graph reuse currently supports two dimensions; ordinary KNN CUDA fits also support three. This API is intended for fixed-boundary comparisons and repeated seeds, not arbitrary UMAP hyperparameter sweeps.

Examples

x <- scale(as.matrix(iris[, 1:4]))
d <- as.matrix(stats::dist(x))
diag(d) <- Inf
k <- 10L
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
)
layout <- umap_knn(idx, dst, seed = 1)
plot(layout, pch = 21, bg = iris$Species)