TDA: Finding the Shape of Your Data

You have a thousand points scattered in space, perhaps from are sensor readings, from embeddings of customer data, or perhaps from molecules in a protein.

The question might not be “how many points” but “what shape do they make”. And you are not interested in clustering or finding groups of points that are closer to each other than others, but rather structure. This could mean loops, voids, or connected components that emerge when points get close enough to matter. In this case we are talking about the topology of un underlying shape that the points are describing.

The LLM apparently thinks topology is about mystical floating shapes ... not entirely wrong.

What TDA Actually Does

Topological Data Analysis gives you a way to ask: “If I connect nearby points, what patterns survive as I change my definition of nearby?”

The simplest example is a circle. Let's say you sample 200 points from a noisy circle and plot them. You see dots, but depending on your viewpoint you will also see either a hole in their middle or a 1-dimensional loop that these points are the shadow of. This is information that persists across many scales.

TDA lets you detect that hole without drawing the circle and needing to manually "observe" it. This matters when your data lives in high dimensions and you cannot just “look at it”.

The topology tells you what the clustering algorithms miss: structural features that are stable across resolutions.

Of course, this is not some magic, it is basic mathematics of the topology of a geometric shape. So, if your data has no meaningful geometric structure, perhaps it is really just random noise, TDA might not tell you anything.

Two Paths to Persistent Homology

When people say “TDA,” they usually mean persistent homology. If you are mathematically inclined this is a subgroup of simplicial homology, otherwise this is a computational way of tracking topological features (connected components, loops, voids) as you sweep through distance thresholds.

There are two dominant approaches in Python, and they differ philosophically.

Path 1: ripser — The Fast and Focused Pipeline

ripser is built around one workflow: point cloud in, persistence diagram out. No detours.

What you get back:

• dgms[0]: birth and death times of connected components (0-dimensional features)

• dgms[1]: birth and death times of loops (1-dimensional features)

So what are these features? Each array dgms[0] and dgms[1] has two columns and each row is a feature of that corresponding dimension. The first entry in a row is the time of birth, the second entry is the death.

Let's say we have a 0-dimensional feature and the row is of the form

[0.0, 0.004]

This means, this is a connected component being birthed at radius 0 and dying at radius 0.004. This is a single point In this case we are talking about a single point as a connected component that is 0.004 away from the next nearest point. Hence when our radius gets big enough the two points get put together into one connected component.

Of course, every point starts in its own connected component at radius 0, so you will have a total of 200 0-dimensional features in this example. One of those features will survive forever in this example, this is the connected component that is the circle itself.

The 1-dimensional features should not exist at 0, since there would be no loops present when each point is for itself, then with time more will appear and some of them will die when absorbed into others. At some value, all points will be connected via 2-dimensional simplices to the point that the underlying shape becomes the shadow of a disk and becomes contractible. At which point all the 1-dimensional features die.

The idea is that the longer a feature persists (death minus birth), the more “real” it is.

For the noisy circle, you will see one strong 1-dimensional feature — the hole in the middle — that appears early and dies late. Everything else is noise that appears and vanishes quickly.

Path 2: GUDHI — The Mathematical Toolbox

GUDHI gives you control over the filtration — the process of building up simplicial complexes as you increase the distance threshold.

It supports multiple complex types: Rips, Alpha, Čech, Witness, Cubical. On the other hand, ripser only supports the Vietoris-Rips complex and that is it.

We have added some more features to this code. Showing both the point cloud, the features and their life span and then the diagram with the features.

The difference is not just on the API side. With GUDHI, you get the simplex tree, a data structure that encodes the entire topological history of your complex. You can query it, filter it, and extract exact simplices that created each feature. For example we could add the following

for simplex, filtration_value in simplex_tree.get_filtration():
    print(simplex, filtration_value)

This would give you a list of all simplices that appear anywhere in the construction of the complex, as a list of vertices followed by the value they are birthed.

This is something that ripser does not give you. It is optimized for speed by skipping the explicit complex construction.

When the Difference Matters

Use ripser when:

