When thinking about data, the first thing that probably comes to your mind is numbers. You might picture standard metrics used to characterize datasets, like the mean, median, and standard deviation. But what if you started analyzing your data through the lens of its geometric features? What if you could study the hidden "holes" that appear in your data?

To explain how such a magic trick can be performed, it is sensible to first look at what Topology actually means. Topology is a field of mathematics that deals with the study of shapes and their properties, more precisely, you can think of it as the study of how those properties behave when a shape is stretched, twisted, or bent. You might have seen a famous meme on your favorite nerd page claiming that a donut and a coffee mug are the exact same thing. It may sound strange at first glance, but if you imagine a donut made out of playdough, you can find a way to mold it into the shape of a coffee mug without tearing it.

If you are clever enough, you immediately noticed that another way to tell if a coffee mug and a donut are the same thing is to simply count the number of holes. Although I haven't mathematically defined what a "hole" is for you just yet, it is natural for you to look at a donut and a coffee mug and intuitively recognize it. We are going to apply that exact same intuition to numbers.

This article is divided into three sections where you will explore a practical example: studying the S&P 500, the benchmark index tracking the stock performance of 500 of the largest U.S. companies, during the COVID-19 crisis. In the first section, I'll introduce you to the notion of simplicial complexes and explain how to build them. I will exemplify how to partition the time series into pieces and build simplicial complexes for each piece, which will give you a geometric representation of your data. In the second section, I will show you how to detect the holes in these shapes using a tool called homology, and I'll show you how to do it in practice with Python to obtain so-called persistent diagrams. In the last section, I will show you how to compare these diagrams and how they reveal the underlying patterns of your data.

💻 The full code for this post is available on GitHub. Feel free to clone it and follow along.

1. From Time Series to Shapes: Building Simplicial Complexes

Time Series

$$\text{A time series is a sequence } (x_t)_{t=0}^n \text{ of real numbers}.$$

That's the object you start with, nothing exotic yet! Here is the S&P 500 time series, with values ranging from 1st January 2018 to 31st December 2023.

To really get under the hood, we’ll switch to the time series of log returns. We do this because log returns normalize the data, turning compounding growth into a much easier, flat line of math to work with. Here’s the formula you can use to get there, and the updated chart.

$$r_t = \ln\left(\frac{P_t}{P_{t-1}}\right)$$

Where \(r_t\) is the log return at time \(\text{$t$}\) , \(P_t\) is the price at time \(\text{$t$}\) and \(P_{t-1}\) is the price at time \(t-1\).

Your goal in this section is to turn this sequence of numbers into an actual geometric shape you can study. To do that, let's define what kind of shape you're building towards: a simplicial complex.

Simplicial Complexes

An (abstract) simplicial complex \(\text{$K$}\) is a collection of finite subsets of a vertex set \(\text{$V$}\) , called simplices, such that \(\text{$K$}\) is closed under taking subsets:

$$\sigma \in K \text{ and } \tau \subseteq \sigma \Rightarrow \tau \in K$$

In plain terms: if a simplex is in the complex, all of its "sub-pieces" must be too.

Simplices have a dimension based on how many vertices they contain:

• a single vertex \(\lbrace v \rbrace\) is a 0-simplex (a point)

• a pair \(\lbrace v_1, v_2 \rbrace\) is a 1-simplex (an edge)

• a triple \(\lbrace v_1, v_2, v_3 \rbrace\) is a 2-simplex (a filled triangle)

• a quadruple \(\lbrace v_1, v_2, v_3, v_4 \rbrace\) is a 3-simplex (a filled tetrahedron)

• and so on in higher dimensions

Take the 2-simplex \(\lbrace v_1, v_2, v_3 \rbrace\) as an example. Because a simplicial complex must be closed under subsets, all of its faces have to be included too: the three vertices \(\lbrace v_1 \rbrace\), \(\lbrace v_2 \rbrace\), \(\lbrace v_3 \rbrace\) , the three edges \(\lbrace v_1, v_2 \rbrace\), \(\lbrace v_1, v_3 \rbrace\), \(\lbrace v_2, v_3 \rbrace\), and the triangle itself.

Stitch enough of these simplices together, sharing vertices and edges, and you get a simplicial complex, a shape built entirely out of points, edges, triangles, and their higher-dimensional analogues. Here is an example shown in Wikipedia:

