The Mapper Algorithm

A discrete analogue of the Reeb graph

Guilherme Vituri

Symbolic Mind · JuliaTDA · XXIV EBT 2026

The Reeb graph alive

Height function

Collapse each connected component of every level set.

bottom height 4%

Drag the slider, or use ↑ and ↓ while presenting.

The Reeb graph

Given a topological space $X$ and a continuous $f:X\to\mathbb R$ , define the relation

$p\sim q \iff$

$p,q\text{ lie in the same connected component of }f^{-1}(c).$

The Reeb graph is the quotient $X/{\sim}$ .

critical points of $f$ become vertices;
arcs track births, merges, splits, and deaths;
the result records how level sets change.

The topologist’s view

Morse theory turns a space into a compact, one-dimensional skeleton.

The torus and its height function leave behind one loop.

Reeb, 1946

Why we cannot just compute it

The real-world obstruction

We almost never have $X$ . We have a finite sample of it.

Connected components collapse

On a finite point cloud, every point is its own connected component.

Exact fibres disappear

$f^{-1}(c)$ is empty for almost every $c$ .

The trick: replace points by overlapping intervals, and connected components by clustering.

From Reeb to Mapper

A loop-shaped point cloud is covered by four overlapping height intervals. Pulling the intervals back gives six clusters, whose nerve is a six-node loop. — Each cluster becomes a node. Two nodes are joined exactly when their clusters share a sampled point.

Construction after Singh–Mémoli–Carlsson, 2007

A dictionary between worlds

Reeb (continuous)		Mapper (discrete)
topological space $X$	⟶	finite metric space $(X,d)$
$f:X\to\mathbb R$	⟶	any filter on the sample
preimage of a point $c$	⟶	preimage of an interval $U$
connected components	⟶	clusters: DBSCAN, linkage, …

filter $f$ + cover $\mathcal U$ + clustering rule + nerve construction

The hinge: the nerve lemma

If a cover is good, meaning every nonempty finite intersection is contractible, its nerve is homotopy-equivalent to the union.

Everything that follows is the nerve of a cover. Only the cover changes.

Mapper: nerve of a pullback cover.
Ball Mapper: nerve of balls.
Multiscale Mapper: tower of nerves.

The torus, now from a finite sample

Mapper graph of a sampled torus, forming one cycle

10 nodes · 10 edges · one loop · 2 tips. Projection onto $x$ sees the loop between two tails.

One point cloud, different questions

Horizontal slices separate body parts that happen to share a height: 19 nodes · 19 edges · 1 component.

A landmark turns the filter into a direction

The beak supplies an origin, so the graph follows anatomical progress from head to feet: 21 nodes · 21 edges · 1 component.

Eccentricity sees centre versus periphery

Equal-distance shells mix remote body parts, then clustering splits them apart: 38 nodes · 39 edges · 1 component.

Geodesic eccentricity follows the surface

The two foot flares now terminate separately: 0 mixed-foot nodes. Their closest samples are 0.036 apart Euclidean but 1.564 geodesic (43×): 39 nodes · 38 edges · 1 component.

When “statistical” is honest

Mapper is deterministic once its parameters are fixed. Statistics enters in three different places.

sample

Run on a sample, not on $X$ itself.

converge

Converges toward the Reeb graph as the sample grows.

Munch–Wang, 2016

infer

Parameter selection and bootstrap uncertainty.

Carrière–Michel–Oudot, 2018

Structure and stability theory says small perturbations of the data move the 1-D Mapper only a little when the cover is fixed.

Two moves, many Mappers

01 · Build a cover

cluster pullbacks of a filter;
$\varepsilon$ -balls around landmarks;
adaptive balls;
nearest-neighbour-scaled balls.

02 · Build a nerve

edge for any nonempty intersection;
require at least $k$ shared points;
threshold by overlap percentage;
retain higher simplices or weights.

multiscale

A tower of covers and nerves.

codomain

Filters into $S^1$ , graphs, or $\mathbb R^d$ .

