DOCSEARCHbyAlgolia
Submit Docs

GUDHI: Geometry Understanding for Data Analysis

repository·master·Indexed 43 days ago

https://github.com/gudhi/gudhi-devel

An open-source C++ library with a Python interface for Computational Topology and Topological Data Analysis (TDA). GUDHI provides data structures and algorithms for constructing simplicial complexes—including Alpha, Čech, Rips, and cubical complexes—and computing persistent homology. Version 3.14.0a0 includes CLI tools for computing persistence diagrams and Bottleneck distance.

Tokens
42.5K
Snippets
127
Records
197
Agent score
55%

What's inside GUDHI

  1. Overview of the GUDHI library

    master
    GUDHI is an open-source C++ library with a Python interface designed for Topological Data Analysis (TDA) and Higher Dimensional Geometry Understanding. It provides state-of-the-art data structures and algorithms for constructing simplicial complexes and computing persistent homology.

  2. Overview of the GUDHI library capabilities

    master

    GUDHI is an open-source library designed for Computational Topology and Topological Data Analysis (TDA). It provides algorithms for constructing simplicial complexes, data structures for representing them, and tools for computing geometric approximations and persistent homology.

    Key functional modules include:

    • Complexes:
      • Cubical complexes.
      • Simplicial complexes (Rips, Witness, Alpha, and Čech).
      • Cover complexes (Nerve and Graph induced).
    • Data structures and basic operations: Simplex tree, Skeleton blockers, Toplex map, and operations for construction, update, filtration, and simplification.
    • Topological descriptors computation and Manifold reconstruction.
    • Topological descriptors tools: Bottleneck distance, Statistical tools, and Persistence diagrams/barcodes.

  3. Explore GUDHI representations submodules

    master

    The gudhi.representations module is organized into several functional submodules:

    • gudhi.representations.preprocessing: Contains tools for preparing diagrams (e.g., Clamping).
    • gudhi.representations.vector_methods: Implements methods to convert diagrams into Euclidean vectors.
    • gudhi.representations.kernel_methods: Implements kernel functions to compute similarity between diagrams.
    • gudhi.representations.metrics: Implements distance metrics for comparing persistence diagrams.

  4. What is a Tangential Delaunay complex?

    master

    A Tangential Delaunay complex is a simplicial complex used to reconstruct a $k$-dimensional smooth manifold embedded in $d$-dimensional Euclidean space. It is particularly useful when the input is a point sample from an unknown manifold where points lie close to a structure of a smaller intrinsic dimension.

    Key Characteristics:

    • Complexity: The running time scales linearly with the extrinsic dimension $d$ and exponentially with the intrinsic dimension $k$.
    • Mechanism: For each point, a tangent subspace is estimated using PCA. The complex is formed by the union of the 'stars' of each point within its local $k$-dimensional regular triangulation restricted to that tangent subspace.
    • Output: The result is exported as a gudhi.SimplexTree.

  5. Edge collapse for flag filtrations

    master

    Edge collapse reduces any flag filtration to a smaller flag filtration with the same persistence, using only the 1-skeletons of a simplicial complex. The reduction is exact, and the persistent homology of the reduced sequence is identical to the input sequence. This method is highly efficient for computing persistent homology of filtered flag complexes.

    Introduced in GUDHI 3.3.0 under the MIT license.

  6. Use the ToMATo clustering algorithm

    master

    ToMATo (Topological Mode Analysis Tool) is a persistence-based clustering algorithm implemented in GUDHI. It works in three main phases:

    1. Density Estimation: Uses a density estimator and a neighborhood graph.
    2. Mode-seeking: Performs naive hill-climbing to build initial clusters.
    3. Merging: Merges clusters based on their prominence.

    You can control the final number of clusters by setting the n_clusters_ attribute after fitting the model. Alternatively, you can control the merging phase via a prominence threshold. Decreasing the prominence threshold creates a hierarchy of clusters.

    As a byproduct, the algorithm produces a persistence diagram of the merge tree, which helps visualize how many clusters are statistically significant (points far from the diagonal represent prominent clusters).

    from gudhi.clustering.tomato import Tomato

t = Tomato()
t.fit(data)
# Access the number of initial clusters found
print(t.n_clusters_)
# Set the desired number of clusters
t.n_clusters_ = 2

  7. Choose between CubicalComplex and CubicalPersistence for homology

    master

    When working with cubical complexes in GUDHI, your choice of class depends on your primary goal:

    1. If you only need to compute persistent homology: Use gudhi.sklearn.CubicalPersistence. This is often significantly faster than using the standard CubicalComplex class for this specific task.
    2. If you need full cubical complex functionality: Use gudhi.CubicalComplex to access the full suite of cubical complex operations beyond just persistent homology.

  8. Choose between CoverComplex and scikit-learn style cover complex classes

    master

    GUDHI provides two ways to compute cover complexes (Nerve, Graph Induced, and Mapper complexes):

    1. scikit-learn style classes (gudhi.cover_complex.NerveComplex, gudhi.cover_complex.GraphInducedComplex, and gudhi.cover_complex.MapperComplex):

      • These follow the scikit-learn API pattern.
      • Inputs must be stored in memory.
      • Use these when you want to integrate with scikit-learn workflows.

    2. gudhi.CoverComplex class:

      • More flexible for input types (e.g., it can read inputs from file paths).
      • Only computes Nerve and Graph Induced complexes (does not support Mapper complexes).

    Key Differences in Complex Types

    • MapperComplex: Nodes are defined by a clustering method. Supports resolutions and gains of any length. Accepts functional covers (preimages of filter functions).
    • GraphInducedComplex (GIC): Nodes are defined by an input graph. Accepts partitions instead of covers. If the cover is functional, GIC only accepts one scalar-valued filter with gain < 0.5.
    • NerveComplex: Nodes are defined by cover elements. Requires cover elements to overlap.

  10. Cover Complexes

    master

    Cover complexes, such as Nerves and Graph Induced Complexes, are simplicial complexes that contain topological information about the input data. They are computed using a cover of the data, such as the preimage of a family of intervals covering the image of a scalar-valued function.

    Requirements:

    • cgal

    License: MIT (GPL v3)

  12. Skeleton blocker

    master

    The Skeleton-Blocker data structure provides a light encoding for simplicial complexes by storing an implicit representation. It primarily stores the 1-skeleton (a graph) and a small set of 'missing faces'.

    It supports operations like simplex enumeration and removal, but is particularly efficient for operations that do not require full enumeration, such as:

    • Edge iteration
    • Link computation
    • Simplex contraction

    Introduced in GUDHI 1.1.0 under the MIT license.