Package {SimplicialComplex}

Type: Package
Title: Topological Data Analysis: Simplicial Complex
Version: 0.1.1
Maintainer: ChiChien Wang <kennywang2003@gmail.com>
Description: Provides an implementation of simplicial complexes for Topological Data Analysis (TDA). The package includes functions to compute faces, boundary operators, Betti numbers, Euler characteristic, and to construct simplicial complexes. It also implements persistent homology, from building filtrations to computing persistence diagrams, with the aim of helping readers understand the core concepts of computational topology. Methods are based on standard references in persistent homology such as Zomorodian and Carlsson (2005) <doi:10.1007/s00454-004-1146-y> and Chazal and Michel (2021) <doi:10.3389/frai.2021.667963>.
Imports: Matrix, gtools, igraph, ggplot2, geometry, RANN
License: MIT + file LICENSE
URL: https://github.com/TDA-R/SimplicialComplex
BugReports: https://github.com/TDA-R/SimplicialComplex/issues
Encoding: UTF-8
RoxygenNote: 7.3.2
Suggests: testthat (≥ 3.0.0), torch
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-07-16 14:30:54 UTC; wangqiqian
Author: ChiChien Wang [aut, cre, trl]
Repository: CRAN
Date/Publication: 2026-07-16 15:10:02 UTC

Construct a Vietoris–Rips Complex (1-skeleton + maximal simplices)

Description

Construct a Vietoris–Rips Complex (1-skeleton + maximal simplices)

Usage

VietorisRipsComplex(points, epsilon)

Arguments

points

A numeric matrix or data.frame with one point per row (columns are coordinates).

epsilon

A positive numeric threshold; connect points with distance < \epsilon.

Details

The Vietoris–Rips complex at scale \epsilon includes a simplex for every finite set of points with pairwise distances < \epsilon. This function constructs the 1-skeleton (edges only) and then uses maximal cliques in that graph as the maximal simplices.

Value

A list with:

network

An igraph object representing the 1-skeleton.

simplices

A list of integer vectors, each the vertex indices of a maximal simplex.

Examples

points <- matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2)
epsilon <- 1.5
vr_complex <- VietorisRipsComplex(points, epsilon)

Compute Euler characteristic for an abstract simplicial complex

Description

Compute Euler characteristic for an abstract simplicial complex

Usage

abstract_simplicial_complex(simplices, dimension, tol = NULL)

Arguments

simplices

A list of simplices (each a numeric vector).

dimension

Optional max dimension to compute up to.

tol

Optional numerical tolerance to pass to rankMatrix().

Value

The Euler characteristic \chi.

Examples

simplices <- list(c(1, 2), c(3, 4), c(2, 1, 3), c(4, 2))
abstract_simplicial_complex(simplices, 2)

Convert a flood_complex object to a filtration list

Description

Convert a flood_complex object to a filtration list

Usage

as_filtration(fc)

Arguments

fc

A "flood_complex" object.

Value

A filtration list compatible with boundary_info.

Safely compute the rank of a sparse matrix

Description

This helper function wraps Matrix::rankMatrix() to safely handle empty matrices (i.e., with 0 rows or columns).

Usage

betti_number(simplices, bound_dim, tol = NULL)

Arguments

simplices

A list of simplices representing the simplicial complex.

bound_dim

The dimension of the boundary to compute the Betti number for.

tol

Optional numerical tolerance to pass to rankMatrix().

Value

An integer representing the rank of the matrix.

Examples

simplices <- list(c(1, 2), c(3, 4), c(2, 1, 3), c(4, 2))
betti_number(simplices, 0, tol=0.1)

Compute the boundary operator for a simplicial complex

Description

Compute the boundary operator for a simplicial complex

Usage

boundary(simplices, bound_dim)

Arguments

simplices

A list of simplices (each a numeric vector).

bound_dim

The dimension k of the boundary operator \partial_{k}.

Details

\partial_k \sigma = \sum_i (-1)^i [v_0 v_1 \ldots \hat{v}_i \ldots v_k]

Value

A sparse matrix representing \partial_{k}.

Examples

simplices <- list(c(1, 2), c(3, 4), c(2, 1, 3), c(4, 2))
boundary(simplices, 0)

