att.topology

Persistent homology computation and topological summaries.

class att.topology.PersistenceAnalyzer(max_dim=2, backend='ripser', use_witness=False, n_landmarks=500, metric='euclidean')

Bases: object

Compute persistent homology on point clouds.

Parameters:

• max_dim (int) – Max homology dimension (0=components, 1=loops, 2=voids).

• backend (str) – “ripser” (fast for H0+H1) or “gudhi” (H2+, alpha complexes).

• use_witness (bool) – Use witness complex for large point clouds (n > 2000).

• n_landmarks (int) – Number of landmarks for witness complex.

• metric (str)

fit_transform(cloud, subsample=None, seed=None, min_effective_dim=5)

Compute persistence diagrams and derived representations.

Parameters:

• cloud ((n_points, dimension) point cloud)

• subsample (if int, randomly select this many points first)

• seed (random seed for subsampling)

• min_effective_dim (int)

Returns:

• dict with diagrams, betti_curves, persistence_entropy,

• bottleneck_norms, persistence_images, persistence_landscapes

Return type:

dict

distance(other, metric='bottleneck')

Compute distance between persistence diagrams.

Parameters:

• other (another PersistenceAnalyzer with computed diagrams)

• metric ("bottleneck", "wasserstein_1", "wasserstein_2")

Returns:

float

Return type:

maximum distance across all dimensions

to_image(resolution=50, sigma=0.1, birth_range=None, persistence_range=None)

Convert diagrams to persistence images.

Parameters:

• resolution (int) – Grid size for the persistence image (resolution x resolution).

• sigma (float) – Gaussian kernel bandwidth.

• birth_range ((min, max) or None) – Explicit birth-axis range. If None, computed from data per diagram.

• persistence_range ((min, max) or None) – Explicit persistence-axis range. If None, computed from data per diagram.

Return type:

list of (resolution, resolution) arrays, one per homology dimension.

to_landscape(n_layers=5, n_grid=100)

Convert diagrams to persistence landscapes.

Returns one (n_layers, n_grid) array per homology dimension.

Parameters:

• n_layers (int)

• n_grid (int)

Return type:

list[ndarray]

plot(kind='diagram')

Plot persistence results.

kind: ‘diagram’, ‘barcode’, ‘betti_curve’, ‘landscape’, ‘image’

Parameters:

kind (str)

exception att.topology.TopologyDimensionalityWarning

Bases: UserWarning

Issued when point cloud effective rank is below minimum for stable PH.

att.topology.knn_graph_laplacian(cloud, k=15, symmetrize='or')

Build the graph Laplacian from a kNN adjacency graph.

Parameters:

• cloud ((n, d) point cloud.)

• k (int) – Number of nearest neighbours (excluding self).

• symmetrize (str) – “or” (union — default) or “and” (intersection) for making the directed kNN graph undirected.

Returns:

L – semi-definite.

Return type:

(n, n) sparse CSR Laplacian (L = D - W), symmetric positive

att.topology.spectral_distance_matrix(cloud, k=15, n_eigenvectors=None)

Compute effective-resistance distance matrix from kNN graph Laplacian.

The effective resistance between nodes i and j is:

R(i,j) = (e_i - e_j)^T L^+ (e_i - e_j)

which can be computed efficiently via the spectral decomposition of L.

Parameters:

• cloud ((n, d) point cloud.)

• k (int) – Number of nearest neighbours for the graph.

• n_eigenvectors (int or None) – Number of Laplacian eigenvectors to use (truncated approximation). None = use min(n-1, 100).

Returns:

D

Return type:

(n, n) symmetric distance matrix with zero diagonal.

class att.topology.PersistenceAnalyzer(max_dim=2, backend='ripser', use_witness=False, n_landmarks=500, metric='euclidean')

Bases: object

Compute persistent homology on point clouds.

Parameters:

• max_dim (int) – Max homology dimension (0=components, 1=loops, 2=voids).

• backend (str) – “ripser” (fast for H0+H1) or “gudhi” (H2+, alpha complexes).

• use_witness (bool) – Use witness complex for large point clouds (n > 2000).

• n_landmarks (int) – Number of landmarks for witness complex.

• metric (str)

__init__(max_dim=2, backend='ripser', use_witness=False, n_landmarks=500, metric='euclidean')

Parameters:

• max_dim (int)

• backend (str)

• use_witness (bool)

• n_landmarks (int)

• metric (str)

fit_transform(cloud, subsample=None, seed=None, min_effective_dim=5)

Compute persistence diagrams and derived representations.

Parameters:

• cloud ((n_points, dimension) point cloud)

• subsample (if int, randomly select this many points first)

• seed (random seed for subsampling)

• min_effective_dim (int)

Returns:

• dict with diagrams, betti_curves, persistence_entropy,

• bottleneck_norms, persistence_images, persistence_landscapes

Return type:

dict

distance(other, metric='bottleneck')

Compute distance between persistence diagrams.

Parameters:

• other (another PersistenceAnalyzer with computed diagrams)

• metric ("bottleneck", "wasserstein_1", "wasserstein_2")

Returns:

float

Return type:

maximum distance across all dimensions

to_image(resolution=50, sigma=0.1, birth_range=None, persistence_range=None)

Convert diagrams to persistence images.

Parameters:

• resolution (int) – Grid size for the persistence image (resolution x resolution).

• sigma (float) – Gaussian kernel bandwidth.

• birth_range ((min, max) or None) – Explicit birth-axis range. If None, computed from data per diagram.

• persistence_range ((min, max) or None) – Explicit persistence-axis range. If None, computed from data per diagram.

Return type:

list of (resolution, resolution) arrays, one per homology dimension.

to_landscape(n_layers=5, n_grid=100)

Convert diagrams to persistence landscapes.

Returns one (n_layers, n_grid) array per homology dimension.

Parameters:

• n_layers (int)

• n_grid (int)

Return type:

list[ndarray]

plot(kind='diagram')

Plot persistence results.

kind: ‘diagram’, ‘barcode’, ‘betti_curve’, ‘landscape’, ‘image’

Parameters:

kind (str)