backbone (version 2.0.0)

fdsm: Extract backbone using the Fixed Degree Sequence Model

Description

fdsm extracts the backbone of a bipartite projection using the Fixed Degree Sequence Model.

Usage

fdsm(
  B,
  trials = 1000,
  method = "fastball",
  alpha = NULL,
  signed = FALSE,
  fwer = "none",
  class = "original",
  narrative = FALSE,
  ...
)

Arguments

B

An unweighted bipartite graph, as: (1) an incidence matrix in the form of a matrix, sparse Matrix, or dataframe; (2) an edgelist in the form of a two-column matrix, sparse Matrix, or dataframe; (3) an igraph object; (4) a network object. Any rows and columns of the associated bipartite matrix that contain only zeros are automatically removed before computations.

trials

numeric: The number of bipartite graphs generated to approximate the edge weight distribution.

method

string: The method used to generate random bipartite graphs, one of c("fastball", "curveball")

alpha

real: significance level of hypothesis test(s)

signed

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

fwer

string: type of familywise error rate 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 B.

narrative

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

...

optional arguments

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, fwer, class, and narrative parameters are ignored.

Details

The fdsm function compares an edge's observed weight in the projection B*t(B) to the distribution of weights expected in a projection obtained from a random bipartite network where both the row vertex degrees and column vertex degrees are exactly fixed at their values in B. It uses the fastball() algorithm to generate random bipartite matrices with give row and column vertex degrees. The fdsm.trials() function can be used to estimate the number of random bipartite matrices that must be generated to obtain stable edge p-values.

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.

References

fdsm: Neal, Z. P., Domagalski, R., and Sagan, B. (2021). Comparing Alternatives to the Fixed Degree Sequence Model for Extracting the Backbone of Bipartite Projections. Scientific Reports. 10.1038/s41598-021-03238-3

curveball: Strona, Giovanni, Domenico Nappo, Francesco Boccacci, Simone Fattorini, and Jesus San-Miguel-Ayanz. 2014. A Fast and Unbiased Procedure to Randomize Ecological Binary Matrices with Fixed Row and Column Totals. Nature Communications, 5, 4114. 10.1038/ncomms5114

Examples

# NOT RUN {
#A binary bipartite network of 30 agents & 75 artifacts; agents form three communities
B <- rbind(cbind(matrix(rbinom(250,1,.8),10),
                 matrix(rbinom(250,1,.2),10),
                 matrix(rbinom(250,1,.2),10)),
           cbind(matrix(rbinom(250,1,.2),10),
                 matrix(rbinom(250,1,.8),10),
                 matrix(rbinom(250,1,.2),10)),
           cbind(matrix(rbinom(250,1,.2),10),
                 matrix(rbinom(250,1,.2),10),
                 matrix(rbinom(250,1,.8),10)))

P <- B%*%t(B) #An ordinary weighted projection...
plot(igraph::graph_from_adjacency_matrix(P, mode = "undirected",
                                         weighted = TRUE, diag = FALSE)) #...is a dense hairball

bb <- fdsm(B, alpha = 0.05, narrative = TRUE, class = "igraph") #An FDSM backbone...
plot(bb) #...is sparse with clear communities
# }