You've probably noticed that you need a set of vertices before you can build that simplicial complex. In TDA, the trick is to slice your time series into moving windows of equal length (in this case 60 days). For each window, you build a set of vertices, often called a point cloud. You can choose any dimension you want, but just stick to 3 dimensions for now.

To make this happen in Python, you will use the giotto-tda library. First, import the specific tools you need for the job:

# giotto-tda for tda tools
from gtda.time_series import SlidingWindow, TakensEmbedding
from gtda.homology import VietorisRipsPersistence
from gtda.diagrams import PairwiseDistance

Next, set up the moving windows. You are grabbing chunks of 60 days at a time. By setting stride=1, you just shift forward one single day to create your next window. Go ahead and apply this to your log returns array to chop it all up:

# create the sliding windows
windows = SlidingWindow(size=60, stride=1)

# fit and transform the log returns array
log_returns_windows = windows.fit_transform(log_returns_array)

Now for the fun part: turning those flat 60-day chunks into actual 3D point clouds using Takens Embedding. If you are wondering what that is, think of it as a mathematical trick that folds a 1D time series into a multi-dimensional shape. It does this by taking delayed copies of your data and using them as coordinates! Here is an example:

$$\begin{align} &\text{Your first 60-day window: } W_0 = [r_1, r_2, r_3, r_4, \dots, r_{60}] \newline &\text{Using } \text{dimension}=3 \text{ and } \text{time_delay}=1\text{, your 3D points become:} \newline &p_1 = (r_1, r_2, r_3) \newline &p_2 = (r_2, r_3, r_4) \newline &p_3 = (r_3, r_4, r_5) \newline &\dots \newline &p_{58} = (r_{58}, r_{59}, r_{60}) \end{align}$$

In the code, you set dimension=3 because you want 3D points. You also set time_delay=1, meaning you just use consecutive days to build the x, y, and z coordinates of each point. Set it up, run your windows through it, and you've got your vertices.

# create the takens embedding
takens_emb = TakensEmbedding(time_delay=1, dimension=3)

# fit and transform the sliding windows
log_returns_te = takens_emb.fit_transform(log_returns_windows)

Here is the result for the first window of 60 days:

From point clouds to complexes: Čech Complex and Vietoris-Rips Complex

So far, this has been pure combinatorics. To actually connect this to your data, you need to build simplicial complexes out of that set of vertices. As you can imagine, there are plenty of ways to pull this off. I'm going to show you two methods, starting with the Čech Complex.

Here is the recipe for the Čech Complex:

• Start with a point cloud (your set of vertices).

• Pick a very small radius \(\text{$r$}\), and imagine a ball of radius \(\text{$r$}\) centered on every single point.

• Now, let the radius \(\text{$r$}\) grow. Whenever the balls of \(\text{$n$}\) vertices all overlap (their intersection is non-empty), connect them to build an (n-1)-simplex.

• This gives you a simplicial complex for every single radius r.

Mathematically:

$$\begin{align} &\text{Čech} _{r}(V) = \left\lbrace [v _{0}, v _{1}, \dots, v _{n}] \mid \bigcap _{i=0}^n B _{r}(v _{i}) \neq \varnothing \right\rbrace \end{align}$$

The image shows an example in 2D.

Here is the recipe for the Vietoris-Rips Complex:

• Start with your point cloud (your set of vertices).

• Pick a small radius \(\text{$r$}\), and imagine a ball of radius \(\text{$r$}\) centered on every single point.

• Let the radius \(\text{$r$}\) grow. Whenever the balls of \(\text{$n$}\) vertices overlap pairwise (meaning every single ball in the group touches every other ball in the group), connect them to build an (n-1)-simplex.

• It doesn't matter if there is an empty space in the middle of them all, if they all touch each other pairwise, you build the simplex!

Mathematically:

$$\begin{align} &VR _{r}(V) = \left\lbrace [v _{0}, v _{1}, \dots, v _{n}] \mid \forall _{i, j} ~ d(v _{i}, v _{j}) \le 2r \right\rbrace \end{align}$$

The image shows an example in 2D.

Notice that on the right side of the image, those 3 balls don't even need a shared, non-empty intersection to form a 2-simplex. Pairwise overlap is all it takes!

