persistent_homology: Persistent Homology

In Nestimate: Network Estimation, Bootstrap, and Higher-Order Analysis

Persistent Homology

Description

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
)

Arguments

x	A square matrix, tna, or netobject. For type = "vr", must be a non-negative distance matrix.
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).

Value

A persistent_homology object with:

betti_curve

Data frame: threshold, dimension, betti.

persistence

Data frame of birth-death pairs: dimension, birth, death, persistence. Sorted by descending persistence.

thresholds

Numeric vector of grid thresholds.

mode

Either "clique" or "vr".

References

Edelsbrunner, H., Letscher, D., & Zomorodian, A. (2000). Topological persistence and simplification. Discrete & Computational Geometry 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)

Nestimate documentation built on July 11, 2026, 1:09 a.m.