UMAP

Also known as: Uniform manifold approximation and projection

On this page 7

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.

StepWhat happensEffect on the result
Neighbor searchApproximate k-nearest-neighbor graph is builtDefines which points count as local
Local scalingEach point gets its own distance normalizationBalances dense and sparse regions
Fuzzy unionDirected weights become one symmetric graphProduces a single topological summary
Spectral initializationGraph Laplacian eigenvectors seed the layoutImproves stability and global arrangement
Layout optimizationGradient descent with negative samplingPulls neighbors together, separates others
Main steps of the UMAP algorithm

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.

ParameterTypical rangeWhat it controls
n_neighbors5 to 200, default 15Size of the local neighborhood; larger values favor global structure
min_dist0.0 to 0.99, default 0.1How tightly points may pack; low values give compact clusters
n_components2 to about 100Output dimensionality; 2 or 3 for plots, more for features
metricEuclidean, cosine, Manhattan and othersDistance used for the neighbor graph
n_epochs200 to 500Optimization length; more epochs refine the layout
random_stateAny fixed integerReproducibility at the cost of parallel speed
Common UMAP hyperparameters

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.

PropertyUMAPt-SNEPCA
Type of mappingNonlinear, graph basedNonlinear, probability basedLinear projection
Speed on 1 million pointsMinutes on a workstationSlow without special variantsSeconds
Global structurePartly preservedWeakly preservedPreserved for linear trends
New dataNative transform methodNo direct transformExact projection
DeterminismStochastic unless seededStochasticDeterministic
Interpretable axesNoNoYes, as loadings
UMAP, t-SNE and PCA side by side

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.

GoalRecommended settingReason
Visualize fine subclustersLow n_neighbors (5 to 15), min_dist near 0.0Emphasizes local detail and tight groups
Show overall data shapeHigh n_neighbors (50 to 200)Larger neighborhoods capture global relations
Input for clusteringmin_dist 0.0, 5 to 20 componentsDense, well-separated regions help density methods
Readable presentation plotmin_dist 0.3 to 0.5Spreads points so overlapping groups stay visible
Choosing UMAP settings by goal

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.