So, what is the point of growing these balls and building all these complexes? As your radius increases and the simplices connect, you will notice holes starting to form in your shape. As the radius keeps growing, those holes eventually fill in and disappear. By keeping track of exactly when a hole is born and when it dies, you capture its "lifetime". That lifespan is the exact hidden information you are going to use to analyze your data.

2. Finding the Holes: Homology and Persistence Diagrams

What is Homology?

Now that you have your expanding balls and your simplicial complexes, you need a way to track the empty space left behind. In topology, the mathematical tool used to count and classify these empty spaces is called Homology.

Don't let the formal name intimidate you. Homology is just a rigorous way of asking, "How many holes are in this shape, and what kind of holes are they?". As your radius grows and your vertices connect, Homology simply acts as a ledger, keeping track of every time a gap forms and every time a gap fills in.

The dimension of holes

Not all holes are the same. A gap between two isolated dots is mathematically different from the hole in the middle of a donut. Homology categorizes features by their dimension, using homology groups, denoted as \(H_n\). To actually count how many of these features exist in each dimension, we use a metric called the Betti number, denoted as \(\beta_n\). If that is a bit too much mathematics for you, just ignore the hard words, all you really need to remember is that we are simply counting the empty spaces. Here are the three you will see most often:

• \(H_0\) (Connected Components): Think of these as isolated islands of data. When the radius is tiny, every single vertex is its own \(H_0\) component. As the radius grows, these islands merge together until everything is just one giant clump.

• \(H_1\) (1D Voids / Loops): This is your classic "donut hole" or rubber band. It happens when a chain of edges forms a closed ring with empty space in the exact middle.

• \(H_2\) (2D Voids / Cavities): Think of the hollow inside of a ping-pong ball or a balloon. This is a trapped pocket of empty space completely surrounded by filled-in triangles (2-simplices).

Reading the Persistence Diagram

So, you are tracking \(H_0\), \(H_1\), and \(H_2\) as your radius expands. How do you actually visualize all that data? You plot it on a Persistence Diagram.

A Persistence Diagram is just a 2D scatter plot where every single topological feature (every component, loop, or cavity) gets its own dot. Here is how you read it:

• The X-Axis (Birth): This records the exact radius size where the hole first appeared.

• The Y-Axis (Death): This records the exact radius size where the hole finally filled in and vanished.

• The Diagonal Line (x=y): This is the most important part of the diagram. If a hole is born and then dies almost immediately after, its dot will plot right next to this diagonal line. We usually consider these short-lived dots to be topological noise.

• The Persistent Features: If a hole is born early but survives a long time before filling in, its dot will plot high up and far away from the diagonal line. These dots represent strong, real, persistent structures in your data!

Now it is time to bring the theory to life and calculate the Homology of your 3D point clouds using giotto-tda.

# create the homology requirements (holes of dimension 0, 1 and 2, prime field with p=2)
homology = VietorisRipsPersistence(metric='euclidean', homology_dimensions=(0, 1, 2), coeff=2)

# calculate the persistent homology
log_returns_homology = homology.fit_transform(log_returns_te)

• homology_dimensions=(0, 1, 2): This tells the algorithm to track the exact \(H_0\), \(H_1\), and \(H_2\) features you just learned about. If you want to speed up the calculation and don't care about 2D cavities, update this explicitly to (0, 1).

• metric='euclidean': This uses standard straight-line distance to check for overlapping balls. You can change this to other distance metrics like 'manhattan' or 'cosine' if you are experimenting.

With the math done, generating the actual Persistence Diagram is just a single line of code.

# show persistent diagram of the window
homology.plot(log_returns_homology, window_index)

The different colors map directly to the different dimensions of holes. Can you see some dots hugging that diagonal line? That is just short-lived topological noise. But look at the dots further away from the line. Those represent holes that lived a long time before filling in. Those are the persistent, underlying structural features for this specific 60-day window in the market.

A quick note on the math

The actual machinery behind homology is significantly deeper and more complex than just expanding balls and counting holes. If you want to dive into the rigorous, formal mathematics, I highly recommend checking out Žiga Virk's freely available book. You can also find mathematical breakdowns directly in the giotto-tda documentation.

3. Comparing Shapes: What Persistence Diagrams Tell Us About the Market

