Skip to contents

Precompute a reusable UMAP initialization

Source: R/umap_init.R
umap_init.Rd

umap_init() separates UMAP neighbor search, graph construction, and initialization from stochastic optimization. The returned object can be passed directly to umap_knn() so repeated or cross-backend runs reuse the same KNN graph and initial coordinates.

Usage

umap_init(
  x,
  distances = NULL,
  n_neighbors = NULL,
  n_components = 2L,
  metric = c("euclidean", "cosine", "correlation"),
  backend = NULL,
  seed = 4L,
  n.cores = NULL,
  graph_mode = c("fuzzy", "binary")
)

Arguments

x

Numeric data, a KNN object, or an object returned by prepare_umap_knn().

distances

Optional KNN distance matrix when x is an index matrix.

n_neighbors

Number of non-self neighbors when x is data. NULL uses the package's size-aware default.

n_components

Output dimensionality.

metric

Distance metric used only when KNN must be computed.

backend

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

seed

Random seed.

n.cores

Number of CPU cores.

graph_mode

UMAP graph weighting. "fuzzy" is the standard default; "binary" requests the adjacency-only sensitivity graph.

Value

A fastEmbedR_umap_initialization object with layout, prepared, resolved parameters, and component timings. Pass the complete object to umap_knn() or use its layout component directly for diagnostics.

Details

For the fuzzy graph, CPU initialization is computed from the prepared CSR graph, while native Metal or CUDA spectral kernels are used when requested and available. Binary initialization is computed from the same unit-weight CSR graph used by the optimizer, so its mathematical input is unchanged. Explicit GPU requests fail when the corresponding native backend is unavailable.

CUDA KNN input is materialized on the host only for this standalone diagnostic API. The ordinary one-call CUDA UMAP path remains device resident.

Examples

x <- scale(as.matrix(iris[, 1:4]))
initialization <- umap_init(
    x,
    n_neighbors = 15,
    backend = "cpu",
    graph_mode = "fuzzy",
    seed = 1
)
layout <- umap_knn(initialization, backend = "cpu", seed = 1)
plot(layout, pch = 21, bg = iris$Species)