0
# Persistent Homology
1

2
Comprehensive tools for computing, analyzing, and visualizing persistent homology. These functions provide the core analysis capabilities for understanding topological features and their persistence across filtration scales.
3

4
## Capabilities
5

6
### Persistence Visualization
7

8
Functions for creating visual representations of persistent homology results including persistence diagrams, barcodes, and density plots.
9

10
```python { .api }
11
def plot_persistence_diagram(persistence, **kwargs):
12
    """
13
    Plot persistence diagram.
14
    
15
    Parameters:
16
    - persistence: List of persistence pairs
17
    - alpha: Transparency level (0-1)
18
    - band: Width of confidence band
19
    - max_plots: Maximum number of plots
20
    - inf_delta: Shift for infinite persistence points
21
    - legend: Whether to show legend
22
    - colormap: Matplotlib colormap name
23
    - axes: Matplotlib axes object
24
    - fontsize: Font size for labels
25
    """
26

27
def plot_persistence_barcode(persistence, **kwargs):
28
    """
29
    Plot persistence barcode.
30
    
31
    Parameters:
32
    - persistence: List of persistence pairs
33
    - alpha: Transparency level (0-1)
34
    - max_intervals: Maximum number of intervals to plot
35
    - inf_delta: Shift for infinite persistence points
36
    - legend: Whether to show legend
37
    - colormap: Matplotlib colormap name
38
    - axes: Matplotlib axes object
39
    - fontsize: Font size for labels
40
    """
41

42
def plot_persistence_density(persistence, **kwargs):
43
    """
44
    Plot persistence density.
45
    
46
    Parameters:
47
    - persistence: List of persistence pairs
48
    - dimension: Dimension to plot (None for all)
49
    - max_intervals: Maximum number of intervals
50
    - nbins: Number of bins for density estimation
51
    - bw_method: Bandwidth selection method
52
    - colormap: Matplotlib colormap name
53
    - axes: Matplotlib axes object
54
    """
55
```
56

57
### Distance Computations
58

59
Functions for computing distances between persistence diagrams, essential for statistical analysis and machine learning applications.
60

61
```python { .api }
62
def bottleneck_distance(diagram1, diagram2, e=None):
63
    """
64
    Compute bottleneck distance between persistence diagrams.
65
    
66
    Parameters:
67
    - diagram1: First persistence diagram
68
    - diagram2: Second persistence diagram
69
    - e: Approximation factor (None for exact computation)
70
    
71
    Returns:
72
    float: Bottleneck distance
73
    """
74

75
def wasserstein_distance(diagram1, diagram2, order: int = 1, internal_p: int = 2):
76
    """
77
    Compute Wasserstein distance between persistence diagrams.
78
    
79
    Parameters:
80
    - diagram1: First persistence diagram
81
    - diagram2: Second persistence diagram
82
    - order: Wasserstein order (1 or 2)
83
    - internal_p: Internal Lp norm parameter
84
    
85
    Returns:
86
    float: Wasserstein distance
87
    """
88

89
def wasserstein_barycenter(diagrams, weights=None, method="lp", reg=None):
90
    """
91
    Compute Wasserstein barycenter of persistence diagrams.
92
    
93
    Parameters:
94
    - diagrams: List of persistence diagrams
95
    - weights: Weights for each diagram
96
    - method: Computation method ("lp" or "hera")
97
    - reg: Regularization parameter
98
    
99
    Returns:
100
    array: Barycenter persistence diagram
101
    """
102
```
103

104
### Persistence Intervals Analysis
105

106
Functions for extracting and analyzing persistence intervals by dimension and other criteria.
107

108
```python { .api }
109
def persistence_intervals_in_dimension(persistence, dimension: int):
110
    """
111
    Extract persistence intervals for specific dimension.
112
    
113
    Parameters:
114
    - persistence: List of persistence pairs
115
    - dimension: Homology dimension
116
    
117
    Returns:
118
    array: Persistence intervals (birth, death) pairs
119
    """
120

121
def persistence_intervals_grouped_by_dimension(persistence):
122
    """
123
    Group persistence intervals by dimension.
124
    
125
    Parameters:
126
    - persistence: List of persistence pairs
127
    
128
    Returns:
129
    dict: Dictionary mapping dimensions to interval lists
130
    """
131
```
132

133
### Statistical Analysis
134

135
Functions for computing topological summaries and statistical descriptors of persistence diagrams.
136

137
```python { .api }
138
def betti_numbers(persistence, dimension: int):
139
    """
140
    Compute Betti numbers from persistence data.
141
    
142
    Parameters:
143
    - persistence: List of persistence pairs
144
    - dimension: Maximum dimension to consider
145
    
146
    Returns:
147
    list: Betti numbers for each dimension
148
    """
149

150
def persistent_betti_numbers(persistence, from_value: float, to_value: float):
151
    """
152
    Compute persistent Betti numbers within filtration range.
153
    
154
    Parameters:
155
    - persistence: List of persistence pairs
156
    - from_value: Start of filtration range
157
    - to_value: End of filtration range
158
    
159
    Returns:
160
    list: Persistent Betti numbers
161
    """
162
```
163

