disparity {backbone}R Documentation

Extract backbone using the Disparity Filter

Description

disparity extracts the backbone of a weighted network using the Disparity Filter.

Usage

disparity(
  W,
  alpha = 0.05,
  signed = FALSE,
  mtc = "none",
  class = "original",
  narrative = FALSE
)

Arguments

W

A weighted unipartite graph, as: (1) an adjacency matrix in the form of a matrix or sparse Matrix; (2) an edgelist in the form of a three-column dataframe; (3) an igraph object.

alpha

real: significance level of hypothesis test(s)

signed

boolean: TRUE for a signed backbone, FALSE for a binary backbone (see details)

mtc

string: type of Multiple Test Correction to be applied; can be any method allowed by p.adjust.

class

string: the class of the returned backbone graph, one of c("original", "matrix", "Matrix", "igraph", "edgelist"). If "original", the backbone graph returned is of the same class as W.

narrative

boolean: TRUE if suggested text & citations should be displayed.

Details

The disparity function applies the disparity filter (Serrano et al., 2009), which compares an edge's weight to its expected weight if a node's total degree was uniformly distributed across all its edges. The graph may be directed or undirected, however the edge weights must be positive.

When signed = FALSE, a one-tailed test (is the weight stronger) is performed for each edge with a non-zero weight. It yields a backbone that perserves edges whose weights are significantly stronger than expected in the chosen null model. When signed = TRUE, a two-tailed test (is the weight stronger or weaker) is performed for each every pair of nodes. It yields a backbone that contains positive edges for edges whose weights are significantly stronger, and negative edges for edges whose weights are significantly weaker, than expected in the chosen null model. NOTE: Before v2.0.0, all significance tests were two-tailed and zero-weight edges were evaluated.

If W is an unweighted bipartite graph, any rows and columns that contain only zeros or only ones are removed, then the global threshold is applied to its weighted bipartite projection.

Value

If alpha != NULL: Binary or signed backbone graph of class class.

If alpha == NULL: An S3 backbone object containing three matrices (the weighted graph, edges' upper-tail p-values, edges' lower-tail p-values), and a string indicating the null model used to compute p-values, from which a backbone can subsequently be extracted using backbone.extract(). The signed, mtc, class, and narrative parameters are ignored.

References

package: Neal, Z. P. (2022). backbone: An R Package to Extract Network Backbones. PLOS ONE, 17, e0269137. doi: 10.1371/journal.pone.0269137

disparity filter: Serrano, M. A., Boguna, M., & Vespignani, A. (2009). Extracting the multiscale backbone of complex weighted networks. Proceedings of the National Academy of Sciences, 106, 6483-6488. doi: 10.1073/pnas.0808904106

Examples

#A network with heterogeneous (i.e. multiscale) weights
net <- matrix(c(0,10,10,10,10,75,0,0,0,0,
                10,0,1,1,1,0,0,0,0,0,
                10,1,0,1,1,0,0,0,0,0,
                10,1,1,0,1,0,0,0,0,0,
                10,1,1,1,0,0,0,0,0,0,
                75,0,0,0,0,0,100,100,100,100,
                0,0,0,0,0,100,0,10,10,10,
                0,0,0,0,0,100,10,0,10,10,
                0,0,0,0,0,100,10,10,0,10,
                0,0,0,0,0,100,10,10,10,0),10)

net <- igraph::graph_from_adjacency_matrix(net, mode = "undirected", weighted = TRUE)
plot(net, edge.width = sqrt(igraph::E(net)$weight)) #A stronger clique & a weaker clique

strong <- igraph::delete.edges(net, which(igraph::E(net)$weight < mean(igraph::E(net)$weight)))
plot(strong) #A backbone of stronger-than-average edges ignores the weaker clique

bb <- disparity(net, alpha = 0.05, narrative = TRUE) #A disparity backbone...
plot(bb) #...preserves edges at multiple scales

[Package backbone version 2.1.0 Index]