structure

Stability via interleavings.

learn

Optimise the filter itself.

Differentiable Mapper learns the filter

Oulhaj · Carrière · Michel, ICML 2024

Reeb fixes the filter.

Mapper chooses it.

Differentiable Mapper learns it.

smooth memberships approximate a hard cover;
persistence values carry the gradient;
Zygote + Optimisers.Adam update $\theta$ ;
implemented in TDAmapper.jl.

Extended persistence makes the objective loop-aware: ordinary $H_0$ sees branches, but a cycle can otherwise have zero loss and zero gradient.

When variance points the wrong way

Controlled benchmark · a table rotated isometrically into

\mathbb R^{10}

A table point cloud with the horizontal PC1 direction and the nearly vertical learned filter direction

Same geometry, hidden orientation.
PC₁ follows the broad tabletop.

A path-shaped Mapper graph produced by the PC1 filter

PC₁: 12 nodes · 2 tips
ordinary H₀ persistence = 0

A four-tip Mapper graph produced by the learned filter

Learned: 44 nodes · 4 tips
ordinary H₀ persistence = 4.40

The learned direction recovers the hidden table normal: $|\cos(\theta,\theta^*)|=0.9999$ , successful in 8 / 8 independent rotations. No part label enters the loss.

Mapper in the wild

Six published case studies · 2011–2017

The famous Mapper pictures did more than compress data.

They turned branches, paths, and repeated shapes into scientific hypotheses.

2011201320152017

A branch became a breast-cancer subgroup

Progression Analysis of Disease Mapper graph of breast tumors with Normal-like, basal-like, ER-negative, ER-positive, and c-MYB-positive regions labelled. — Original Fig. 3 · NKI breast-tumor cohort

Nicolau · Levine · Carlsson · PNAS · 2011

Does gene expression vary through connected disease progressions rather than isolated clusters?

The finding

A dense c-MYB⁺, ER⁺/HER2⁻ arm emerged between sparse regions, an arrangement that ordinary clustering scattered across groups.

The c-MYB⁺ group had 100% observed overall survival in the discovery cohort and a distinct molecular signature; the subgroup was then tested in an independent cohort.

Nicolau et al., doi:10.1073/pnas.1102826108 · Fig. 3 ↗

The same survivor arm appeared twice

Four Mapper networks from the NKI and GSE2034 breast cancer cohorts, separated by survival or relapse and colored by ESR1 or chemokine pathway expression. — Original Fig. 2 · two cohorts, two molecular colorings

Lum et al. · Scientific Reports · 2013

Can a topological patient subgroup recur across different microarray platforms?

The finding

Both cohorts contained a comparable Y-shaped survivor / non-relapse structure with a low-ESR1 arm.

That unusual low-ESR1, good-outcome arm also showed elevated chemokine-pathway expression, turning visual correspondence into a biological lead.

Lum et al., doi:10.1038/srep01236 · Fig. 2 ↗

Five basketball positions became thirteen roles

Low- and high-resolution Mapper networks of 452 NBA players, colored by points per game and annotated with performance roles such as scoring guard, offensive point guard, paint protector, and all-NBA team. — Original Fig. 5 · low resolution left, high resolution right

Alagappan 2012 · Lum et al. 2013

What if a player's position is inferred from performance, not height or a roster label?

The finding

Seven per-minute statistics for 452 players yielded thirteen connected playing styles, not the traditional five positions.

Offensive and defensive point guards separated; “paint protectors,” scoring bigs, and small elite-player islands became visible.

Lum et al., doi:10.1038/srep01236 · Fig. 5 ↗

Type-2 diabetes became three patient profiles

Two patient similarity networks: the full 11,210-patient cohort and a type-2 diabetes network with three subtypes labelled around a large loop. — Original Fig. 1 · all patients above, T2D subtypes below

Li et al. · Science Translational Medicine · 2015

Can one diagnosis hide several clinically and genetically distinct populations?

The finding

