build_simplicial() builds a simplicial complex, the higher-order
structure of a network: besides nodes (0-simplices) and edges
(1-simplices) it holds filled triangles (2-simplices), tetrahedra and
larger groups of nodes. Three constructions are available through type:
Clique complex (
"clique"): every clique of the network whose edges reachthresholdbecomes a simplex, the standard bridge from a graph to algebraic topology.Pathway complex (
"pathway"): the states on each higher-order pathway of anet_hon,net_hypaornet_mogen(or of one built from atnamodel ornetobject) become a simplex.Vietoris-Rips complex (
"vr", alias"rips"): the input is a non-negative distance matrix, every group of nodes whose pairwise distances are all at mostmax_scalebecomes a simplex, and each simplex records the scale at which it enters (its largest pairwise distance), sopersistent_homology()can read the filtration.
A clique complex is fixed by the thresholded graph, since every clique is
filled in; its Betti numbers count the holes that remain, such as cycles
of edges that no triangles fill. Its shape depends on threshold, so
read betti_numbers() at more than one threshold, or follow the features
across all of them with persistent_homology(). A pathway complex is
built from paths observed in the sequences, so its simplices say which
states occur together on a path.
simplicial_degree() and q_analysis() describe how the nodes take part
in the complex.
Arguments
- x
The network: a square weight matrix, a
tnamodel, anetobjectorcograph_network, or anet_hon,net_hypaornet_mogen. Withtype = "vr", the matrix holds non-negative distances. The clique and Vietoris-Rips constructions read the weight matrix of any of these networks; withtype = "pathway", a barecograph_networkor a matrix raises an error. For theprint()andplot()methods: asimplicial_complexobject.- type
The construction:
"clique"(default),"pathway"or"vr"(alias"rips", stored as"vr").- threshold
For
type = "clique": the smallest absolute edge weight an edge needs to enter (edges at exactlythresholdare included). Zero weights are never edges. Default0. Ignored for"vr", which usesmax_scale, and for"pathway".- max_dim
The highest simplex dimension built (a k-simplex has k + 1 nodes), a non-negative whole number. Default
10. When a larger clique is cut at this dimension, the clique or Vietoris-Rips complex is marked truncated;betti_numbers()then warns with classnestimate_truncated_complex, as doespersistent_homology()on a Vietoris-Rips complex. A pathway with more thanmax_dim + 1distinct states is cut to its faces of that size, without the truncated mark.- max_pathways
For
type = "pathway", how many pathways to keep: the most frequent higher-order paths for anet_hon, the most frequent transitions ofmogen_transitions()at the optimal order for anet_mogen(the highest order fitted when the optimal one is 0), and for anet_hypathe anomalous paths ranked by their observed / expected ratio (seeanomaly). DefaultNULL(all).- anomaly
For
type = "pathway"on anet_hypa: which anomalous paths become simplices:"all"(default),"over"or"under". Over-represented and"all"paths are ranked by the largest ratio, under-represented ones by the smallest. Possible paths that never occur are left out, since a pathway simplex is a set of states observed together on a path.- max_scale
For
type = "vr": the largest distance at which an edge enters; longer edges are left out. DefaultNULL, the largest finite distance.- ...
For
type = "pathway"on atnamodel ornetobject:method("hon", the default,"hypa"or"mogen") chooses the higher-order model built from it, and the other arguments go tobuild_hon(),build_hypa()orbuild_mogen(). Any other construction or input does not read...and warns with classnestimate_ignored_argumentwhen it is given. For theprint()andplot()methods: ignored.- combined
For the
plot()method:TRUE(default) draws the four panels (f-vector, Betti numbers, simplicial degree per node and degree by dimension) as one 2 x 2 figure, which needs gridExtra;FALSEreturns the four ggplots in a named list (f_vector,betti,degree,degree_heatmap) to print, save or arrange separately. A complex without edges (dimension 0) has no simplicial degree to draw and raises an error of classnestimate_bad_input.
Value
A simplicial_complex object. print() shows the counts, the
density, the f-vector (simplices per dimension), the Euler
characteristic and the non-zero Betti numbers; plot() draws the
f-vector, the Betti numbers and the simplicial degree of each node;
betti_numbers(), euler_characteristic(), simplicial_degree(),
q_analysis() and persistent_homology() read it. The object's
fields:
- simplices
List of integer vectors, one per simplex, each holding the sorted indices of the nodes it spans. Every face of every simplex is present, as are all 0-simplices (isolated nodes included).
- nodes
Character vector of node labels, which
simplicesindex.- n_nodes, n_simplices
Counts of nodes and simplices.
- dimension
Highest simplex dimension present.
- f_vector
Named integer vector
dim_0,dim_1, ...: the number of simplices of each dimension.- density
n_simplicesdivided by the number of simplices a complete complex onn_nodesnodes would have up todimension.- mean_dim
Mean simplex dimension.
- type
"clique","pathway"or"vr".- truncated
For the clique and Vietoris-Rips complexes: whether
max_dimcut a larger clique.
A Vietoris-Rips complex also holds filtration (the scale at which each
simplex enters, in the order of simplices) and max_scale (the cap
used), which persistent_homology() reads.
The print() method returns its input invisibly. plot()
returns the drawn grid grob invisibly with combined = TRUE, and the
named list of four ggplots invisibly with combined = FALSE.
Details
For the clique and Vietoris-Rips complexes the weight matrix is made
symmetric first (the larger absolute weight of the two directions for a
clique complex, the larger distance for a Vietoris-Rips complex) and its
diagonal is not read. Cliques are found with igraph::cliques() when
igraph is installed, and by Bron-Kerbosch otherwise.
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)
#> Clique Complex
#> 3 nodes, 7 simplices, dimension 2
#> Density: 100.0% | Mean dim: 0.71 | Euler: 1
#> f-vector: (f0=3 f1=3 f2=1)
#> Betti: b0=1
#> Nodes: A, B, C
betti_numbers(sc)
#> b0 b1 b2
#> 1 0 0
# Vietoris-Rips on a distance matrix:
d <- 1 - mat
diag(d) <- 0
sc_vr <- build_simplicial(d, type = "vr", max_scale = 0.6)