UMAP: Graph-Based Embeddings and Tradeoffs

UMAP's parameters are modeling choices, not cosmetic controls. The clearest statements of what the resulting picture does not carry come from the people who maintain the tools. A whole second package exists because of one of them. The Bioconductor package densvis ships a density-preserving objective, and it gives its reason for existing plainly: “These embeddings may not accurately represent the local density of data in the original space, resulting in misleading visualisations where the space given to clusters of data does not represent the fraction of the high dimensional space that they occupy.”

“A UMAP plot” names a picture, not a procedure. The reference implementation, umap-learn 0.5.12, documents its defaults as “n_neighbors: float (optional, default 15)”, “min_dist: float (optional, default 0.1)” and “metric: string or function (optional, default 'euclidean')”. The Seurat R package reaches UMAP through a different engine. The Usage block of RunUMAP in Seurat 5.5.1 reads “umap.method = "uwot", n.neighbors = 30L, n.components = 2L, metric = "cosine", n.epochs = NULL, learning.rate = 1, min.dist = 0.3”, and the Satija lab's own documentation site gives the same defaults.

Thirty neighbours instead of fifteen. A minimum distance of 0.3 instead of 0.1. Cosine instead of euclidean. A different implementation underneath. None of that is a tuning disagreement downstream of a shared object: the same data handed to the two standard tools is turned into two different neighbour graphs before any optimisation begins. Both outputs are called UMAP in the caption. So a team refits its map with new data, or moves between tools, and expects the regions to stay where they were. It has treated a fitted, stochastic graph embedding as a coordinate system, without versioning or alignment. A permanent customer atlas is the wrong idea of what it owns.

UMAP builds a weighted graph in the original space, then looks for a low-dimensional graph with similar fuzzy connectivity. A metric and a neighbor count identify local candidate relationships. Distances become directed membership strengths adapted to each observation. Those local relations are symmetrized into one weighted fuzzy graph. Attractive and repulsive updates optimize a layout. The artifact is then validated for neighborhood retention, stability, transform quality and downstream behavior. The reference implementation ships defaults for all of it, and they are choices rather than neutral settings: n_neighbors, “the size of local neighborhood (in terms of number of neighboring sample points) used for manifold approximation”, defaults to 15, min_dist defaults to 0.1, and the documentation adds that “in general values should be in the range 2 to 100”.

The fourth step is where that description and the shipped code separate. In 2021 Damrich and Hamprecht took the sampling-based optimiser UMAP actually runs and worked out what it minimises: “We derive UMAP’s true loss function in closed form and find that it differs from the published one in a dataset size dependent way.” The paper gives the direction of the difference: “The weight of the loss function's repulsive term is drastically reduced.” The effective target, they find, encodes little beyond the shared k-nearest-neighbour graph. A different group, in Tübingen, arrived at the same conclusion from the other side in 2022: “We find that UMAP embeddings correspond to t-SNE with increased attraction; mathematical analysis shows that this is because the negative sampling optimization strategy employed by UMAP strongly lowers the effective repulsion.”

The objective in the paper and the objective the process descends are therefore not the same object, and the gap depends on the size of the dataset. A reader who reasons about a layout from the published loss is reasoning about a function the code does not minimise.

The workflow changes slightly with the intended use. State the use — exploration, downstream transformation, retrieval, clustering, or label-guided visualization. Define the source metric and document scaling, embeddings, approximate-neighbor settings, and duplicate handling. Sweep neighborhood size, min_dist, dimension, initialization, and seed within plausible ranges. Test transform quality, neighbor retention, downstream metrics, and outlier placement on unseen data. Store the fitted reducer and monitor for drift, unsupported inputs, and coordinate incompatibility. It always preserves the training boundary.

The sweep step and the versioning step run into the same wall. Fixing a seed is not by itself reproducibility. The umap-learn documentation states it under “UMAP Reproducibility”: “Unfortunately this means that the randomness in UMAP outputs for the multi-threaded case depends not only on the random seed input, but also on race conditions between threads during optimization, over which no control can be had. This means that multi-threaded UMAP results cannot be explicitly reproduced.” Setting random_state restores exact reproducibility, at the cost of turning off the multi-threading. The uwot R package documents the same trade for its own stochastic gradient descent. It is the engine behind Seurat's RunUMAP, and James Melville maintains it independently of umap-learn: “Number of threads to use during stochastic gradient descent. If set to > 1, then be aware that if batch = FALSE, results will not be reproducible, even if set.seed is called with a fixed seed before running.”

Two independently authored implementations, the same limitation. So the seed setting is a throughput decision as well as a reproducibility one. A run that has to be reproduced exactly must record the threading configuration next to the seed.

A single library call can serve very different purposes, and each purpose requires different evidence. An exploratory map is a temporary layout for inspecting examples and nuisance structure. It prioritizes local interpretability, allows several parameter sweeps, and can be refit for each investigation. It should not define permanent IDs. A feature transformation is a fitted reducer supplying coordinates to a downstream model or index. It requires held-out transform evaluation, and versioned preprocessing and model state — including the seed and threading settings. It has to be monitored for out-of-support inputs, and it has to beat simpler reducers on the task. Supervised or target-guided UMAP lets labels influence which relationships the embedding preserves. It can increase class separation. It can also leak label assumptions into the visualization, so it requires target-aware validation. It should never be described as purely unsupervised discovery.

UMAP can provide informative visual neighborhoods, compact nonlinear features, or an interface for inspecting high-dimensional representations. Those benefits come from explicit assumptions about local connectivity and optimization. The size of what the contract gives up has been measured twice, by different groups. Chari and Pachter compared each cell's 30 nearest neighbours in ambient space with its neighbours in the two-dimensional layout, across six single-cell datasets: “The 2D t-SNE/UMAP embeddings (e.g., “PCA-50D→UMAP” in Fig 2A) displayed large Jaccard distances with respect to the neighbors in ambient dimension, with an average consistently above 0.7 (70%).” Measured against the intermediate PCA space the average was above 0.8. The group that reproduced the analysis on the same datasets reported kNN recall at k=10 that “was below 40% for all methods”.

Most of a point's nearest neighbours are therefore not its neighbours in the picture. And on the same datasets, in the same paper, kNN accuracy stayed above 90% for UMAP and t-SNE, against below 62% for two-dimensional PCA and the Picasso elephant. Both facts belong in the caption. A responsible analysis reports the source metric, graph parameters, stochastic variability, and validation target. It never treats the default two-dimensional layout as ground truth.