164
## Wasserstein Module
165

166
Specialized module for efficient Wasserstein distance computations and barycenter calculations.
167

168
```python { .api }
169
# From gudhi.wasserstein module
170
def wasserstein_distance(X, Y, order=1, internal_p=2):
171
    """
172
    Optimized Wasserstein distance computation.
173
    
174
    Parameters:
175
    - X: First persistence diagram
176
    - Y: Second persistence diagram  
177
    - order: Wasserstein order
178
    - internal_p: Internal metric parameter
179
    
180
    Returns:
181
    float: Wasserstein distance
182
    """
183

184
def wasserstein_barycenter(pdiagset, weights=None, method="lp", reg=None):
185
    """
186
    Compute Wasserstein barycenter using specialized algorithms.
187
    
188
    Parameters:
189
    - pdiagset: Set of persistence diagrams
190
    - weights: Optional weights for each diagram
191
    - method: Algorithm choice ("lp", "hera")
192
    - reg: Regularization parameter
193
    
194
    Returns:
195
    array: Barycenter diagram
196
    """
197
```
198

199
## Hera Integration
200

201
High-performance distance computations using the Hera library for improved efficiency on large datasets.
202

203
```python { .api }
204
# From gudhi.hera module
205
def bottleneck_distance(X, Y, delta=0.01):
206
    """
207
    Fast bottleneck distance using Hera library.
208
    
209
    Parameters:
210
    - X: First persistence diagram
211
    - Y: Second persistence diagram
212
    - delta: Approximation precision
213
    
214
    Returns:
215
    float: Bottleneck distance
216
    """
217

218
def wasserstein_distance(X, Y, order=1, delta=0.01):
219
    """
220
    Fast Wasserstein distance using Hera library.
221
    
222
    Parameters:
223
    - X: First persistence diagram
224
    - Y: Second persistence diagram
225
    - order: Wasserstein order
226
    - delta: Approximation precision
227
    
228
    Returns:
229
    float: Wasserstein distance
230
    """
231
```
232

233
## Usage Examples
234

235
### Basic Persistence Visualization
236

237
```python
238
import gudhi
239
import numpy as np
240

241
# Create complex and compute persistence
242
points = np.random.random((50, 2))
243
rips = gudhi.RipsComplex(points=points, max_edge_length=0.3)
244
st = rips.create_simplex_tree(max_dimension=1)
245
persistence = st.persistence()
246

247
# Plot persistence diagram
248
gudhi.plot_persistence_diagram(persistence)
249

250
# Plot barcode
251
gudhi.plot_persistence_barcode(persistence)
252
```
253

254
### Distance Computations
255

256
```python
257
import gudhi
258

259
# Compute two persistence diagrams
260
# ... (construct persistence1 and persistence2)
261

262
# Compute bottleneck distance
263
bottleneck_dist = gudhi.bottleneck_distance(persistence1, persistence2)
264

265
# Compute Wasserstein distance
266
wasserstein_dist = gudhi.wasserstein_distance(persistence1, persistence2, order=2)
267

268
print(f"Bottleneck distance: {bottleneck_dist}")
269
print(f"Wasserstein distance: {wasserstein_dist}")
270
```
271

272
### Statistical Analysis
273

274
```python
275
import gudhi
276

277
# Analyze persistence intervals
278
intervals_0d = gudhi.persistence_intervals_in_dimension(persistence, 0)
279
intervals_1d = gudhi.persistence_intervals_in_dimension(persistence, 1)
280

281
# Compute Betti numbers
282
betti = st.betti_numbers()
283
print(f"Betti numbers: {betti}")
284

285
# Compute persistent Betti numbers in range
286
persistent_betti = st.persistent_betti_numbers(0.1, 0.5)
287
print(f"Persistent Betti numbers: {persistent_betti}")
288
```
289

290
### Barycenter Computation
291

292
```python
293
import gudhi
294
import numpy as np
295

296
# Collect multiple persistence diagrams
297
diagrams = []
298
for i in range(10):
299
    points = np.random.random((30, 2))
300
    rips = gudhi.RipsComplex(points=points, max_edge_length=0.3)
301
    st = rips.create_simplex_tree(max_dimension=1)
302
    persistence = st.persistence()
303
    # Extract 1D intervals
304
    intervals = gudhi.persistence_intervals_in_dimension(persistence, 1)
305
    diagrams.append(intervals)
306

307
# Compute barycenter
308
barycenter = gudhi.wasserstein_barycenter(diagrams)
309
print(f"Barycenter diagram shape: {barycenter.shape}")
310
```