UMAP, short for uniform manifold approximation and projection, is a nonlinear dimensionality reduction algorithm that embeds high-dimensional data in a low-dimensional space, usually two or three dimensions, while preserving the local neighborhood structure of the points. In machine learning it is used mainly for visualizing clusters, exploring embeddings and producing compact features for downstream models.
UMAP builds a weighted nearest-neighbor graph of the data, then optimizes a low-dimensional layout whose graph matches the original as closely as possible. Compared with t-SNE, it is usually faster on large datasets, keeps somewhat more global structure, and can transform new points after fitting, which makes it practical in production pipelines.
How UMAP builds and optimizes the neighbor graph
UMAP works in two stages: it first constructs a fuzzy topological representation of the data in the original space, and then searches for a low-dimensional embedding with a similar representation. The theory draws on Riemannian geometry and algebraic topology, but the practical mechanism is a graph layout problem.
In the first stage, the algorithm finds the k nearest neighbors of every point, typically with an approximate method such as nearest-neighbor descent. Each point receives a local distance scale so that its closest neighbor is always connected with weight one, which assumes the data are uniformly distributed on a manifold and lets dense and sparse regions be treated alike. Directed edge weights are then symmetrized with a fuzzy set union into a single undirected graph.
In the second stage, UMAP initializes the embedding, by default with a spectral layout of the graph, and refines it by stochastic gradient descent. The objective is a cross-entropy between fuzzy sets: attractive forces pull connected points together and repulsive forces, estimated with negative sampling, push unconnected points apart. Negative sampling keeps each training step cheap, so runtime scales roughly with the number of edges rather than with all point pairs.
The following table summarizes the pipeline and what each step contributes to the final map.
| Step | What happens | Effect on the result |
|---|---|---|
| Neighbor search | Approximate k-nearest-neighbor graph is built | Defines which points count as local |
| Local scaling | Each point gets its own distance normalization | Balances dense and sparse regions |
| Fuzzy union | Directed weights become one symmetric graph | Produces a single topological summary |
| Spectral initialization | Graph Laplacian eigenvectors seed the layout | Improves stability and global arrangement |
| Layout optimization | Gradient descent with negative sampling | Pulls neighbors together, separates others |
Key UMAP hyperparameters and their effects
UMAP behavior is controlled by a small set of hyperparameters, and the two most influential are n_neighbors and min_dist. Choosing them deliberately matters more than any other setting, because they decide whether the map emphasizes fine local detail or broad global shape.
The table below lists the common parameters in the reference implementation, their typical ranges and the visual or numerical consequence of changing them.
| Parameter | Typical range | What it controls |
|---|---|---|
n_neighbors | 5 to 200, default 15 | Size of the local neighborhood; larger values favor global structure |
min_dist | 0.0 to 0.99, default 0.1 | How tightly points may pack; low values give compact clusters |
n_components | 2 to about 100 | Output dimensionality; 2 or 3 for plots, more for features |
metric | Euclidean, cosine, Manhattan and others | Distance used for the neighbor graph |
n_epochs | 200 to 500 | Optimization length; more epochs refine the layout |
random_state | Any fixed integer | Reproducibility at the cost of parallel speed |
The choice of metric deserves special attention. For text and sentence embeddings, cosine distance usually reflects similarity better than Euclidean distance, while for standardized tabular data Euclidean distance is a reasonable default once feature scaling has been applied.
UMAP compared with t-SNE and PCA
UMAP sits between linear projection and probabilistic neighbor embedding among the dimensionality reduction methods. Principal component analysis finds orthogonal directions of maximum variance and is fully linear, whereas t-SNE and UMAP both model neighborhoods and can unfold curved manifolds that a linear method collapses.
The comparison below shows where each method is strongest and where it tends to mislead.
| Property | UMAP | t-SNE | PCA |
|---|---|---|---|
| Type of mapping | Nonlinear, graph based | Nonlinear, probability based | Linear projection |
| Speed on 1 million points | Minutes on a workstation | Slow without special variants | Seconds |
| Global structure | Partly preserved | Weakly preserved | Preserved for linear trends |
| New data | Native transform method | No direct transform | Exact projection |
| Determinism | Stochastic unless seeded | Stochastic | Deterministic |
| Interpretable axes | No | No | Yes, as loadings |
A frequent and effective practice is to run PCA first, reducing the data to around 50 components, and then apply UMAP. This step removes noise dimensions, speeds up the neighbor search and often produces cleaner cluster separation.
Practical uses of UMAP in machine learning workflows
UMAP is most often used for exploratory visualization, but its ability to produce embeddings of any moderate dimension also makes it a feature extraction tool. Typical applications include inspecting embeddings from language or vision models, finding subpopulations in single-cell genomics and spotting outliers before training a classifier.
- Cluster exploration: projecting data to two dimensions to see whether natural groups exist before running k-means clustering or DBSCAN.
- Preprocessing for density clustering: reducing to 5 to 20 dimensions, then clustering with a density method, a pattern that often outperforms clustering in the raw space.
- Supervised and semi-supervised UMAP: passing labels to the fit so that the embedding separates known classes while still respecting the data geometry.
- Drift monitoring: fitting on reference data and transforming new batches to see whether incoming points fall in unfamiliar regions.
The decision table below helps match settings to the analytical goal.
| Goal | Recommended setting | Reason |
|---|---|---|
| Visualize fine subclusters | Low n_neighbors (5 to 15), min_dist near 0.0 | Emphasizes local detail and tight groups |
| Show overall data shape | High n_neighbors (50 to 200) | Larger neighborhoods capture global relations |
| Input for clustering | min_dist 0.0, 5 to 20 components | Dense, well-separated regions help density methods |
| Readable presentation plot | min_dist 0.3 to 0.5 | Spreads points so overlapping groups stay visible |
Limitations and common misreadings of UMAP plots
UMAP produces persuasive pictures, and the main risk is overinterpreting the layout. The algorithm optimizes neighborhood agreement, not faithful distances, so several visual features of a plot carry little or no meaning.
- Distances between clusters are not reliable measures of dissimilarity; two distant islands may be closer in the original space than they appear.
- Cluster sizes and densities are distorted, because local scaling equalizes density by design.
- Apparent clusters can be artifacts of a small n_neighbors value on data that is actually continuous.
- Results vary between runs unless the random seed is fixed, and fixing it disables some parallelism.
- The axes have no units and no interpretation, unlike principal components.
Sound practice is to check stability across seeds and parameter values, confirm clusters with a separate method, and use UMAP plots as hypothesis generators rather than as evidence. The curse of dimensionality also applies: with very high-dimensional, noisy features, nearest-neighbor distances become less meaningful, so prior reduction or feature selection improves results.
A non-technical view
Imagine a huge spreadsheet where every row is a customer described by hundreds of numbers. Nobody can picture hundreds of dimensions. UMAP draws a flat map of those rows in which similar rows end up close together, much like a seating plan that puts friends at the same table.
The map is good at showing who belongs with whom. It is less trustworthy about how far apart the tables are or how big each one looks. So UMAP is best treated as a guide for exploring data, not as a precise measurement.
A concrete example
A support team at a software company collects 200,000 customer tickets and turns each one into a 768-dimensional text embedding. A data scientist reduces the embeddings to 50 dimensions with PCA, then runs UMAP with cosine distance, n_neighbors of 30 and min_dist of 0.0, producing a 10-dimensional embedding for clustering and a separate 2-dimensional one for plotting.
A density-based clustering step on the 10-dimensional output finds about 40 groups. The 2-dimensional plot reveals one large, previously unnoticed group of tickets about a failed login flow after a recent release. After checking samples by hand and confirming the group with several random seeds, the team routes those tickets to a dedicated queue and the engineering team fixes the defect, reducing related tickets sharply over the following weeks.