Among 2,551 people with T2D, Mapper separated three patient subtypes with different comorbidity patterns.

Subtype 1 emphasized nephropathy / retinopathy; subtype 2 cancer / cardiovascular disease; subtype 3 cardiovascular / neurological disease and other conditions. Genotypes, which were not used to build the graph, showed subtype-specific associations.

Li et al., doi:10.1126/scitranslmed.aaa9364 · Fig. 1 ↗

A 20-year-old trial contained a hidden predictor

Two Mapper analyses of spinal cord injury trials linking perioperative hypertension to poorer locomotor recovery in discovery and validation cohorts. — Original Fig. 5 · discovery cohort left, validation cohort right

Nielson et al. · Nature Communications · 2015

Can connected outcome profiles reveal a factor that conventional trial summaries missed?

The finding

Within matched spinal-cord injuries, the poor-recovery branch was associated with perioperative hypertension.

The relationship was recovered in a separate cohort from the same historical trial, then tested explicitly with conventional statistics.

Nielson et al., doi:10.1038/ncomms9581 · Fig. 5 ↗

Cell fate became a branching trajectory

Single-cell topological representation of embryonic stem cell differentiation into motor neurons, colored by experimental day and marker genes and paired with microscopy images. — Original Fig. 3 · motor-neuron differentiation

Rizvi et al. · Nature Biotechnology · 2017

How do asynchronously differentiating cells move through transient states?

The finding

scTDA recovered a continuous developmental path with four transient identities: pluripotent, precursor, progenitor, and differentiated.

Recoloring the same topology by day and marker expression aligned transcriptional progression with experimentally observed motor-neuron development.

Rizvi et al., doi:10.1038/nbt.3854 · Fig. 3 ↗

The branches carry the story

From theorem to exploration

The data: each player is a performance profile

FBref-derived snapshot · 2020–21

1,513 outfield players from the five major European leagues.

900+ minutes played: enough exposure for per-90 rates to be meaningful.

Source: FBref-derived public mirror by eddwebster/football_analytics. Goalkeepers and incomplete rows are removed.

18 z-scored metrics define the point cloud

ATTACK goals · shots · shots on target · xG · assists · xA

ON THE BALL pass completion · key passes · passes into the box · progressive passes · touches · carries · progressive carries

DEFENCE tackles · interceptions · blocks · clearances

plus a non-penalty goals + assists rate

Player, team, nationality, and position are kept only for interpretation. Mapper sees none of those labels.

Why Mapper, not another scatter?

PCA scatter plot of football players

PCA and UMAP compress overlapping styles into a cloud.

Mapper retains local continuity, then turns changes in that continuity into branches.

The published examples used the same visual grammar:

interesting populations occupy branches, transitions, and repeated shapes, not only isolated clusters.

Here, every node remains linked to the original players and every edge records shared membership.

Football has a shape

1,513 outfield players from the five major European leagues, 2020–21.

18 z-scored per-90 features.

0 position labels shown to Mapper.

Filter: PC₁ · 14 intervals · DBSCAN inside each slice

Football Mapper graph with named specialist players

Who does Mapper call similar?

Football Mapper graph with the selected region's nodes labelled by example players who share each node

Attacking end · nodes 1–8: Messi + Lewandowski; Mbappé + Neymar + De Bruyne; Benzema + Salah; plus five more neighbourhoods.

One graph, many stories

Football Mapper graph coloured by the selected attribute

Goals: the attacking end lights up.

Change the filter, change the question

Football Mapper graph using the selected filter

PC₁: 49 nodes · 68 edges · 6 components · 12 tips.

Same data. Same cover. Same clustering. The filter is doing the work.

The football lens learns, literally

What improved

Ordinary branch persistence: 1.15 → 2.61. Mean node position purity: 0.738 → 0.770.

What did not

Point-weighted purity stays flat: 0.650 → 0.646. More topology is not automatically more meaning.

The pullback still needs clustering

