How UMAP Works, and How to Read One Without Fooling Yourself
UMAP (Uniform Manifold Approximation and Projection) reduces high-dimensional data to two or three dimensions in two stages. First it builds a weighted graph connecting each point to its k nearest neighbors, where edge weights come from a distance kernel rescaled per point so that everyone has a comparable sense of “near”. Then it initializes a low-dimensional layout and moves the points with stochastic gradient descent until the low-dimensional graph matches the high-dimensional one under a cross-entropy loss. Everything you see in a UMAP plot is the output of that force simulation. The topological framing in the original paper justifies the loss function, but the code is a neighbor graph plus a layout optimizer.
The algorithm in four steps
The first step is the neighbor search. UMAP calls pynndescent to get approximate k-nearest neighbors under whatever metric you chose, with n_neighbors defaulting to 15. Approximate means the graph is not guaranteed exact, which is one reason two runs can differ slightly even with the same data.
The second step is local rescaling, and it is the part that makes UMAP behave the way it does. For each point i, UMAP records ρ_i, the distance to its nearest neighbor. It then solves for a bandwidth σ_i by binary search so that the sum of exp(−(d_ij − ρ_i)/σ_i) over the k neighbors equals log2(k). Subtracting ρ_i guarantees every point is connected to at least one neighbor with weight 1. Dividing by σ_i means a point in a sparse region gets a wide kernel and a point in a dense region gets a narrow one. This is why UMAP flattens density differences: it deliberately normalizes them away.
The third step is symmetrization. The weight from i to j is generally not the weight from j to i, so UMAP takes the fuzzy union w = a + b − ab, where a and b are the two directed weights. The result is a single undirected weighted graph, stored as a sparse matrix.
The fourth step is layout. Low-dimensional similarity uses the kernel 1/(1 + a·d^(2b)), with a and b fit by least squares to a piecewise curve defined by min_dist and spread. At the defaults of min_dist=0.1 and spread=1.0 this gives roughly a ≈ 1.577 and b ≈ 0.895. UMAP initializes with a spectral embedding of the graph Laplacian, then runs SGD for n_epochs (200 for large datasets, 500 for small ones). Each epoch samples edges in proportion to their weight and applies an attractive force, then applies repulsive forces to negative_sample_rate=5 randomly chosen points per edge. Negative sampling is what keeps the cost linear rather than quadratic in the number of points.
The parameters that change the answer
n_neighbors sets the scale of structure UMAP preserves. At 5 you see fine local neighborhoods and many fragments. At 50 to 200 you see global arrangement and fewer, broader groups. Running the same data at 10, 30, and 100 and comparing is the cheapest sanity check available. We do it every time.
min_dist controls only how tightly points pack in the output. It has no effect on the graph. Use 0.0 to 0.1 if you intend to run a density clustering algorithm afterward, and 0.3 to 0.5 if you want a plot that is readable.
metric matters more than most people assume. For expression data on a log scale, cosine or correlation is often the better choice than euclidean, because it ignores overall magnitude. For binary or presence-absence features, use jaccard or hamming.
random_state fixes the seed but forces single-threaded layout, which can cost you an order of magnitude in wall time on a large matrix. We leave it unset while exploring and set it for any figure we intend to publish or revisit. Note also that embeddings shift across versions of umap-learn, pynndescent and numba, so pin them if reproducibility matters.
A concrete recipe for expression data
Do not run UMAP on raw counts. The standard pipeline is variance stabilization, then feature selection. After that comes a linear reduction, followed by UMAP on the linear components.
import scanpy as sc
sc.pp.normalize_total(adata, target_sum=1e6)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
adata = adata[:, adata.var.highly_variable]
sc.pp.scale(adata, max_value=10)
sc.tl.pca(adata, n_comps=50, svd_solver="arpack")
sc.pp.neighbors(adata, n_neighbors=15, n_pcs=30, metric="cosine")
sc.tl.umap(adata, min_dist=0.1)
The PCA step is not optional in practice. Computing neighbors in 2,000-dimensional space is slow and noisy, and 30 to 50 principal components usually carry the reproducible signal. Choose the number of components from the elbow of the variance-explained curve, then check that your conclusions survive moving it by ten.
Sample size is the constraint people most often ignore. UMAP needs many more points than n_neighbors to have anything to estimate. With 20 bulk RNA-seq samples, a UMAP is decoration. Use PCA, or a correlation heatmap with hierarchical clustering, and report the actual distances. UMAP earns its keep on bulk data when you have hundreds of samples, where it has been shown to separate heterogeneous subgroups that PCA leaves overlapping 1.
What you can and cannot read off the plot
Distance between two adjacent clusters is weakly informative. Distance between two clusters on opposite sides of the plot is close to meaningless, because the spectral initialization and the repulsive forces jointly determine global placement. Cluster size in area is meaningless, since min_dist sets packing density directly. Relative density is also distorted by the per-point σ_i rescaling. If density is what you care about, use densmap=True, which adds a term to the loss that preserves local radii.
The failure mode that costs people the most is finding clusters in noise. UMAP will produce separated blobs from isotropic Gaussian noise if n_neighbors is small. The defense is to cluster in the PC space rather than the UMAP coordinates, then color the UMAP by those labels. If the clustering and the embedding agree, you have some evidence. If groups that are separate in the embedding are not separate upstream, the embedding made them.
Density-based clustering on the embedding is defensible when the pipeline is built for it. The GAUDI method integrates multi-omics blocks by running UMAP per block, concatenating the embeddings and applying HDBSCAN to the joint space. Feature attribution comes afterward to explain what drives each cluster 2. That last part matters: an embedding coordinate has no units and no gene attached to it. Recovering interpretation requires an explicit attribution step, such as SHAP values computed against the embedding 3.
For data that combines modalities measured on the same samples, a single concatenated UMAP lets whichever assay has more features dominate. Joint formulations of t-SNE and UMAP weight each modality’s neighbor graph separately before optimizing one shared layout 4. That is the better structure when you are combining transcript counts with proteomics and biomarker panels.
One naming note to save you a search. In genomics literature, “Umap” also refers to an unrelated tool that quantifies single-read and multi-read mappability across the genome 5. If a paper mentions Umap alongside Bismap and bigWig tracks, it is not talking about dimensionality reduction.
Validating an embedding
Three checks are enough for most work. Run the embedding at several n_neighbors values and keep only the structure that persists. Subsample 80 percent of your data ten times, cluster each run, and compute the adjusted Rand index between runs: stable structure gives values above roughly 0.8. Compute sklearn.manifold.trustworthiness on the embedding to measure how many high-dimensional neighbors survived the projection.
Finally, color by every technical variable you have. That includes sequencing batch, library prep date, RNA integrity number and collection time. If the dominant split tracks a batch, you have found your batch effect and nothing else. Correct it upstream with something like ComBat or Harmony, then recompute the neighbor graph.
A cluster in your own longitudinal data is a statistical grouping of samples. It is not a diagnosis and does not indicate what to do. Take anything that looks clinically meaningful to a physician who can order confirmatory testing.
Questions people also ask
How do I interpret UMAP results? Read local neighborhoods, which are reliable, and treat global geometry as a rough sketch. Which points sit together means something. How far apart two distant clusters are, and how large each blob looks, do not.
What are the weaknesses of UMAP? It can manufacture clusters from noise, and it distorts density and global distances. Its output depends on the random seed and on library versions, and its axes carry no interpretable units. It also does not give you a loading vector, so you cannot read which features drive an axis without a separate attribution step.
How is UMAP different from PCA? PCA is a deterministic linear projection with orthogonal axes, explained-variance figures, and per-feature loadings you can inspect. UMAP is a stochastic nonlinear method that optimizes neighbor preservation and gives none of those. Use PCA for quality control and interpretable variance decomposition, and UMAP for visualizing nonlinear structure once the data are clean. Topological and graph-based methods built on UMAP embeddings have been applied to cancer subtyping where linear projections underperform 6.
Is UMAP or t-SNE faster? UMAP is usually faster at scale, mostly because approximate nearest neighbors plus negative sampling avoids the quadratic gradient of naive t-SNE. Modern FIt-SNE closes much of the gap. UMAP also has the practical advantage of a transform method that embeds new points into an existing layout.
Footnotes
-
Yang Yang, Hongjian Sun, Yu Zhang, et al. Dimensionality reduction by UMAP reinforces sample heterogeneity analysis in bulk transcriptomic data. Cell Reports, 2021. https://doi.org/10.1016/j.celrep.2021.109442 ↩
-
Pol Castellano-Escuder, Derek K. Zachman, Kevin Han, et al. GAUDI: interpretable multi-omics integration with UMAP embeddings and density-based clustering. Nature Communications, 2025. https://doi.org/10.1038/s41467-025-60822-1 ↩
-
Zhonglin Qu, Yezihalem Tegegne, Simeon J. Simoff, et al. Enhancing Understandability of Omics Data with SHAP, Embedding Projections and Interactive Visualisations. Communications in Computer and Information Science, 2022. https://doi.org/10.1007/978-981-19-8746-5_5 ↩
-
Van Hoan Do, Stefan Canzar. A generalization of t-SNE and UMAP to single-cell multimodal omics. Genome Biology, 2021. https://doi.org/10.1186/s13059-021-02356-5 ↩
-
Mehran Karimzadeh, Carl Ernst, Anshul Kundaje, et al. Umap and Bismap: quantifying genome and methylome mappability. Nucleic Acids Research, 2018. https://doi.org/10.1093/nar/gky677 ↩
-
Arif Ahmad Rather, Manzoor Ahmad Chachoo. UMAP guided topological analysis of transcriptomic data for cancer subtyping. International Journal of Information Technology, 2022. https://doi.org/10.1007/s41870-022-01048-y ↩
Pothos builds longitudinal molecular profiles of individuals: whole-genome sequencing, single-cell RNA sequencing, and plasma proteomics, delivered as a detailed report, every data file, and stored cells. Build your profile.