Quick Reference · uniform manifold approximation & projection

umap-learn cheat sheet

UMAP builds a fuzzy graph of your data's nearest neighbors, then optimizes a low-dimensional layout that keeps that graph's shape. Two dials do most of the work: n_neighbors (how local the view is) and min_dist (how tightly points pack). It follows the scikit-learn API — so it drops into pipelines, and can even transform new points onto a trained map.

data & setup graph · n_neighbors, metric layout · min_dist, spread fit / optimize embedding & new data pitfall ★ most common

Distilled & cross-checked across: umap-learn.readthedocs.io (docs · API · parameter guide) · McInnes, Healy & Melville, 2018 (arXiv:1802.03426) · github.com/lmcinnes/umap · Coenen & Pearce — Understanding UMAP (Google PAIR) · Narayan et al., 2021 (densMAP) · scikit-learn

The two steps & the two dials that shape them

01Install & Importonce per env

pip install umap-learn★
Not pip install umap — that's a different package.
conda install -c conda-forge umap-learn
Conda-forge build.
import umap★
Then use umap.UMAP(...).
import umap.plot
Plot helpers (needs extra deps).
pip install umap-learn[plot]
Pulls datashader, bokeh, holoviews…

0260-Second Startthe daily loop

reducer = umap.UMAP()★
All sensible defaults.
emb = reducer.fit_transform(X)★
Fit + return the (n, 2) embedding.
emb = umap.UMAP(random_state=42).fit_transform(X)★
Reproducible layout.
reducer.embedding_
Same array, stored on the model.
reducer.transform(X_new)★
Embed new points onto the trained map.
plt.scatter(emb[:, 0], emb[:, 1], c=y, s=5)★
It's a plain array — plot it directly.

03The 4 core parameters80% of tuning

n_neighbors=15★
Local ↔ global balance of the graph.
min_dist=0.1★
How tightly points may pack together.
n_components=2
Output dims — 2/3 to view, more for ML.
metric="euclidean"★
Distance in the input space.
random_state=42★
Reproducible (but single-threaded — slower).

04n_neighbors · local ↔ globalthe graph dial

n_neighbors=15★
Default; a good all-round balance.
n_neighbors=2..5
Very local — fine detail, may fragment.
n_neighbors=50..200
Big-picture global structure, less detail.
# how large a neighborhood UMAP looks at
Usual range 5–50; sensible default 10–15.

05min_dist · packingthe layout dial

min_dist=0.1★
Default; good for general visualization.
min_dist=0.0
Tight clumps — best before clustering.
min_dist=0.5..0.99
Even, spread-out points for a clean view.
# min gap between points in the map
Range 0.0–0.99; keep it < spread.

06Metricsdistance in input space

metric="euclidean"★
Default; general numeric data.
metric="cosine"★
Text / embeddings / word vectors.
metric="correlation"
Shape over magnitude (e.g. genomics).
metric="manhattan", "chebyshev"
Other numeric metrics.
metric="hamming", "jaccard"
Binary / set-valued features.
metric="precomputed"
Pass your own distance matrix as X.
metric=my_numba_fn
Custom — a @numba.njit function.

07Embedding shapedims & init

n_components=2★
2 or 3 to visualize.
n_components=10..50
Scales in dim — feed downstream ML.
init="spectral"
Default; global-structure-aware start.
init="pca"
PCA start (deterministic).
init="random"
Random start (faster, less stable).
spread=1.0
Scale of the map; pairs with min_dist.

08Fit, transform, reusescikit-learn API

reducer.fit(X)★
Train & keep the model.
reducer.fit_transform(X)★
Fit + return the embedding array.
reducer.transform(X_new)★
Map unseen data — great in Pipelines.
reducer.inverse_transform(Y)
Reconstruct a high-dim sample from a point.
pickle.dump(reducer, f)
Persist the fitted model; reload to reuse.

09Supervised & semi-superviseduse your labels

reducer.fit_transform(X, y=labels)★
Labels guide the layout — cleaner classes.
# y = -1 for unlabeled rows
Semi-supervised on partial labels.
target_weight=0.5
0 = ignore labels · 1 = labels dominate.
reducer.fit(X_tr, y_tr).transform(X_te)
Metric learning: project unlabeled test data.

10Clustering with UMAPreduce, then cluster

