Tidy Topological Features for One or Many Networks
Source:R/simplicial_features.R
simplicial_features.Rdsimplicial_features() builds a simplicial complex for each network with
build_simplicial() and returns its topological summaries as a tidy data
frame, one row per network and one column per feature, ready to use as
regression predictors or to join onto unit-level outcomes. It takes one
network, a group of networks, the within-cluster networks of an mcml,
or a list of networks, at one threshold or a sweep of them.
Higher-order structure is reported as d2, d3, ...: the number of
simplices of that dimension. A 2-simplex is a triangle of three mutually
connected states, a 3-simplex a tetrahedron of four. These count
co-participation in a dense region, not statistical interaction. The
counts are a step function of threshold, so one threshold is a choice,
not a result: sweep several and check that a conclusion holds across
them.
Arguments
- x
The networks: a
netobject,cograph_network,tnamodel or square weight matrix (one row); anetobject_group, or a list of single networks or matrices (one row per member, named by the list, ornetwork_1,network_2, ... when unnamed); or anmcmlobject (one row per cluster, from its within-cluster networks; one built without them raises an error).- threshold
The smallest absolute edge weight that makes an edge, passed to
build_simplicial(). Default0(every non-zero edge). A vector sweeps it, giving one row per network per threshold. Values must be finite and not negative.type = "vr"andtype = "pathway"ignore it, although thethresholdcolumn still records it.- max_dim
The highest simplex dimension built, a whole number of at least 1 (a fractional value is truncated). Default
4. When a network holds a larger clique, the complex is truncated andbetti_numbers()warns with classnestimate_truncated_complex; the warning concerns the Betti number of dimensionmax_dim, so it affectsb1only whenmax_dim = 1.- normalize
Whether to divide the simplex counts (
d1onwards andhigher_order) by the number of nodes, so networks of different size are comparable;n_edgesstays a count. DefaultFALSE.- type
The complex construction passed to
build_simplicial():"clique"(default),"pathway","vr"or its alias"rips"."pathway"needs networks of classnetobjectortna, from which a higher-order network is built; a matrix, a barecograph_networkor anmcml(whose cluster layers are matrices) raises an error.
Value
A data frame with one row per network and threshold, ordered by
network name and then threshold, and columns network, threshold,
n_nodes, n_edges, b0 and b1 (the Betti numbers: connected
components and independent cycles, 0 when the complex has no such
dimension), euler (the Euler characteristic of the complex as
built), max_q (the top q-level of q_analysis(), the dimension of the
largest maximal simplex), d1, d2, ... up to dimension max_dim
(simplex counts by dimension) and higher_order (the total from d2 upward).
Examples
m1 <- matrix(c(0, .6, .5, .6, 0, .4, .5, .4, 0), 3, 3,
dimnames = list(c("A", "B", "C"), c("A", "B", "C")))
m2 <- matrix(c(0, .2, 0, .2, 0, .1, 0, .1, 0), 3, 3,
dimnames = list(c("A", "B", "C"), c("A", "B", "C")))
simplicial_features(list(dense = m1, sparse = m2), threshold = 0.3)
#> network threshold n_nodes n_edges b0 b1 euler max_q d1 d2 d3 d4 higher_order
#> 1 dense 0.3 3 3 1 0 1 2 3 1 0 0 1
#> 2 sparse 0.3 3 0 3 0 3 0 0 0 0 0 0
# Sweep the threshold rather than committing to one.
simplicial_features(list(dense = m1), threshold = c(0.1, 0.3, 0.5))
#> network threshold n_nodes n_edges b0 b1 euler max_q d1 d2 d3 d4 higher_order
#> 1 dense 0.1 3 3 1 0 1 2 3 1 0 0 1
#> 2 dense 0.3 3 3 1 0 1 2 3 1 0 0 1
#> 3 dense 0.5 3 2 1 0 1 1 2 0 0 0 0