build_simplicial: Build a Simplicial Complex

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

Build a Simplicial Complex

Description

Constructs a simplicial complex from a network or higher-order pathway object. Two construction methods are available:

• Clique complex ("clique"): every clique in the thresholded non-zero graph becomes a simplex. Edges with absolute weight \geq threshold are retained. The standard bridge from graph theory to algebraic topology.

• Pathway complex ("pathway"): each higher-order pathway from a net_hon or net_hypa becomes a simplex.

For type = "vr" (or alias "rips"), the input is treated as a non-negative distance / dissimilarity matrix and a Vietoris-Rips filtration is constructed: each k-simplex \sigma enters at \max_{(i,j) \in \sigma} d(i,j). Use max_scale to cap the filtration diameter; edges with d(i,j) > max_scale are excluded. Filtration values are attached as $filtration on the returned object so persistent_homology() can read them directly.

Usage

build_simplicial(
  x,
  type = "clique",
  threshold = 0,
  max_dim = 10L,
  max_pathways = NULL,
  anomaly = c("all", "over", "under"),
  max_scale = NULL,
  ...
)

Arguments

x	A square matrix, tna, netobject, net_hon, net_hypa, or net_mogen.
type	Construction type: "clique" (default), "pathway", or "vr" (alias "rips").
threshold	For type = "clique": minimum non-zero absolute edge weight to include an edge (default 0). Edges below this are ignored; zero-weight non-edges are never included. Ignored for type = "vr" - use max_scale instead.
max_dim	Maximum simplex dimension (default 10). Must be a single non-negative integer. A k-simplex has k+1 nodes.
max_pathways	For type = "pathway": maximum number of pathways to include, ranked by count (HON) or ratio (HYPA). NULL includes all. Default NULL.
anomaly	For HYPA pathway complexes, which anomaly direction to include: "all" (default), "over", or "under". Under-represented HYPA paths are ranked by smallest observed/expected ratio; over-represented paths are ranked by largest ratio.
max_scale	For type = "vr": maximum edge length to include in the filtration. NULL (default) uses max(d).
...	Additional arguments passed to build_hon() when x is a tna/netobject with type = "pathway".

Value

A simplicial_complex object. For type = "vr" an additional $filtration numeric vector is attached (parallel to $simplices).

See Also

betti_numbers, persistent_homology, simplicial_degree, q_analysis

Examples

mat <- matrix(c(0,.6,.5,.6,0,.4,.5,.4,0), 3, 3)
colnames(mat) <- rownames(mat) <- c("A","B","C")
sc <- build_simplicial(mat, threshold = 0.3)
print(sc)
betti_numbers(sc)

# Vietoris-Rips on a distance matrix:
d <- 1 - mat
diag(d) <- 0
sc_vr <- build_simplicial(d, type = "vr", max_scale = 0.6)

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