Persistent Homology

Computes persistent homology via full boundary-matrix reduction over \(\mathbb{Z}/2\) (Edelsbrunner, Letscher & Zomorodian 2000). The returned persistence diagram pairs each k-dimensional homology class to the simplex whose addition creates it (birth) and the simplex whose addition destroys it (death). Essential classes - those never killed - are reported with death = 0 in clique mode (similarity scale, descending) and death = Inf in VR mode (distance scale, ascending).

Two filtration modes are supported:

type = "clique"

Weighted clique filtration. Input is treated as a similarity matrix; high-weight simplices appear early. For each k-simplex \(\sigma\), the filtration value is \(\min_{(i,j) \in \sigma}\,|w(i,j)|\). Thresholds run high to low.

type = "vr"

Vietoris-Rips filtration on a non-negative distance matrix. For each k-simplex \(\sigma\), the filtration value is \(\max_{(i,j) \in \sigma}\,d(i,j)\). Thresholds run low to high. Use max_scale to cap the filtration diameter.

Usage

persistent_homology(
  x,
  n_steps = 20L,
  max_dim = 3L,
  type = "clique",
  max_scale = NULL
)

# S3 method for class 'persistent_homology'
print(x, ...)

# S3 method for class 'persistent_homology'
plot(x, combined = TRUE, ...)

Arguments

x

A square matrix, tna, or netobject. For type = "vr", must be a non-negative distance matrix. A simplicial_complex carrying a $filtration vector (as returned by build_simplicial(type = "vr")) is also accepted and is used directly: its stored filtration values are reduced as they are, so type is taken from the complex rather than this argument. For the print() and plot() methods: an object of class persistent_homology.

n_steps

Number of grid points for the reported Betti curve (default 20). The persistence diagram itself is exact - it does not depend on n_steps.

max_dim

Maximum simplex dimension to track (default 3).

type

Filtration: "clique" (default, similarity-weighted) or "vr" (Vietoris-Rips on distances).

max_scale

For type = "vr" only: cap on edge length. Edges with d(i,j) > max_scale are excluded. NULL (default) uses max(d).

...

In plot.persistent_homology(): Ignored. In print.persistent_homology(): Additional arguments (unused).

combined

When TRUE (default), the two panels are stitched side-by-side via gridExtra::arrangeGrob. When FALSE, returns a named list (betti_curve, persistence) of ggplots.

Value

A persistent_homology object with:

betti_curve

Data frame: threshold, dimension, betti.

persistence

Data frame of birth-death pairs, one row per homology class: dimension, birth, death, persistence. Sorted by descending persistence. Essential classes are included, with death = 0 and persistence = birth in clique mode, and death = Inf, persistence = Inf in VR mode (the plot method caps those for display only).

thresholds

Numeric vector of grid thresholds.

mode

Either "clique" or "vr".

In print.persistent_homology(): The input object, invisibly.

In plot.persistent_homology(): A grid grob (invisibly) when combined = TRUE; a named list of two ggplots when combined = FALSE.

Methods

• plot.persistent_homology(): Two panels: Betti curve (threshold vs Betti number) and persistence diagram (birth vs death). Persistence pairs come from full boundary- matrix reduction; essential classes are shown at the filtration boundary (death = 0 in clique mode; in VR mode their stored death = Inf is capped for display at the largest finite value in the diagram or on the threshold grid, so they still render).

References

Edelsbrunner, H., Letscher, D., & Zomorodian, A. (2000). Topological persistence and simplification. In Proceedings of the 41st Annual Symposium on Foundations of Computer Science, 454-463. Journal version: Discrete & Computational Geometry (2002) 28, 511-533.

Examples

mat <- matrix(c(0,.6,.5,.6,0,.4,.5,.4,0), 3, 3)
colnames(mat) <- rownames(mat) <- c("A","B","C")
ph <- persistent_homology(mat, n_steps = 10)
print(ph)
#> Persistent Homology
#>   10 filtration steps [0.6000 → 0.0060]
#>   Features: b0: 2 (1 persistent) 
#>   Longest-lived:
#>     b0: 0.6000 → 0.0000 (life: 0.6000)
#>     b0: 0.6000 → 0.5000 (life: 0.1000)