tessl/pypi-gudhi
Computational topology and topological data analysis library providing state-of-the-art algorithms for constructing simplicial complexes and computing persistent homology
—
Pending
persistent-homology.mddocs/
Persistent Homology
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.
Capabilities
Persistence Visualization
Functions for creating visual representations of persistent homology results including persistence diagrams, barcodes, and density plots.
def plot_persistence_diagram(persistence, **kwargs):
"""
Plot persistence diagram.
Parameters:
- persistence: List of persistence pairs
- alpha: Transparency level (0-1)
- band: Width of confidence band
- max_plots: Maximum number of plots
- inf_delta: Shift for infinite persistence points
- legend: Whether to show legend
- colormap: Matplotlib colormap name
- axes: Matplotlib axes object
- fontsize: Font size for labels
"""
def plot_persistence_barcode(persistence, **kwargs):
"""
Plot persistence barcode.
Parameters:
- persistence: List of persistence pairs
- alpha: Transparency level (0-1)
- max_intervals: Maximum number of intervals to plot
- inf_delta: Shift for infinite persistence points
- legend: Whether to show legend
- colormap: Matplotlib colormap name
- axes: Matplotlib axes object
- fontsize: Font size for labels
"""
def plot_persistence_density(persistence, **kwargs):
"""
Plot persistence density.
Parameters:
- persistence: List of persistence pairs
- dimension: Dimension to plot (None for all)
- max_intervals: Maximum number of intervals
- nbins: Number of bins for density estimation
- bw_method: Bandwidth selection method
- colormap: Matplotlib colormap name
- axes: Matplotlib axes object
"""Distance Computations
Functions for computing distances between persistence diagrams, essential for statistical analysis and machine learning applications.
def bottleneck_distance(diagram1, diagram2, e=None):
"""
Compute bottleneck distance between persistence diagrams.
Parameters:
- diagram1: First persistence diagram
- diagram2: Second persistence diagram
- e: Approximation factor (None for exact computation)
Returns:
float: Bottleneck distance
"""
def wasserstein_distance(diagram1, diagram2, order: int = 1, internal_p: int = 2):
"""
Compute Wasserstein distance between persistence diagrams.
Parameters:
- diagram1: First persistence diagram
- diagram2: Second persistence diagram
- order: Wasserstein order (1 or 2)
- internal_p: Internal Lp norm parameter
Returns:
float: Wasserstein distance
"""
def wasserstein_barycenter(diagrams, weights=None, method="lp", reg=None):
"""
Compute Wasserstein barycenter of persistence diagrams.
Parameters:
- diagrams: List of persistence diagrams
- weights: Weights for each diagram
- method: Computation method ("lp" or "hera")
- reg: Regularization parameter
Returns:
array: Barycenter persistence diagram
"""Persistence Intervals Analysis
Functions for extracting and analyzing persistence intervals by dimension and other criteria.
def persistence_intervals_in_dimension(persistence, dimension: int):
"""
Extract persistence intervals for specific dimension.
Parameters:
- persistence: List of persistence pairs
- dimension: Homology dimension
Returns:
array: Persistence intervals (birth, death) pairs
"""
def persistence_intervals_grouped_by_dimension(persistence):
"""
Group persistence intervals by dimension.
Parameters:
- persistence: List of persistence pairs
Returns:
dict: Dictionary mapping dimensions to interval lists
"""Statistical Analysis
Functions for computing topological summaries and statistical descriptors of persistence diagrams.
def betti_numbers(persistence, dimension: int):
"""
Compute Betti numbers from persistence data.
Parameters:
- persistence: List of persistence pairs
- dimension: Maximum dimension to consider
Returns:
list: Betti numbers for each dimension
"""
def persistent_betti_numbers(persistence, from_value: float, to_value: float):
"""
Compute persistent Betti numbers within filtration range.
Parameters:
- persistence: List of persistence pairs
- from_value: Start of filtration range
- to_value: End of filtration range
Returns:
list: Persistent Betti numbers
"""Wasserstein Module
Specialized module for efficient Wasserstein distance computations and barycenter calculations.
# From gudhi.wasserstein module
def wasserstein_distance(X, Y, order=1, internal_p=2):
"""
Optimized Wasserstein distance computation.
Parameters:
- X: First persistence diagram
- Y: Second persistence diagram
- order: Wasserstein order
- internal_p: Internal metric parameter
Returns:
float: Wasserstein distance
"""
def wasserstein_barycenter(pdiagset, weights=None, method="lp", reg=None):
"""
Compute Wasserstein barycenter using specialized algorithms.
Parameters:
- pdiagset: Set of persistence diagrams
- weights: Optional weights for each diagram
- method: Algorithm choice ("lp", "hera")
- reg: Regularization parameter
Returns:
array: Barycenter diagram
"""Hera Integration
High-performance distance computations using the Hera library for improved efficiency on large datasets.
# From gudhi.hera module
def bottleneck_distance(X, Y, delta=0.01):
"""
Fast bottleneck distance using Hera library.
Parameters:
- X: First persistence diagram
- Y: Second persistence diagram
- delta: Approximation precision
Returns:
float: Bottleneck distance
"""
def wasserstein_distance(X, Y, order=1, delta=0.01):
"""
Fast Wasserstein distance using Hera library.
Parameters:
- X: First persistence diagram
- Y: Second persistence diagram
- order: Wasserstein order
- delta: Approximation precision
Returns:
float: Wasserstein distance
"""Usage Examples
Basic Persistence Visualization
import gudhi
import numpy as np
# Create complex and compute persistence
points = np.random.random((50, 2))
rips = gudhi.RipsComplex(points=points, max_edge_length=0.3)
st = rips.create_simplex_tree(max_dimension=1)
persistence = st.persistence()
# Plot persistence diagram
gudhi.plot_persistence_diagram(persistence)
# Plot barcode
gudhi.plot_persistence_barcode(persistence)Distance Computations
import gudhi
# Compute two persistence diagrams
# ... (construct persistence1 and persistence2)
# Compute bottleneck distance
bottleneck_dist = gudhi.bottleneck_distance(persistence1, persistence2)
# Compute Wasserstein distance
wasserstein_dist = gudhi.wasserstein_distance(persistence1, persistence2, order=2)
print(f"Bottleneck distance: {bottleneck_dist}")
print(f"Wasserstein distance: {wasserstein_dist}")Statistical Analysis
import gudhi
# Analyze persistence intervals
intervals_0d = gudhi.persistence_intervals_in_dimension(persistence, 0)
intervals_1d = gudhi.persistence_intervals_in_dimension(persistence, 1)
# Compute Betti numbers
betti = st.betti_numbers()
print(f"Betti numbers: {betti}")
# Compute persistent Betti numbers in range
persistent_betti = st.persistent_betti_numbers(0.1, 0.5)
print(f"Persistent Betti numbers: {persistent_betti}")Barycenter Computation
import gudhi
import numpy as np
# Collect multiple persistence diagrams
diagrams = []
for i in range(10):
points = np.random.random((30, 2))
rips = gudhi.RipsComplex(points=points, max_edge_length=0.3)
st = rips.create_simplex_tree(max_dimension=1)
persistence = st.persistence()
# Extract 1D intervals
intervals = gudhi.persistence_intervals_in_dimension(persistence, 1)
diagrams.append(intervals)
# Compute barycenter
barycenter = gudhi.wasserstein_barycenter(diagrams)
print(f"Barycenter diagram shape: {barycenter.shape}")Install with Tessl CLI
npx tessl i tessl/pypi-gudhi