UMAP: a map, not a ruler
UMAP draws the neighbour relations of cells in a few dozen PC dimensions on a two-dimensional page. It is the most common figure in single-cell papers and the most often misread: it is a map that tells you who neighbours whom, not a ruler for measuring distance.
How a UMAP is drawn
UMAP works in two steps. The first resembles clustering: in PC space, each cell gets its nearest neighbours (n.neighbors = 30 by default in Seurat), forming a weighted neighbour graph. The second places all cells on a plane so that cells linked in the graph sit close and unlinked cells are pushed apart, optimising until the layout settles.
Two parameters matter most:
- n.neighbors: how many neighbours each cell considers. Smaller values stress local detail, larger ones the overall layout.
- min.dist (0.3 by default in Seurat): how close points may sit. Smaller values pack clusters tightly, larger ones spread points out.
The optimisation is random: with another seed, clusters move and rotate, but who neighbours whom largely stays.
obj <- RunUMAP(obj, dims = 1:10)From PCA to UMAP
The widget animates each cell from its place on the PC1/PC2 scatter to its place on the UMAP. Populations that overlap on PC1/PC2 separate on the UMAP, because UMAP uses all the selected PCs (the first 10 here), not just the first two. The price is distorted distances: to keep neighbours together, UMAP stretches and squeezes space.
Now switch to t-SNE: the same clusters, arranged differently. The relative placement of clusters is not a property of the data but a choice of the algorithm.
Common pitfalls
A UMAP can tell you which cells neighbour each other, whether a population is separate from the rest in this embedding, and where a gene’s expression is high.
A UMAP cannot tell you:
- Distances between clusters. Two clusters far apart on the plot are not necessarily more different than two that sit close.
- Cell numbers or heterogeneity. A cluster’s area and density do not match its cell count or its internal variation.
- Trajectories. A “bridge” between two clusters does not necessarily mean a differentiation process (chapter 12).
- Clusters or statistics. Clusters are computed on the graph in PC space, so a cluster that looks split in two on the UMAP, or interleaved with a neighbour, does not mean clustering failed; and do not compute distances or tests on UMAP coordinates.
Separation on a UMAP is not statistical significance. When publishing, report the number of PCs, n.neighbors, min.dist and the random seed.