For every cover element $U_i$ , Mapper must split the pullback $f^{-1}(U_i)$ into clusters. Those clusters, rather than the intervals, become nodes.

none

Trivial: one cluster per nonempty pullback. Fast, but disconnected pieces can be merged.

density

DBSCAN: variable cluster count and non-convex shapes. Radius and density thresholds matter.

linkage

Single linkage / first empty bin: cut a dendrogram. Adaptive, but sensitive to chaining.

partition

$k$ -means / $k$ -medoids: request $k$ groups per pullback. Simple, but can force a split.

Clustering changes the nodes themselves. There is no universally neutral refiner.

Same pullback, different answers

Three clustering methods applied to the same noisy two-moons point cloud with a sparse bridge: k-means cuts across the moons, single linkage chains them together, and DBSCAN separates the dense curves while treating the bridge as noise

Same points. Different definitions of “together.” The refiner turns that definition into Mapper nodes.

Same lens, different clustering

Football Mapper graph using the selected pullback clustering algorithm

First empty bin: an adaptive single-linkage cut · 20 nodes · 16 edges · 4 components.

Same PC₁ filter. Same 20 intervals. Same overlap. The refiner decides whether a slice stays whole or branches.

From intervals to rectangles

When $f:X\to\mathbb R^2$ , write $f(x)=(f_1(x),f_2(x))$ and cover the image with overlapping rectangles.

01 · two coordinates

$f(x)=\big(\mathrm{PC}_1(x),\mathrm{PC}_2(x)\big)$

The lens retains two directions instead of ordering every point on one line.

02 · grid cover

$\mathcal U=\{I_i\times J_j\}$

Each observation may lie in several horizontal, vertical, or diagonal neighbours.

03 · pull back + nerve

Cluster every $f^{-1}(I_i\times J_j)$ , then connect clusters that share observations.

$\text{path-like layering in }\mathbb R \quad\longrightarrow\quad \text{grid-like adjacency in }\mathbb R^2$

Two lenses reveal what one cannot

Two-dimensional football Mapper graph using the first two principal components

R2Cover(PC₁, PC₂) uses a $12\times12$ grid.

146 nodes

390 edges

252 cycle rank

A one-dimensional filter with expansion $<1$ maps every node to a slice on a path. Its Mapper graph must be bipartite and triangle-free.

A grid maps to the king graph on $\mathbb Z^2$ . Triangles become possible: this graph has 322.

Overlap has a phase change

layered

At $e>1$ , non-adjacent slices overlap. The loops we would measure can become artefacts of the cover.

Four ways to decide whether an edge is real

Let $A$ and $B$ be two Mapper nodes: clusters of observations from overlapping pullbacks.

simple

$|A\cap B|\ge 1$

One shared observation is enough. This is the ordinary nerve.

minimum count

$|A\cap B|\ge 2$

Reject edges supported by a single observation.

percentage

$\dfrac{|A\cap B|}{\min(|A|,|B|)}\ge .2$

The overlap must explain 20% of at least one cluster.

Jaccard

$\dfrac{|A\cap B|}{|A\cup B|}\ge .1$

Normalise by the combined size of both clusters.

Count thresholds are scale-dependent; relative thresholds compare unequal node sizes more fairly.

The nerve is a modelling choice too

Two-lens Mapper graph using the selected nerve rule

Simple nerve: one shared player creates an edge · 390 edges · 8 components · cycle rank 252.

Same 146 clusters. Same purity. Only the definition of an edge changed. Once thresholded, this is no longer the ordinary nerve, so the nerve lemma does not transfer automatically.

Does the story survive resolution?

coarse

Football Mapper graph at the selected resolution

The ordering of roles is stable. The branch structure is not. Stability theory holds the cover fixed; choosing the cover remains the open problem.

Another kind of Mapper

Ball Mapper covers the data directly

A Julia-generated Ball Mapper construction: a circular point cloud with seven farthest-point landmarks, epsilon balls around them, and the resulting seven-node nerve cycle

