introvoyz041/TDA-tutorial
04
1# Tutorials for Topological Data Analysis with the Gudhi Library2 3Topological Data Analysis (TDA) is a recent and fast growing field4providing a set of new topological and geometric tools to infer relevant5features for possibly complex data. Here we propose a set of notebooks6for the practice of TDA with the Python Gudhi library together with7popular machine learning and data sciences libraries. See for instance8[this paper](https://arxiv.org/abs/1710.04019) for an introduction to9TDA for data science. The complete list of notebooks can also be found10at the end of this page.11 12## Install Python Gudhi Library13 14See the [installation15page](https://gudhi.inria.fr/python/latest/installation.html) or16if you have conda you can make a [conda17install](https://anaconda.org/conda-forge/gudhi).18 19## TDA Analysis Pipeline20 21### 01 - Simplex trees and simpicial complexes22 23TDA typically aims at extracting topological signatures from a point24cloud in $\mathbb{R}^d$ or in a general metric space. By studying the topology25of a point cloud, we actually mean studying the topology of the unions26of balls centered at the point cloud, also called *offsets*. However,27non-discrete sets such as offsets, and also continuous mathematical28shapes like curves, surfaces and more generally manifolds, cannot easily29be encoded as finite discrete structures. [Simplicial30complexes](https://en.wikipedia.org/wiki/Simplicial_complex) are31therefore used in computational geometry to approximate such shapes.32 33A simplicial complex is a set of34[simplices](https://en.wikipedia.org/wiki/Simplex), they can be seen as35higher dimensional generalization of graphs. These are mathematical36objects that are both topological and combinatorial, a property making37them particularly useful for TDA. The challenge here is to define such38structures that are proven to reflect relevant information about the39structure of data and that can be effectively constructed and40manipulated in practice. Below is an exemple of simplicial complex:41 4243 44A filtration is an increasing sequence of sub-complexes of a simplicial45complex $\mathcal{K}$. It can be seen as ordering the simplices included in46the complex $\mathcal{K}$. Indeed, simpicial complexes often come with a47specific order, as for [Vietoris-Rips48complexes](https://en.wikipedia.org/wiki/Vietoris%E2%80%93Rips_complex),49[Cech complexes](https://en.wikipedia.org/wiki/%C4%8Cech_complex) and50[alpha51complexes](https://en.wikipedia.org/wiki/Alpha_shape#Alpha_complex).52 53[Notebook: Simplex trees](tutorials/Tuto-GUDHI-simplex-Trees.ipynb). In Gudhi,54filtered simplicial complexes are encoded through a data structure55called simplex tree. Vertices are represented as integers, edges as56pairs of integers, etc.57 5859 60[Notebook: Vietoris-Rips complexes and alpha complexes from data61points](tutorials/Tuto-GUDHI-simplicial-complexes-from-data-points.ipynb).62In practice, the first step of the **TDA Analysis Pipeline** is to define a63filtration of simplicial complexes for some data. This notebook explains64how to build Vietoris-Rips complexes and alpha complexes (represented as65simplex trees) from data points in $\mathbb{R}^d$, using the simplex tree data66structure.67 68 69This [Notebook](tutorials/Tuto-GUDHI-alpha-complex-visualization.ipynb) shows how to visualize simplicial complexes.70 71 72[Notebook: Rips and alpha complexes from pairwise73distance](tutorials/Tuto-GUDHI-simplicial-complexes-from-distance-matrix.ipynb).74It is also possible to define Rips complexes in general metric spaces75from a matrix of pairwise distances. The definition of the metric on the76data is usually given as an input or guided by the application. It is77however important to notice that the choice of the metric may be78critical to reveal interesting topological and geometric features of the79data. We also give in this last notebook a way to define alpha complexes80from matrix of pairwise distances by first applying a [multidimensional81scaling (MDS)](https://en.wikipedia.org/wiki/Multidimensional_scaling)82transformation on the matrix.83 84TDA signatures can extracted from point clouds but in many cases in data85sciences the question is to study the topology of the sublevel sets of a86function.87 8889 90Above is an example for a function defined on a subset of91$\mathbb{R}$ but in general the function $f$ is defined on a subset of92$\mathbb{R}^d$.93 94[Notebook: cubical complexes](tutorials/Tuto-GUDHI-cubical-complexes.ipynb). One95first approach for studying the topology of the sublevel sets of a96function is to define a regular grid on97$\mathbb{R}^d$ and then to define a filtered complex based on this grid and the98function $f$.99 100### 02 - Persistent homology and persistence diagrams101 102Homology is a well-known concept in algebraic topology. It provides a103powerful tool to formalize and handle the notion of topological features104of a topological space or of a simplicial complex in an algebraic way.105For any dimension $k$, the $k$-dimensional *holes* are represented by a vector106space $H\_k$, whose dimension is intuitively the number of such independent107features. For example, the $0$-dimensional homology group $H\_0$ represents the108connected components of the complex, the $1$-dimensional homology group $H\_1$109represents the $1$-dimensional loops, the $2$-dimensional homology group $H\_2$110represents the $2$-dimensional cavities and so on.111 112Persistent homology is a powerful tool to compute, study and encode113efficiently multiscale topological features of nested families of114simplicial complexes and topological spaces. It encodes the evolution of115the homology groups of the nested complexes across the scales. The116diagram below shows several level sets of the filtration:117 118119 120[Notebook: persistence diagrams](tutorials/Tuto-GUDHI-persistence-diagrams.ipynb)121In this notebook we show how to compute barcodes and persistence122diagrams from a filtration defined on the Protein binding dataset. This123tutorial also introduces the bottleneck distance between persistence124diagrams.125 126### 03 - Representations of persistence and linearization127 128In this [notebook](tutorials/Tuto-GUDHI-representations.ipynb), we learn how to129use alternative representations of persistence with the representations130module and finally we see a first example of how to efficiently combine131machine learning and topological data analysis.132 133This [notebook](tutorials/Tuto-GUDHI-Expected-persistence-diagrams.ipynb)134illustrates the notion of “Expected Persistence Diagram”, which is a way135to encode the topology of a random process as a deterministic measure.136 137This [notebook](tutorials/Tuto-GUDHI-persistent-entropy.ipynb) shows how to summarize138the information given by persistent homology using persistent entropy (a139number) and the ES-function (a curve) and explains in which situations they140can be useful.141 142### 04 - Statistical tools for persistence143 144For many applications of persistent homology, we observe topological145features close to the diagonal. Since they correspond to topological146structures that die very soon after they appear in the filtration, these147points are generally considered as “topological noise”. Confidence148regions for persistence diagram provide a rigorous framework to this149idea. This [notebook](tutorials/Tuto-GUDHI-ConfRegions-PersDiag-datapoints.ipynb)150introduces the subsampling approach of [Fasy et al. 2014151AoS](https://projecteuclid.org/download/pdfview_1/euclid.aos/1413810729).152 153### 05 - A Bayesian Framework for Persistent Homology154 155C. Oballe and V. Maroulas provide a156[tutorial](https://github.com/coballejr/misc/blob/master/Tuto-GUDHI-bayes-tda.ipynb)157for a Python module that implements the model for Bayesian inference158with persistence diagrams introduced in their159[paper](https://epubs.siam.org/doi/abs/10.1137/19M1268719).160 161### 06 - Machine learning and deep learning with TDA162 163Two libraries related to Gudhi:164 165 - [ATOL](https://github.com/martinroyer/atol): Automatic166 Topologically-Oriented Learning. See [this167 tutorial](https://github.com/martinroyer/atol/blob/master/demo/atol-demo.ipynb).168 - [Perslay](https://github.com/MathieuCarriere/perslay): A Simple and169 Versatile Neural Network Layer for Persistence Diagrams. See [this170 notebook](tutorials/Tuto-GUDHI-perslay-visu.ipynb).171 172### 07 - Alternative filtrations and robust TDA173 174This [notebook](tutorials/Tuto-GUDHI-DTM-filtrations.ipynb) introduces the175distance to measure (DTM) filtration, as defined in [this176paper](https://arxiv.org/abs/1811.04757). This filtration can be used177for robust TDA. The DTM can also be used for robust approximations of178compact sets, see this [notebook](tutorials/Tuto-GUDHI-kPDTM-kPLM.ipynb).179 180### 08 - Topological Data Analysis for Time series181 182### 09 - Cover complexes and the Mapper Algorithm183 184### 10 - TDA and dimension reduction185 186### 11 - Inverse problem and optimization with TDA187 188In this [notebook](tutorials/Tuto-GUDHI-optimization.ipynb), we will see how Gudhi and189Tensorflow can be combined to perform optimization of persistence diagrams to190solve an inverse problem. This other, less complete191[notebook](tutorials/Tuto-GUDHI-PyTorch-optimization.ipynb) shows that this kind of192optimization works just as well with PyTorch.193 194## Complete list of notebooks for TDA195 196[Simplex trees](tutorials/Tuto-GUDHI-simplex-Trees.ipynb)197 198[Vietoris-Rips complexes and alpha complexes from data199points](tutorials/Tuto-GUDHI-simplicial-complexes-from-data-points.ipynb)200 201[Visualizing simplicial202complexes](tutorials/Tuto-GUDHI-alpha-complex-visualization.ipynb)203 204[Rips and alpha complexes from pairwise205distance](tutorials/Tuto-GUDHI-simplicial-complexes-from-distance-matrix.ipynb)206 207[Cubical complexes](tutorials/Tuto-GUDHI-cubical-complexes.ipynb)208 209[Persistence diagrams and bottleneck210distance](tutorials/Tuto-GUDHI-persistence-diagrams.ipynb)211 212[Representations of persistence](tutorials/Tuto-GUDHI-representations.ipynb)213 214[Expected Persistence215Diagram](tutorials/Tuto-GUDHI-Expected-persistence-diagrams.ipynb)216 217[Confidence regions for persistence diagrams - data218points](tutorials/Tuto-GUDHI-ConfRegions-PersDiag-datapoints.ipynb)219 220[ATOL221tutorial](https://github.com/martinroyer/atol/blob/master/demo/atol-demo.ipynb)222 223[Perslay](tutorials/Tuto-GUDHI-perslay-visu.ipynb)224 225[DTM-filtrations](tutorials/Tuto-GUDHI-DTM-filtrations.ipynb)226 227[kPDTM-kPLM](tutorials/Tuto-GUDHI-kPDTM-kPLM.ipynb)228 229[Inverse problem and optimization with TDA](tutorials/Tuto-GUDHI-optimization.ipynb)230 231[PyTorch differentiation of diagrams](tutorials/Tuto-GUDHI-PyTorch-optimization.ipynb)232 233Contact : <bertrand.michel@ec-nantes.fr>234