You now have a rolling sequence of Persistence Diagrams, one for every single 60-day window in your dataset. But looking at thousands of scatter plots isn't going to help you. You need a way to mathematically measure how much the topological shape of the market changes from one day to the next.

To do this, you calculate the distance between consecutive Persistence Diagrams. If the market is behaving normally, today's 60-day window will have almost the exact same topological shape as yesterday's, and the distance will be near zero. If the market suddenly crashes, the geometry shatters, new holes form, and the distance between the diagrams will spike.

There are two main ways to calculate this distance:

• Wasserstein Distance: This measures the total overall change. It calculates the total work or energy required to shift every single dot in the first diagram to match the dots in the second diagram. Given two diagrams \(D_1\) and \(D_2\) and the diagonal \(\Delta\), consider all bijections (one-to-one correspondence) \(\phi \colon D_1 \cup \Delta \to D_2 \cup \Delta\), and the norm \(||-|| _{\infty}\) in \(\mathbb{R}^2\) , the p-Wasserstein distance between the diagrams is defined as:

$$\inf _{\phi} \left( \sum _{x \in D _{1} \cup \Delta} ||x - \phi(x)|| _{\infty}^p \right)^{1/p}$$

• Bottleneck Distance: This is actually a special, extreme case of the Wasserstein distance (specifically, the \(\infty\)-Wasserstein distance). Instead of summing up all the small shifts, it ignores the small stuff and isolates only the single largest, most extreme movement between any matched pair of dots. Because it only cares about the maximum disruption, it is perfect for spotting sudden, violent market shocks.

$$\inf _{\phi} \sup _{x \in D _{1} \cup \Delta} ||x - \phi(x)|| _{\infty}$$

To calculate this in giotto-tda, you use the distance tools to compare your rolling sequence of homologies.

# specify bottleneck distance to compare persistence diagrams
distances = PairwiseDistance(metric='bottleneck')

# calculate only sequential bottleneck distances (diagram i vs diagram i+1)
log_returns_bottleneck = np.array([distances.fit_transform(log_returns_homology[i:i+2])[0, 1] for i in range(len(log_returns_homology) - 1)])

• Change metric='bottleneck' to metric='wasserstein' if you want to measure the total geometric shift rather than the single maximum disruption.

Once you have that array of distances, it is time to plot them directly over your actual market prices to see the topological regime changes in action.

When you look at the plot, the connection between topology and market behavior becomes undeniable. During steady bull runs or sideways chop, the Bottleneck distance stays relatively flat and quiet. The shape of the market is stable.

But look at what happens right as the market drops. The Bottleneck distance violently spikes. The underlying 3D point cloud of your price data has fundamentally transformed, opening up new topological holes and cavities. By tracking the birth and death of these shapes, you aren't just looking at a moving average, you are mathematically measuring the exact moment the structure of the market breaks.

Conclusion

Let’s be honest, staring at a standard line chart of stock prices is a great way to go cross-eyed and learn absolutely nothing new. But look at what you just pulled off instead.

You took that flat, boring price data, folded it into a 3D point cloud using Takens embedding, and blew up expanding mathematical bubbles around every single point just to see where the empty spaces were. You tracked the exact moment those topological holes were born and when they died, plotting them onto a Persistence Diagram like a weird, geometric heart monitor for the market.

Then, instead of just crossing your fingers or squinting at a lagging moving average to guess if a crash was coming, you used the Bottleneck distance to measure the exact moment the market's underlying structure snapped in half.

Financial markets are messy, irrational, and mostly driven by panic. But underneath all that noise, the chaos actually has a shape. And now, you have the Python code to mathematically measure exactly when that shape breaks.

Thanks for reading! You can connect with me on LinkedIn and GitHub.

References

• S&P Dow Jones Indices LLC, S&P 500 [SP500], retrieved from FRED, Federal Reserve Bank of St. Louis; https://fred.stlouisfed.org/series/SP500, August 30, 2026.

• Ž. Virk. Introduction to Persistent Homology. Založba UL FRI, University of Ljubljana, 2022, doi: 10.51939/0002.

• giotto-tda: A Topological Data Analysis Toolkit for Machine Learning and Data Exploration, Tauzin et al, arXiv:2004.02551, 2020.