Run opinionated fixed-policy UMAP from data or precomputed KNN

umap() is a small convenience wrapper. If data is already a list of KNN indices and distances, it calls umap_knn() directly. Otherwise it preprocesses the data, computes KNN once with fastEmbedR's native backend, and embeds from that KNN graph.

Usage

umap(
  data,
  n_neighbors = NULL,
  n_components = 2L,
  standardize = FALSE,
  pca_dims = NULL,
  metric = c("euclidean", "cosine", "correlation"),
  nn = NULL,
  seed = 4L,
  backend = NULL,
  n.cores = NULL,
  keep_knn = FALSE,
  graph_mode = c("fuzzy", "binary"),
  verbose = FALSE,
  landmarks = FALSE,
  transform_k = NULL,
  massive = "off",
  output = NULL,
  chunk_rows = NULL,
  memory_limit = "8GB",
  refinement_epochs = 0L,
  local_refine = FALSE,
  local_neighbors = 15L,
  overlap_rows = 500L,
  devices = NULL,
  landmark_method = "reservoir",
  init = NULL,
  layout_storage = "memory",
  checkpoint = FALSE,
  resume = FALSE
)

Arguments

data: Numeric matrix/data frame, or a list containing KNN indices and distances.
n_neighbors: Number of non-self neighbors. NULL chooses the package default for the data size.
n_components: Output dimensionality. The CPU backend supports positive dimensions. Metal and CUDA support two- and three-dimensional embeddings.
standardize: Center and scale columns before KNN when data is a matrix. Defaults to FALSE so one-call results match a KNN object computed from the supplied matrix.
pca_dims: Optional PCA dimension before KNN.
metric: KNN distance metric for one-call matrix input: "euclidean", "cosine", or "correlation".
nn: Optional precomputed KNN result for resident matrix input. In EXPERIMENTAL massive = "landmark" mode, a previous massive landmark embedding reuses its saved selection and query-to-landmark KNN. Its source, reference, neighbor count, and backend must match.
seed: Random seed.
backend: Execution backend: "cpu", "cuda", or "metal". CPU KNN uses package-native exact search below 5,000 rows and HNSW otherwise. Metal uses package-native exact or recall-tuned IVF-Flat search. CUDA uses cuVS brute-force exact search below 100,000 rows and cuVS IVF-Flat above that threshold. The KNN result stays on the device through graph construction and optimization. GPU requests must resolve to a real native backend; the package does not relabel CPU work as GPU.
n.cores: Requested CPU core count. For matrix input, the value is passed to CPU PCA preprocessing, KNN, and UMAP. UMAP uses at most four workers and records both requested and effective values. With NULL, PCA uses options(n.cores) (one by default); KNN and UMAP use their stage defaults. Native GPU stages ignore this argument.
keep_knn: Keep KNN matrices in the returned object.
graph_mode: Graph weighting mode. "fuzzy" (the default) uses the standard UMAP fuzzy graph. "binary" uses a symmetric unit-weight graph as an adjacency-only sensitivity approximation; it is not standard UMAP or necessarily faster.
verbose: Print progress.
landmarks: FALSE (the default) embeds all observations. A fraction in (0, 1), a positive landmark count, or explicit row indices enables landmark embedding followed by fixed-reference projection of the remaining rows.
transform_k: Number of landmark neighbors used to project non-landmark observations. Used only when landmarks enables landmarking and defaults to n_neighbors.
massive: "off" (default), experimental "landmark", or "out_of_core_graph". Landmarking is always explicit. The full-graph route needs a symmetric fuzzy massive_umap_fuzzy_graph() and file-backed init. The experimental CUDA full-graph route requires a device-resident 2D layout.
output: New .f32 path for experimental file-backed coordinates.
chunk_rows: Maximum experimental query rows per batch.
memory_limit: Conservative experimental RAM budget.
refinement_epochs: Fixed-reference UMAP projection epochs in experimental mode. Defaults to zero on CPU and CUDA; CUDA currently rejects positive values.
local_refine: Enable EXPERIMENTAL bounded query-to-query graph refinement in massive landmark mode. Requires CPU and positive epochs.
local_neighbors: Non-self neighbors in each local query window.
overlap_rows: Extra rows on each side of a local query window; at least local_neighbors.
devices: Optional CUDA device indices for experimental landmark query projection. Reference fitting and KNN use the first device.
landmark_method: Sampling method for experimental landmark mode: "reservoir" (default) or "random" for fast random-access storage. Auto mode uses ordinary UMAP when its conservative memory estimate fits; otherwise it reports and runs approximate landmark UMAP. The landmark route requires a file-backed massive_matrix() and a new .f32 output.
init: File-backed 2D or 3D initial coordinates for experimental full-graph UMAP. Other routes do not accept this argument.
layout_storage: "memory" (default), "mmap" for a writable CPU mapping, or "managed" for CUDA managed-memory coordinates in experimental full-graph UMAP. CUDA rejects "mmap".
checkpoint: Save experimental workflow stages and completed batches. Only available for massive landmark or full-graph mode.
resume: Continue a matching interrupted experimental workflow. Changed input, backend, or fit controls fail without recomputation.

Value

A fastEmbedR_embedding object. Landmark fits also contain model, which can be passed to project_landmark_model() for new observations.

Details

umap() is an opinionated high-throughput UMAP implementation rather than a drop-in interface for every UMAP hyperparameter. The public matrix-input API exposes neighborhood size, distance metric, graph weighting, output dimension, preprocessing, backend, seed, and CPU thread count. In the current release, epochs, minimum distance, spread, learning rate, repulsion strength, negative-sample rate, spectral iteration count, and asynchronous update mode are selected internally. The resolved values and rule names are stored in fit$parameters.

The default policy uses 500 epochs below 10,000 observations and 200 epochs for larger inputs, increasing to 300 for high-variability distance profiles; five negative samples, spread 1, and repulsion strength 1 are fixed. Minimum distance is normally 0.01 and becomes 0.1 only under the documented wide-shell profile; learning rate is correspondingly 1 or 1.25. Use umap_init() to precompute and reuse package-native initial coordinates, or umap_knn() to supply an externally controlled KNN graph. These controls are scientifically consequential; fixing them is a scope decision made to keep one tested objective and update schedule aligned across CPU, Metal, and CUDA, not a claim that the values are universally optimal. Arbitrary min_dist, spread, epoch, learning-rate, negative-sampling, or optimizer-mode sweeps should use a general-purpose UMAP implementation; fastEmbedR does not claim API or parameter interchangeability with those packages.

Landmark mode fits the requested fuzzy or binary UMAP graph on the landmark rows, projects the remaining rows with query-to-reference KNN, and optionally refines only projected rows while landmark coordinates remain fixed. Metal and CUDA landmark refinement currently requires 2D output; 3D landmark requests fail explicitly. Resident precomputed KNN input cannot be combined with landmarking. The returned model retains the fitted preprocessing transform so new data can be supplied in the same original feature space.

Examples

x <- scale(as.matrix(iris[, 1:4]))
fit <- umap(x, n_neighbors = 15, seed = 1)
plot(fit)