UMAP

Unsupervised & Dim. ReductionAdvanced~8 min

UMAP — Fast manifold embedding preserving local and some global structure.

UMAP is a faster cousin of t-SNE that preserves more of the global structure. It builds a graph of neighbors and lays it out in 2D, revealing clusters while keeping their arrangement more faithful.

UMAP

t-SNE (perplexity 18)

Cluster 0
Cluster 1
Cluster 2
k-NN graph edge

Same data, two embeddings running on the same clock. UMAP converges fast and tends to keep clusters that are close in the data close in the layout; t-SNE spends its early iterations under exaggeration and cares only about local neighbourhoods. (This is a simplified, in-spirit UMAP for teaching — not the full fuzzy-simplicial optimizer.)

UMAP controls

Data

Source data

Three well-separated blobs in six dimensions — both methods should find them.

Shape60 × 6 → 2

Model

n_neighbors12

min_dist0.40

Iterations (both panels)300

Playback

Step 0 / 38

Speed

Build the k-NN graph
Pull neighbours together
Cool down
↻

Step 0 of 38 — each point is wired to its 12 nearest neighbours in 6-D, and both layouts start from noise

Inspect

Hover a point in either panel: its 12 graph neighbours light up in both layouts at once, so you can see which one kept them together.

Break it

The idea in plain words

UMAP is a faster cousin of t-SNE. It builds a graph connecting each point to its nearest neighbors, then lays that graph out in 2-D with attractive forces along edges and repulsion elsewhere. Run both on the same data and the contrast is the lesson.

UMAP tends to preserve more global structure and converges faster, so clusters that are related in the data often stay closer in the layout. Very small n_neighbors fragments the manifold into disconnected islands.

Now, the math

UMAP optimizes a low-D layout to match a fuzzy neighbor graph, balancing two forces:

\underbrace{\text{attract}}_{\text{graph edges}} \;\;\leftrightarrow\;\; \underbrace{\text{repel}}_{\text{non-neighbors}}

$n\_neighbors$: graph connectivity — small values emphasize local, fine structure.
$\text{min\_dist}$: how tightly points may pack in the layout.

▸ Show the derivation

UMAP models neighborhoods as a fuzzy simplicial set and minimizes a cross-entropy between the high-D and low-D graphs. Fewer neighbors means a sparser graph, so weakly-connected regions drift apart into islands. (This build is a simplified force-directed stand-in for teaching, not the full optimizer.)

Trace it by hand

One edge of UMAP's fuzzy neighbor graph, for a pair A, B at distance 2. A's nearest neighbor is at distance 1 (rho A = 1), B's is at distance 1.5 (rho B = 1.5), and we fix sigma = 1 for both (real UMAP tunes sigma per point from n neighbors). Values rounded to 4 decimal places. The site's interactive uses a simplified force layout; these are the standard UMAP weight formulas.

Step 1 — the directed weight from A's point of view
$w_{B|A} = \exp\left(-\frac{d(A,B) - \rho_A}{\sigma_A}\right) = \exp\left(-\frac{2 - 1}{1}\right) = e^{-1} = 0.3679$
Distances are measured beyond rho, the gap to the nearest neighbor — so every point's local scale is recentered before weighting.
Step 2 — the same edge from B's point of view
$w_{A|B} = \exp\left(-\frac{2 - 1.5}{1}\right) = e^{-0.5} = 0.6065$
The two directed views disagree: the edge matters more to B than to A. UMAP must reconcile them.
Step 3 — fuzzy union: a probabilistic OR
$w_{AB} = w_{B|A} + w_{A|B} - w_{B|A}\, w_{A|B} = 0.3679 + 0.6065 - 0.2231 = 0.7513$
This is the probability that at least one of the two directed edges exists — an edge survives if either endpoint believes in it.
Step 4 — nearest neighbors always get weight 1
$w_{C|A} = \exp\left(-\frac{1 - 1}{1}\right) = e^{0} = 1$
Subtracting rho guarantees every point is fully connected to its nearest neighbor, so no point is stranded — the union then keeps that 1.

What just happened: Two directed opinions about the same pair, 0.3679 and 0.6065, fused into one edge of strength 0.7513 by the fuzzy OR. That single number then acts as the attraction strength when the layout is optimized — edges near 1 pull hard, weak edges barely pull, and non-edges only repel.

Now Break It

Try this: Very small n_neighbors fragments the manifold into disconnected islands.

Control: n_neighbors slider (set very low)

What happens: Fragmented manifold! Too few neighbors breaks the structure into disconnected islands.

Where umap is used

UMAP is a manifold learning method that embeds high-dimensional data into a low-dimensional map, and it has grown popular because it is fast, scales to large datasets, and tends to retain more of the global layout than t-SNE. Practitioners use it to visualize millions of single cells in biology, to explore embeddings from language and vision models, and to lay out large collections of documents or images so related items form navigable regions. Unlike purely visual methods, UMAP can also serve as a general dimensionality reduction step: it produces a reusable transformation, so you can project new, unseen points into an existing embedding and even reduce to more than two dimensions as a preprocessing stage before clustering or classification.

A widespread misconception is that UMAP faithfully preserves global distances; it captures local structure well and more global structure than t-SNE, but the spacing between distant clusters still should not be read as a precise measure of dissimilarity. Its two main knobs shape the result strongly: n_neighbors trades local detail against broader structure, and min_dist controls how tightly points pack, so tuning them changes the visual story considerably. Like t-SNE, UMAP is stochastic and can produce apparent clusters or gaps that are partly artifacts of the parameters, so conclusions should be checked at several settings. It is a powerful embedding tool, but the geometry of its output is qualitative, not a metric to be measured off the plot.

Frequently asked questions

How is UMAP different from t-SNE?

Both create nonlinear low-dimensional embeddings that preserve local neighborhoods, but UMAP is generally faster, scales better to large datasets, and tends to retain somewhat more global structure. UMAP also produces a reusable mapping that can transform new points, whereas standard t-SNE is purely for visualizing a fixed dataset. Neither should have its inter-cluster distances read literally.

What do n_neighbors and min_dist control?

n_neighbors sets how much of the surrounding data each point considers, with small values emphasizing fine local detail and large values capturing broader structure. min_dist controls how tightly points are allowed to cluster in the output, where small values produce dense clumps and larger values spread points out. Together they shape the balance of local versus global appearance.

Can UMAP preserve global structure?

Better than t-SNE, but only partially. UMAP retains more of the overall arrangement of clusters, yet the exact distances between far-apart groups are still not a reliable metric. Treat the global layout as suggestive rather than precise.

Can I project new data points into an existing UMAP embedding?

Yes. Unlike standard t-SNE, UMAP learns a transformation you can save and reapply, so new samples can be mapped into the same space without recomputing the whole embedding. This makes UMAP usable as a preprocessing step in a pipeline, not just a one-off visualization.

Is UMAP deterministic?

Not by default. UMAP uses randomized initialization and stochastic optimization, so separate runs can differ, though setting a fixed random seed makes results reproducible. As with any such method, checking stability across a few runs and parameter settings guards against over-reading incidental features of one plot.

← Back to all visualizations Continue on the Learning Path →

Written & reviewed by the ML Visualization team · Last updated August 6, 2026.