Intuition The One Core Idea
UMAP takes data that lives in a huge number of dimensions (say a 784-number description of a handwritten digit) and squashes it down to a 2-D picture you can actually look at — while trying to keep neighbours as neighbours and strangers as strangers . Everything else in the parent note is just the careful machinery for measuring "who is a neighbour" in high-D and then re-drawing those friendships in 2-D. (You will meet the full input/output symbols X and Y properly in Section 0 — don't worry if they look mysterious right now.)
Before you can read a single formula in the parent note, you need to be fluent in a small pile of symbols. This page unpacks every one of them, in an order where each rests on the previous. We build from absolutely nothing — no prior linear algebra, no calculus jargon assumed.
The very first symbol the parent throws at you is X ∈ R n × d . Let us earn every piece of it.
Definition Bold-face convention: matrices vs vectors
Two typographic rules used everywhere in the parent note:
Bold uppercase (like X , Y ) = a whole table of numbers , called a matrix — many rows, many columns.
Plain lowercase with a subscript (like x i , y i ) = a single row of that table — one data point, itself a short list of numbers, called a vector .
So X is the entire dataset stacked up , and x i is one point picked out of it (the i -th row).
Definition A single data point as a list of numbers
A dimension is just one measurement slot. If I describe a person by (height, weight), that is 2 numbers , so this person is a point in 2-dimensional space — a dot on a flat sheet of paper.
Add "age" and now each person is (height, weight, age) — 3 numbers , a dot floating in a room.
A handwritten digit image that is 28 pixels by 28 pixels has 28 × 28 = 784 brightness numbers. So each image is a single dot living in a 784-dimensional space . We cannot picture that room — but the arithmetic works exactly the same as with 2 or 3.
Figure s01 — one object, more slots. Look left to right: the same thing (a point, drawn as an orange dot) is a dot on a line when it has 1 number, a dot on a sheet when it has 2, a dot in a box when it has 3. The teal labels count the numbers. The lesson to carry away: adding dimensions just means adding measurement slots — the pattern keeps going even after we run out of ways to draw it (like the 784-D digit).
X , n , d , and R n × d
X = the data matrix — the whole input dataset written as one big table.
n = how many data points you have (e.g. 1000 digit images) — the number of rows of X .
d = how many numbers describe each point (e.g. 784) — the number of columns .
R is the symbol for "all ordinary numbers" (the R stands for Real numbers — anything on the number line: − 3 , 0 , 2.71 , ...).
R n × d therefore reads: "a table of real numbers with n rows and d columns." One row per data point, one column per measurement. Writing X ∈ R n × d says "X is such a table."
Definition The output matrix
Y and its rows y i
Y = the output matrix — the finished low-dimensional layout, again one table with n rows (still one row per original point) but now only d ′ columns, where d ′ is the small target dimension (usually 2 ). We write Y ∈ R n × d ′ .
The prime mark ′ in d ′ just means "the new, smaller dimension."
The i -th row of Y is the vector y i — the ( x , y ) position of point i on the final plot . This is the thing UMAP is solving for.
Intuition Why the topic needs this
UMAP's whole job is to turn X ∈ R n × d (a wide table you cannot see) into Y ∈ R n × d ′ with d ′ = 2 (a table you can plot). Same n points, fewer columns. Throughout, x i is a high-D data point (row of X ) and y i is its low-D position (row of Y ) — both are met properly above and reused below.
Every UMAP formula starts with d ij , the distance between point i and point j . We must define what "distance" means before using it.
i and j
The little i in x i is just a name tag / row number . x i and x j are two different high-D points — think "point number i " and "point number j ." Likewise y i and y j are two different low-D positions.
So d ij = "the distance between point i and point j ." Two subscripts because distance needs two points.
Definition Euclidean distance (the straight-line ruler)
In 2-D, the distance between two points ( p 1 , q 1 ) and ( p 2 , q 2 ) is the length of the straight line joining them — the Pythagoras rule:
d = ( p 1 − p 2 ) 2 + ( q 1 − q 2 ) 2
In d dimensions we just keep adding squared differences under the root. This same straight-line recipe is what the double-bar notation ∥ ⋅ ∥ 2 (defined next) stands for.
Figure s02 — distance is just Pythagoras. The two black dots are points i and j . The dashed teal segment is the horizontal gap (here 3), the dashed orange segment is the vertical gap (here 2), and the solid plum line is the actual distance between them. Notice the plum line is the hypotenuse of the right triangle formed by the two gaps — so its length is 3 2 + 2 2 . That is exactly what "Euclidean distance" computes; in higher dimensions we just have more gaps to square and add.
Definition Vector subtraction and the double-bar notation
∥ ⋅ ∥ 2
y i and y j are each a short list of d ′ numbers of the same length (both live in R d ′ ), so we can subtract them slot by slot : y i − y j is the list of coordinate-differences (in 2-D, the horizontal gap and the vertical gap of Figure s02). Subtraction only makes sense because both have the same shape — the dimensions must match.
The double vertical bars ∥ ⋅ ∥ 2 mean length of (also called the norm ): square every slot, add, take the root. So ∥ y i − y j ∥ 2 = "the straight-line length of the arrow between the two low-D points" (the plum hypotenuse in Figure s02, but in the low-D plot). The small subscript 2 names this the Pythagoras (squared-and-rooted) recipe — the "ℓ 2 " norm. So ∥ y i − y j ∥ 2 2 (with an outer power 2) is just distance-squared — which conveniently cancels the square root.
Intuition Why the topic needs distance — and what "metric" means
UMAP decides who is a neighbour by measuring distances. Small distance → likely a neighbour → strong bond. Large distance → strangers → weak bond. Everything downstream is a transformation of these d ij numbers.
The parent lists metric as a hyperparameter. A metric is simply which ruler you use to turn two points into a distance number. Swapping metrics just swaps the recipe that produces d ij — the rest of UMAP is untouched:
Euclidean (ℓ 2 ): d ij = ∑ m ( x im − x j m ) 2 — straight-line length (our default).
Manhattan (ℓ 1 ): d ij = ∑ m ∣ x im − x j m ∣ — add the gaps without squaring (city-block walking).
Cosine: d ij = 1 − ∥ x i ∥ ∥ x j ∥ x i ⋅ x j — measures the angle between the two arrows, ignoring their length (great for text/word counts).
Whichever you pick, UMAP feeds the resulting d ij into every later formula unchanged. Related: Nearest Neighbors Algorithms is the machinery that finds the closest points quickly.
Before the friendship formula, we must say which points count as neighbours of x i .
k (n_neighbors) and the neighbour set N ( i )
k is a number you choose — the UMAP hyperparameter called n_neighbors (typical values 5–50). It answers "how many closest points should each point pay attention to?"
N ( i ) = ==the set of the k nearest neighbours of point i == — the k points with the smallest distances d ij to x i . Crucially, i itself is not in N ( i ) (a point is not its own neighbour). So ∑ j ∈ N ( i ) means "add over exactly those k closest other points."
Common mistake Edge case:
k must be smaller than n
You cannot have more neighbours than there are other points. Formally N ( i ) needs k ≤ n − 1 , so you must choose k < n . On a tiny dataset (say n = 6 points) asking for n_neighbors=50 is meaningless — real libraries either error out or silently clamp k down to n − 1 . Rule to remember: more points than neighbours, always.
k ?
Instead of connecting every point to every other point (which is huge and mostly meaningless), UMAP only wires up each point to its k closest companions. Small k → each point sees only its tight local circle (fine local detail); large k → each point sees a wider crowd (more global context). This single knob is why the parent's Worked Example 1 changes the whole picture.
The parent's core high-D formula is
w ij = exp ( − σ i m a x ( 0 , d ij − ρ i ) ) , j ∈ N ( i ) .
Three new pieces to earn: exp , max ( 0 , ⋅ ) , and the parameters ρ i , σ i .
w ij — only neighbours get a weight
w ij is computed only for j ∈ N ( i ) (the k nearest neighbours of point i ). For every other j we simply set w ij = 0 — no edge at all. This is why later sums run over j ∈ N ( i ) : those are the only pairs with a non-zero weight. Picture point i sending out exactly k threads and nothing else.
exp — the exponential, and WHY it is used here
exp ( z ) means e z , where e ≈ 2.718 . All you need to feel is the shape of exp ( − something ) :
When the "something" is 0 , exp ( 0 ) = 1 (maximum).
As the "something" grows, the output slides smoothly down toward 0 , never going negative.
Why this tool and not, say, a straight line? We want a smooth rule where "distance 0 → weight 1 (best friends)" and "distance huge → weight ~0 (strangers)," with a gentle fade in between — never a hard cliff, never a negative weight. The decaying exponential is the simplest curve with exactly those properties.
Figure s03 — the friendship weight fades from 1 down to 0. The horizontal axis is distance d ij ; the vertical axis is the weight w ij . Follow either curve from left to right: it starts flat at weight 1 up to the dashed orange line at ρ i (the nearest-neighbour distance), then slides smoothly toward 0 — never crossing below zero. Compare the two curves: the plum one (small σ i ) drops steeply so only very close points keep any weight, while the teal one (large σ i ) fades gently so farther points still count. That contrast is what σ i controls.
max ( 0 , z ) — the "never go below zero" clamp
max ( 0 , z ) reads "pick the larger of 0 and z ." If z is positive it returns z ; if z is negative it returns 0 . Picture a floor: the value can rest on the floor 0 but cannot fall through it.
Here it protects the formula: if a neighbour is closer than the nearest-neighbour distance ρ i , then d ij − ρ i would be negative — the clamp turns that into 0 , so the weight becomes exp ( 0 ) = 1 (fully connected). No point is ever left isolated.
ρ i (rho) — distance to the closest neighbour
ρ i (the Greek letter "rho") = ==the distance from point i to its single nearest neighbour==. Subtracting it shifts the decay so it starts after the first friend. Picture sliding the whole decay curve rightwards so the closest point sits exactly at weight 1 (the flat part before the orange line in Figure s03).
σ i (sigma) — the local zoom level / bandwidth
σ i ("sigma") controls how fast the weight fades with distance for point i . Small σ i = steep drop (only the very nearest count); large σ i = gentle drop (farther points still matter). It is tuned per point so that dense and sparse regions are treated fairly — the parent's Worked Example 3 solves for it.
ρ i and σ i ?
In a crowded region everyone is close; in an empty region the "nearest" neighbour is already far. By giving each point its own ρ i (shift) and σ i (stretch), UMAP measures friendship in relative terms — "close for you " — so it does not mistake sparse-region points for outliers.
The parent sets ∑ j ∈ N ( i ) w ij = log 2 ( k ) . Two more notations — and recall from Section 2 that N ( i ) is the k -nearest-neighbour set and k is n_neighbors.
Definition The summation sign
∑
∑ j w ij is just shorthand for "==add up all the w ij == as j runs over the listed items." ∑ j ∈ N ( i ) means "j ranges over N ( i ) , the k nearest neighbours of point i ." So this is: add together all the friendship weights point i hands out to its k closest companions.
log 2 ( k ) — the logarithm base 2
log 2 ( k ) answers the question "2 to what power gives k ? " e.g. log 2 ( 8 ) = 3 because 2 3 = 8 . It grows slowly. Here (with k = n_neighbors, already named in Section 2) it is the target total friendship budget — a modest number so each point spreads a fixed, sensible amount of connection over its k neighbours.
Worked example Quick log sanity check
log 2 ( 15 ) ≈ 3.906 (since 2 3.906 ≈ 15 ). This is the number the parent's Worked Example 3 makes the weights sum to.
σ i always exists (the monotonicity argument)
Think of the total weight as a knob-reading that depends on σ i :
S ( σ i ) = ∑ j ∈ N ( i ) exp ( − σ i m a x ( 0 , d ij − ρ i ) ) .
Turn σ i up and every single term rises (each exponential fades more slowly), so S rises. Turn σ i down and every term falls, so S falls. Because S moves strictly one direction as σ i changes — it is monotonic — it can equal the target log 2 ( k ) at exactly one value of σ i . In the two limits:
As σ i → 0 + : only the nearest neighbour survives, so S → 1 (below the target).
As σ i → ∞ : every term → 1 , so S → k (above the target, since k > log 2 k ).
A strictly-increasing quantity that starts below the target and ends above it must cross the target once . That is the guarantee that makes the binary search in Worked Example 3 valid: it is squeezing in on that single crossing point. Picture the plum/teal curves of Figure s03 as one knob-turn: sliding σ i smoothly slides the whole sum up or down.
So far w ij is directed : it is "how strongly i reaches toward j ," and w ij need not equal w j i . We now define a single undirected edge weight, written with the superscript "sym" (for symmetric ):
Definition The symmetric edge weight
w ij sym
w ij sym = ==the one agreed, undirected bond strength between points i and j ==. The superscript "sym" is just a label meaning "symmetric," i.e. w ij sym = w j i sym . It is computed from the two directed weights by
w ij sym = w ij + w j i − w ij ⋅ w j i ,
and it replaces the directed w ij from here on. It is defined for any pair ( i , j ) where at least one of w ij , w j i is non-zero (i.e. i is a neighbour of j or vice versa); all other pairs stay 0 .
w ij and w j i can differ
w ij = "how strongly i reaches toward j "; w j i = "how strongly j reaches toward i ." Because ρ and σ are per-point, these two can genuinely disagree — friendship can feel one-sided (and j might not even be in N ( i ) while i is in N ( j ) ).
Intuition The formula is a probabilistic OR
If two numbers behave like probabilities in [ 0 , 1 ] , then "a OR b " = a + b − ab . Reading it: "there is a bond if either side wants one." Picture two overlapping soap bubbles — the union is both bubbles minus the double-counted overlap. This makes the graph undirected : one agreed strength per pair. The word fuzzy here just means "membership is a number between 0 and 1, not a hard yes/no."
The parent's low-D weight:
v ij = 1 + a ∥ y i − y j ∥ 2 2 b 1 .
y i , and a , b
y i = the low-D position of point i (its ( x , y ) dot on the final plot — the row of Y from Section 0, the thing UMAP is solving for). a and b are two fixed shape numbers (a ≈ 1.929 , b ≈ 0.7915 ) fitted so that this curve mimics the desired near/far behaviour.
Read v ij like this: when the 2-D distance is 0 , the denominator is 1 , so v ij = 1 (full bond). As the 2-D distance grows, the denominator grows, so v ij → 0 . Same "1 down to 0" spirit as w ij , just a different-shaped curve with heavy tails (it fades more slowly far out, which stops everything crushing into a blob).
Definition min_dist — the hyperparameter behind
a and b
min_dist is a number you choose (typical 0.0–0.99) that sets how close two points are allowed to sit in the final 2-D plot . UMAP fits the shape numbers a , b from your chosen min_dist: a small min_dist (e.g. 0.0) lets v ij stay near 1 even when points nearly touch, so clusters pack tightly; a large min_dist (e.g. 0.8) forces a minimum gap, spreading points out. In short, min_dist tunes the low-D kernel's curve so you can trade tight, dense clusters against a spread-out, readable layout — this is exactly the parent's Worked Example 2.
The final objective compares the high-D bonds w ij sym against the low-D bonds v ij using cross-entropy , written L (a script "L" for Loss — the single number we push downhill).
Intuition What cross-entropy measures, in words
Cross-entropy is a number that is small when two sets of probabilities agree and large when they disagree . Here the two "sets" are the high-D bonds and the low-D bonds. UMAP nudges the low-D dots y i until v ij matches w ij sym as closely as possible — i.e. it minimises L . For the full treatment see Cross-Entropy Loss . The nudging itself is done by stochastic gradient descent — repeatedly taking tiny steps that reduce L , like a ball rolling downhill.
Neighbour set N of i, size k
Exponential fade to weight w_ij
Sum and log2 k calibration
Cross-entropy loss compare
Gradient descent moves y_i
Every arrow is a symbol you now own. Related big-picture methods worth knowing: PCA and Random Projection (linear squashing), Isomap and Spectral Clustering (graph/manifold cousins), Autoencoders (neural squashing), and the deeper theory in Topological Data Analysis .
Try to answer each before revealing. If any stumps you, re-read its section above.
What is the bold-face convention for matrices vs vectors? Bold uppercase (e.g. X , Y ) is a whole matrix/table; plain lowercase with a subscript (e.g. x i , y i ) is one row — a single point/vector.
What does X ∈ R n × d mean in plain words? X is the data matrix: a table of real numbers with n rows (one per data point) and d columns (one per measurement).
What is Y and what is d ′ ? Y is the output matrix — the finished layout with n rows and d ′ columns; d ′ is the small target dimension (usually 2), so the result can be plotted.
What is the difference between x i and y i ? x i is the original high-D data point (a row of X ); y i is its finished low-D position (a row of Y ), the ( x , y ) dot on the plot.
What do the subscripts in d ij tell you? That distance needs two points — point number i and point number j .
Why can you subtract y i − y j , and what does ∥ y i − y j ∥ 2 compute? Because both are vectors of the same length, so you subtract slot by slot; the double bars then give the straight-line (Euclidean, ℓ 2 ) length of that difference.
What is a "metric" and name two besides Euclidean. The ruler used to turn two points into a distance d ij ; e.g. Manhattan (ℓ 1 , sum of absolute gaps) and cosine (angle between the arrows).
What is N ( i ) , and is i itself in it? The set of the k nearest neighbours of point i ; no — i is excluded (a point is not its own neighbour).
What constraint must k (n_neighbors) satisfy and why? k < n — you cannot have more neighbours than there are other points; N ( i ) needs k ≤ n − 1 .
For which j is w ij non-zero? Only for j ∈ N ( i ) (the k nearest neighbours); for all other $