Quick Reference · t-SNE dimensionality reduction & embedding

openTSNE cheat sheet

Every run follows one pipeline: turn high-dimensional data into a neighbor graph (affinities P), pick a starting layout (init), then optimize it in two phases into a 2-D map. Learn the pipeline once and every parameter finds its place — and unlike other t-SNE tools, openTSNE can drop new points onto a finished map.

data & setup affinities (P) initialization optimize / fit embedding & new points pitfall ★ most common

Distilled & cross-checked across: opentsne.readthedocs.io (official docs + parameter guide) · Poličar et al., JSS 2024 · Kobak & Berens, Nature Comms 2019 · Wattenberg et al., distill.pub · scikit-learn · van der Maaten & Hinton, 2008

The pipeline & the calls that move data through it
Data X n × d, high-dim PCA → 50-D first Affinities P neighbor graph, n × n PerplexityBasedNN Optimize 1 · early exaggeration ×12 2 · normal phase gradient descent + momentum Embedding Y n × 2, a numpy array TSNEEmbedding Init Y₀ pca · spectral · random .affinity .optimize result pca init reads X embedding.transform(X_new) — drop new points onto the finished map INPUT THE TWO-PHASE FIT OUTPUT
01Install & Importonce per env
0260-Second Startthe daily loop
03TSNE() Parametersthe knobs
04Perplexitythe key dial
05Affinities · the P matrixbuild the graph
06Initializationthe starting layout
07Optimization · 2 phaseshow the fit runs
08Modular API · full controlthe canonical recipe
# build each stage yourself, then
# drive the two-phase optimization
aff  = affinity.PerplexityBasedNN(
           X, perplexity=30, n_jobs=-1)
init = initialization.pca(
           X, random_state=42)

emb = TSNEEmbedding(
    init, aff,
    negative_gradient_method="fft",
    n_jobs=-1,
)
# ★ phase 1 — early exaggeration
emb.optimize(250, exaggeration=12,
             momentum=0.5, inplace=True)
# ★ phase 2 — normal regime
emb.optimize(500, momentum=0.8,
             inplace=True)
09Add new points · transformopenTSNE's signature
10The embedding & I/Oit's just an array
11Large data & speedmillions of points
12Monitor & controlwatch it converge
★Recommended recipeKobak & Berens protocol
!Reading the picturedon't over-read t-SNE

How the pieces shape the map

Four ideas that decide what your embedding looks like — based on the openTSNE parameter guide and Kobak & Berens (2019).

the two-phase fit

Early exaggeration (×12) first packs neighbors into tight clusters; the normal phase then relaxes and spreads them apart.

phase 1 exaggeration 12 phase 2 · normal no / mild exaggeration 250 iter · momentum 0.5 500 iter · momentum 0.8 tight separated

perplexity's effect

Too low fragments a cluster into specks; too high melts everything into one blob. The sweet spot depends on how many points you have.

low fragmented balanced clean clusters high one blob

standard vs multiscale

Standard t-SNE nails local clusters but scatters them arbitrarily. Multiscale affinities keep related clusters near each other.

standard multiscale hues scattered hues grouped

map new points to a reference

Fit once on a reference set (grey), then transform unseen samples (colored) — each lands in the matching cluster. Unique to openTSNE.

new samples → transform() → matching cluster grey = reference embedding

Worth memorizing

perplexity ≈ #neighborsdefault 30; raise it (or use Multiscale) for global structure on big data
pca init is defaultdeterministic and keeps global layout — prefer over random
fit() → an arrayTSNEEmbedding subclasses np.ndarray; plot emb[:,0], emb[:,1]
transform() is uniqueopenTSNE alone maps new points into an existing embedding
two phasesearly exaggeration (12) packs clusters, normal phase spreads them
axes are meaninglessonly neighborhoods are trustworthy — not cluster size or spacing
learning_rate="auto"= N / exaggeration; almost never set it by hand
set random_statelayouts are otherwise different on every run
fft > bh at scaleFIt-SNE handles millions of points; Barnes-Hut suits small data
t-SNE ≠ PCA/UMAPit's for visualization, not general feature reduction