backbone (version 2.0.3)

disparity: 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; (4) a network 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", "sparseMatrix", "igraph", "network", "edgelist"). If "original", the backbone graph returned is of the same class as W.

narrative

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

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.

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.

References

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. 10.1073/pnas.0808904106

Examples

# NOT RUN {
#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
# }