min_dist=0.0★
Let clusters pack tightly.
n_components=5..10
Cluster in a few dims — not the 2-D view.
n_neighbors=15..30
Enough context to keep clusters honest.
HDBSCAN().fit(reducer.embedding_)★
Cluster the reduced representation.
densmap=True
Preserve local density (densMAP).

11Speed & scalebig & sparse data

n_jobs=-1★
All cores (default) — unless random_state set.
low_memory=True
Default; trims kNN memory use.
# first fit = numba JIT warmup
Slow once, then fast; scales to millions.
force_approximation_algorithm=True
Approx kNN even on small data.
precomputed_knn=(idx, dists, idx2)
Reuse a kNN you already computed.

12Variantsbeyond plain UMAP

umap.UMAP(densmap=True, dens_lambda=2.0)
densMAP — keeps relative densities.
from umap.parametric_umap import ParametricUMAP
NN-learned embedder …
ParametricUMAP().fit_transform(X)
… fast transform of new data; save/load.
umap.AlignedUMAP(n_neighbors=[...])
Aligned maps across datasets / params.

13Plotting · umap.plotbuilt-in helpers

umap.plot.points(reducer, labels=y)★
Fast scatter, colored by label.
umap.plot.connectivity(reducer, edge_bundling="hammer")
Show the underlying graph structure.
umap.plot.diagnostic(reducer, diagnostic_type="pca")
Sanity-check embedding quality.
umap.plot.interactive(reducer, labels=y)
Hover-able Bokeh plot.

★Recommended recipesensible starting point

StandardScaler().fit_transform(X)
Scale features before UMAP.
n_neighbors=15
Then sweep 5 → 50 to taste.
min_dist=0.1
0.1 to view · 0.0 to cluster.
metric="cosine"
For text & learned embeddings.
random_state=42
Reproducible (accept the speed hit).
n_components=2 → 10+
2 to look; higher to feed a model.

!Reading the picturedon't over-read UMAP

cluster sizes mean littlemyth
UMAP expands sparse, shrinks dense regions.
gaps aren't exact distancescare
Global layout beats t-SNE, but isn't literal.
random_state ⇒ single-threadcare
Reproducible but noticeably slower.
low n_neighbors ⇒ false shredscare
And high min_dist can merge real clusters.
don't cluster the 2-D viewcare
Reduce to more dims + min_dist=0 first.

How the pieces shape the map

Four ideas that decide what your embedding looks like — based on the UMAP parameter guide and Coenen & Pearce, “Understanding UMAP”.

the two steps

First build a fuzzy nearest-neighbor graph in high-D (set by n_neighbors); then optimize a low-D layout that keeps that graph's shape (set by min_dist).

n_neighbors: local ↔ global

Low values glue together small chains and miss the big picture; high values capture overall structure but blur fine detail.

min_dist: tight ↔ spread

Small min_dist lets clusters clump densely — better for clustering. Large values disperse points evenly — better for a clean overview.

add new data: transform()

Fit once on a training set (grey), then transform unseen samples (colored) — each lands in the matching region. UMAP fits straight into sklearn Pipelines.

Worth memorizing

n_neighbors = local↔globaldefault 15; raise for global structure, lower for fine detail

min_dist = packing0.1 to view, 0.0 to cluster; keep it < spread

fit_transform → arraythe same result also lives on reducer.embedding_

transform() = sklearnembed new points; drop UMAP straight into Pipelines

scales in dimensionunlike t-SNE, set n_components high to feed downstream ML

global structureUMAP keeps the big picture better than t-SNE — but sizes still aren't literal

random_state trade-offreproducible, but forces single-threaded — slower

cosine for textnon-metric distances (cosine, correlation) are first-class

cluster in >2-Dreduce to ~10 dims + min_dist=0, then HDBSCAN — never cluster the 2-D view

numba warmupthe first fit compiles; later runs are fast

umap-learn cheat sheet · synthesized from the official documentation (umap-learn.readthedocs.io — basic usage, parameter guide & API), McInnes, Healy & Melville, “UMAP: Uniform Manifold Approximation and Projection” (arXiv:1802.03426, 2018), the lmcinnes/umap README, Coenen & Pearce’s “Understanding UMAP” (Google PAIR), Narayan et al. (densMAP, 2021), and scikit-learn.
API shown for umap-learn ≈ 0.5.x · defaults: n_neighbors=15, min_dist=0.1, n_components=2, metric="euclidean", init="spectral", random_state=None.