You have point cloud data, you want persistence diagrams, and you do not care about the intermediate structure. Most machine-learning-flavored TDA workflows fit here.

Use GUDHI when:

You need to inspect the actual simplices, try different complex types, or work with cubical data (images, grids). GUDHI is also the right choice if you are doing research-level computational topology and need mathematically complete tools.

A concrete example: if you are building features from persistence diagrams to feed into a classifier, ripser is faster and simpler. If you need to understand why a particular loop appeared, hence you need to know which exact points created it, you need GUDHI.

Detecting Clusters vs. Detecting Voids

Let’s compare what TDA sees versus what clustering sees.

Looking at the plot, it is not surprising that K-means tells you there are three groups

But unless we color them, it is not obvious where a possible 1-loop would be. If we now look at the persistent homology features

TDA tells you that meaningful 1-dimensional loops exist. Meaningful here means that of the three 1-dimensional features that appear

birth=2.819, death=3.234, persistence=0.415
birth=2.743, death=4.384, persistence=1.641
birth=2.722, death=4.142, persistence=1.419

at least 2 have a much longer persistence than the others. The 3 clusters are much harder to see, since there is not a clear cut off point. Of course what can be considered meaningful will depend on the application, every 1-loop will vanish if the scale is made big enough. I that case so many points are connected that the point cloud described a contractible space.

This difference here is: Clustering answers “how are the points grouped”. Topology answers “what shape do the groups make together”. None of them is better than the other, but they can complement each other.

Persistence Diagrams Are Not the End

A persistence diagram is a scatter plot where each point is a topological feature. The x-axis is birth time, the y-axis is death time. The rule of thumb here is: Points far from the diagonal are persistent features, points near the diagonal are noise.

But diagrams are hard to feed into machine learning models. They are sets of points, not vectors.

This is where persistence images and persistence landscapes come in — ways to turn diagrams into fixed-size feature vectors. persim handles this transformation:

We generate 3 of our point clouds the same way as before and generate their persistence diagrams, for the 1-dimensional features only. Afterwards we have the persistence images, these are smoothed 2D histogram of the persistence diagram. Features that persist longer contribute more weight. These are more useful informations that one can feed into a neural network, similar to the situation when working with images.

Scaling and Practical Limits

Persistent homology is computationally expensive. The Vietoris-Rips complex for n points has O(n^2) edges and potentially exponential higher-dimensional simplices.

While ripser is fast because it uses sparse matrix tricks and a compressed annotation format, even ripser will struggle past 5,000–10,000 points without subsampling. So if you have large data, you will need a more involved strategy.

Option 1: Subsample intelligently

For example reduce to cluster representatives via K-Means:

This preserves large-scale structure while making computation feasible. As usual in any type of machine learning, this will need testing and consideration to get the correct ratios.

Option 2: Use GUDHI’s witness complex

Witness complexes let you compute topology using a small subset of “landmark” points while still respecting the full dataset.

This is compositional in a way that makes large datasets tractable.

When NOT to Use TDA

TDA is a very specialized tool.

Do not use it when:

• Your data has no geometric structure (text embeddings from a bag-of-words model, for example)

• You only care about local neighborhoods (use UMAP or t-SNE instead)

• You have a supervised learning problem with good labels (just train a classifier)

• Your data is truly high-dimensional with no low-dimensional manifold structure

TDA shines when you suspect your data lives on or near a low-dimensional shape embedded in high-dimensional space. If that assumption does not hold, the persistence diagrams will be noisy and uninformative.

A reasonable heuristic: if dimensionality reduction techniques like PCA or UMAP reveal interesting structure, TDA might reveal why that structure exists topologically.

What Comes Next

This post focused on the core pipeline: point clouds, filtrations, persistence diagrams. We covered ripser for speed and GUDHI for mathematical completeness.

But the real question is: what do you do with the diagrams once you have them?

In the next post, we will look at downstream workflows: using persistence features inside machine-learning pipelines, comparing shapes with Wasserstein distances, and building Mapper-style visualizations that turn high-dimensional data into interpretable graphs.

The tools change, but the idea behing everything stays the same: topology is about finding the shape that survives the noise.