01 · landmarks

Choose $L\subset X$ , often by greedy farthest-point sampling, so landmarks spread across the data.

02 · balls

$A_\ell=\{x\in X:d(x,\ell)\le\varepsilon\}$

One node represents each nonempty landmark ball.

03 · nerve

$A_\ell\sim A_m\iff A_\ell\cap A_m\ne\varnothing$

An edge requires a shared observation, not merely intersecting geometric balls.

There is no filter and no within-slice clustering, but the metric, landmarks, radius, and nerve rule still encode modelling choices.

Ball Mapper: no filter, one unforgiving scale

Ball Mapper graph at the selected radius

ε = 3.0: dust · 39 components · 36 isolated landmarks.

In 18 dimensions, distances concentrate. Ball Mapper removes the filter, but its one remaining knob must carry all the weight.

What the experiment taught us

Structure that survived

The broad ordering from defending through midfield to attack persists across resolutions and recolourings.

Structure that did not

Individual branches, loops, and components can change sharply with cover, overlap, lens dimension, and nerve rule.

The picture is an argument, never the conclusion.

Open problems · open stack

Open problems

nonlinear trainable filters;
principled, data-driven cover selection;
uncertainty that includes modelling choices, not only perturbations at a fixed cover;
loop-aware differentiable objectives at scale.

JuliaTDA

TDAmapper.jl
MetricSpaces.jl
TDAplots.jl
Ripserer.jl
PersistenceInference.jl

Fast · composable · native autodiff

github.com/JuliaTDA

Long story short

Reeb fixes the filter · Mapper chooses it · Differentiable Mapper learns it.

And throughout: everything is the nerve of a cover.

And flamingos.

References · origins and applications

Reeb, G. (1946). Sur les points singuliers d’une forme de Pfaff… C. R. Acad. Sci. Paris 222, 847–849.
Singh, G., Mémoli, F., Carlsson, G. (2007). Topological Methods for the Analysis of High-Dimensional Data Sets and 3D Object Recognition. PBG@Eurographics.
Yao, Y. et al. (2009). Topological methods for exploring low-density states in biomolecular folding pathways. J. Chem. Phys. 130, 144115.
Nicolau, M., Levine, A. J., Carlsson, G. (2011). Topology based data analysis identifies a subgroup of breast cancers with a unique mutational profile and excellent survival. PNAS 108, 7265–7270.
Alagappan, M. (2012). From 5 to 13: Redefining the Positions in Basketball. MIT Sloan Sports Analytics Conference.
Lum, P. et al. (2013). Extracting insights from the shape of complex data using topology. Scientific Reports 3, 1236.
Li, L. et al. (2015). Identification of type 2 diabetes subgroups through topological analysis of patient similarity. Sci. Transl. Med. 7, 311ra174.
Nielson, J. L. et al. (2015). Topological data analysis for discovery in preclinical spinal cord injury and traumatic brain injury. Nature Communications 6, 8581.
Rizvi, A. H. et al. (2017). Single-cell topological RNA-seq analysis reveals insights into cellular differentiation and development. Nature Biotechnology 35, 551–560.

References · theory and variants

Munch, E., Wang, B. (2016). Convergence between categorical representations of Reeb space and Mapper. SoCG.
Dey, T., Mémoli, F., Wang, Y. (2016). Multiscale Mapper. SODA.
Carrière, M., Oudot, S. (2018). Structure and Stability of the One-Dimensional Mapper. FoCM 18, 1333–1396.
Carrière, M., Michel, B., Oudot, S. (2018). Statistical Analysis and Parameter Selection for Mapper. JMLR.
Oulhaj, Z., Carrière, M., Michel, B. (2024). Differentiable Mapper for Topological Optimization of Data Representation. ICML.
Dłotko, P. (2019). Ball mapper: a shape summary for topological data analysis. arXiv:1901.07410.

Obrigado!

Guilherme Vituri

Symbolic Mind · JuliaTDA

viturivituri@gmail.com