Get the boundary matrix and its reduction information in matrix form

Description

Get the boundary matrix and its reduction information in matrix form

Usage

boundary_info(filist)

Arguments

filist

Filtration list, each element includes simplex and time.

Value

A list containing the boundary matrix, the last boundary row, and the pivot owner for persistence extraction.

Examples

points <- matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2)
filtration <- build_vr_filtration(points, eps_max=1.2)
res <- boundary_info(filtration)

Flood filtration in SimplicialComplex format

Description

Wraps flood_complex and returns the filtration in the same format as build_vr_filtration: a list of list(simplex = <integer vector>, t = <numeric>), sorted by (time, dimension, lexicographic order). The result plugs directly into boundary_info() / extract_persistence_pairs() / plot_persistence(), as well as into the faster flood_persistence.

Usage

build_flood_filtration(points, landmarks, ...)

Arguments

points

A numeric matrix (N x d) point cloud.

landmarks

Number of FPS landmarks, or an explicit landmark matrix.

...

Passed on to flood_complex.

Value

A filtration list compatible with boundary_info.

Examples

## Not run: 
pts <- matrix(rnorm(2000), ncol = 2)
filtration <- build_flood_filtration(pts, landmarks = 30)
pairs <- flood_persistence(filtration)

## End(Not run)

Vietoris-Rips Filtration: Get the boundary matrix and its reduction information in matrix form

Description

Vietoris-Rips Filtration: Get the boundary matrix and its reduction information in matrix form

Usage

build_vr_filtration(points, eps_max)

Arguments

points

Data point input.

eps_max

Maximum scale (epsilon).

Value

A list of simplices with their information.

Examples

points <- matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2)
filtration <- build_vr_filtration(points, eps_max=1.2)

Compute the Euler characteristic \chi of a simplicial complex

Description

Compute the Euler characteristic \chi of a simplicial complex

Usage

euler_characteristic(simplices, tol)

Arguments

simplices

A list of simplices (each a numeric vector).

tol

Optional numerical tolerance to pass to rankMatrix().

Details

The Euler characteristic is computed as:

\chi = \sum_{k=0}^{k_{\max}} (-1)^k \beta_k

where \beta_k is the kth Betti number, and k_{\max} is the highest dimension of any simplex in the complex.

Interpretation of values:

Value

An integer representing the Euler characteristic \chi.

See Also

betti_number

Examples

simplices <- list(c(1, 2), c(3, 4), c(2, 1, 3), c(4, 2))
euler_characteristic(simplices, tol=0.1)

This function extracts the persistence from combining the boundary matrix and its filtration

Description

This function extracts the persistence from combining the boundary matrix and its filtration

Usage

extract_persistence_pairs(filist, last_1, pivot_owner)

Arguments

filist

Filtration list, each element includes simplex and time.

last_1

The last 1 row index for each column in boundary matrix (after reduction).

pivot_owner

The column index owning the pivot row.

Value

A data frame with columns: dimension, birth, and death.

Examples

points <- matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2)
filtration <- build_vr_filtration(points, eps_max=1.2)
res <- boundary_info(filtration)
pairs <- extract_persistence_pairs(filtration, res$last_1, res$pivot_owner)

Generate all unique faces of a given dimension from simplices

Description

Generate all unique faces of a given dimension from simplices

Usage

faces(simplices, target_dim)

Arguments

simplices

A list of simplices (each a numeric vector).

target_dim

The target dimension k for the faces (e.g., 0 for vertices, 1 for edges, etc.).

Details

The function generates all possible subsets (combinations) of each simplex, removes duplicates, and filters them to only include those of length target_dim + 1.

For example, a 2-simplex c(1, 2, 3) has three 1-dimensional faces (edges): c(1,2), c(1,3), and c(2,3), and three 0-dimensional faces (vertices): 1, 2, and 3.

Value

A list of faces (each a numeric vector) of dimension target_dim.

Examples

simplices <- list(c(1, 2), c(3, 4), c(2, 1, 3), c(4, 2))
faces(simplices, target_dim=0)

Construct a Flood complex

Description

Builds the Flood complex of a point cloud: a Delaunay complex on a set of landmarks whose simplices are filtered by their covering radius with respect to the full point cloud ("flood time").

Usage

flood_complex(
  points,
  landmarks,
  max_dimension = NULL,
  points_per_edge = 30,
  backend = c("auto", "cpu", "torch"),
  batch_points = 2^22,
  delaunay = NULL
)

Arguments

points

A numeric matrix (N x d) of witness points.

landmarks

Either an integer (number of FPS landmarks) or a numeric matrix (N_l x d) of explicit landmark coordinates.

max_dimension

Top dimension of the simplices. Defaults to d.

points_per_edge

Grid resolution per simplex edge (accuracy vs. speed trade-off). Defaults to 30, as in flooder.

backend

One of "auto", "cpu", "torch". "cpu" uses a kd-tree (RANN). "torch" uses the torch R package and runs on CUDA when available. "auto" picks torch only if a CUDA device is present, else the kd-tree.

batch_points

Maximum number of grid points processed per batch (bounds memory). Defaults to 2^22.

delaunay

Optional precomputed Delaunay triangulation of the landmarks: an m x (d+1) integer matrix of 1-based landmark indices. If NULL (default), computed via geometry::delaunayn.

Value

A list of class "flood_complex" with elements simplices (list of integer vectors, landmark indices), filtration (numeric vector of flood times), landmarks (matrix), landmark_indices (or NULL).

Examples

## Not run: 
pts <- matrix(rnorm(3000), ncol = 2)
fc <- flood_complex(pts, landmarks = 40)

## End(Not run)

Persistence pairs via sparse boundary reduction

Description

Computes persistence pairs from a filtration list with the standard column-reduction algorithm, but on sparse columns (integer index vectors over GF(2)) instead of a dense matrix. Produces the same output format as extract_persistence_pairs(filist, res$last_1, res$pivot_owner) while scaling to the much larger complexes produced by build_flood_filtration.

Usage

flood_persistence(filist)

Arguments

filist

A filtration list (from build_flood_filtration or build_vr_filtration).

Value

A data frame with columns dim, birth, death.

Farthest-Point Sampling of landmarks

Description

Selects n_lms landmarks from a point cloud via (exact) Farthest-Point Sampling. Equivalent to flooder::generate_landmarks (which uses an approximate bucket-FPS; the exact version below gives the same qualitative coverage).

Usage

generate_landmarks(points, n_lms, start_idx = 1)

Arguments

points

A numeric matrix (N x d) point cloud.

n_lms

Number of landmarks to sample (<= N).

start_idx

Index of the starting point. Defaults to 1 (flooder defaults to index 0, i.e. the same first point).

Value

A list with landmarks (n_lms x d matrix) and indices (row indices into points).

Examples

## Not run: 
pts <- matrix(rnorm(2000), ncol = 2)
lms <- generate_landmarks(pts, 50)

## End(Not run)

Persistence pairs via sparse boundary reduction (for large filtrations)

Description

Same standard column-reduction algorithm as boundary_info() + extract_persistence_pairs(), but each column is stored as a sorted integer vector over GF(2) instead of a row of a dense n x n matrix. Memory drops from O(n^2) to O(total number of non-zeros), which is what makes filtrations with thousands to hundreds of thousands of simplices (e.g. Flood or large Vietoris-Rips complexes) feasible. Output is identical to the dense pipeline.

Usage

persistence_pairs(filist)

Arguments

filist

Filtration list, each element includes simplex and time.

Value

A data frame with columns: dim, birth, and death.

Examples

points <- matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2)
filtration <- build_vr_filtration(points, eps_max=1.2)
pairs <- persistence_pairs(filtration)

Plot Persistence Diagram

Description

Plot Persistence Diagram

Usage

plot_persistence(df)

Arguments

df

Dataframe from plot_persistence.

Value

A ggplot2 object representing the persistence diagram.

Examples

points <- matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2)
filtration <- build_vr_filtration(points, eps_max=1.2)
res <- boundary_info(filtration)
pairs <- extract_persistence_pairs(filtration, res$last_1, res$pivot_owner)
plot_persistence(pairs)