fdsm: Extract backbone using the Fixed Degree Sequence Model

In backbone: Extracts the Backbone from Graphs

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,
  alpha = 0.05,
  trials = NULL,
  signed = FALSE,
  mtc = "none",
  class = "original",
  narrative = FALSE,
  progress = TRUE,
  ...
)

Arguments

B	An unweighted bipartite graph, as: (1) an incidence matrix in the form of a matrix or sparse Matrix; (2) an edgelist in the form of a two-column dataframe; (3) an igraph object.
alpha	real: significance level of hypothesis test(s)
trials	numeric: the number of bipartite graphs generated to approximate the edge weight distribution. If NULL, the number of trials is selected based on alpha (see details)
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 B.
narrative	boolean: TRUE if suggested text & citations should be displayed.
progress	boolean: TRUE if the progress of Monte Carlo trials should be displayed.
...	optional arguments

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.

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.

The p-values used to evaluate the statistical significance of each edge are computed using Monte Carlo methods. The number of trials performed affects the precision of these p-values, and the confidence that a given p-value is less than the desired alpha level. Because these p-values are proportions (i.e., the proportion of times an edge is weaker/stronger in the projection of a random bipartite graphs), evaluating the statistical significance of an edge is equivalent to comparing a proportion (the p-value) to a known proportion (alpha). When trials = NULL, the power.prop.test function is used to estimate the required number of trials to make such a comparison with a alpha type-I error rate, (1-alpha) power, and when the riskiest p-value being evaluated is at least 5% smaller than alpha. When any mtc correction is applied, for simplicity this estimation is based on a conservative Bonferroni correction.

Value

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

If alpha == NULL: An S3 backbone object containing (1) the weighted graph as a matrix, (2) upper-tail p-values as a matrix, (3, if signed = TRUE) lower-tail p-values as a matrix, (4, if present) node attributes as a dataframe, and (5) several properties of the original graph and backbone model, from which a backbone can subsequently be extracted using backbone.extract().

References

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

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. doi: 10.1038/s41598-021-03238-3

fastball: Godard, Karl and Neal, Zachary P. 2022. fastball: A fast algorithm to sample bipartite graphs with fixed degree sequences. Journal of Complex Networks doi: 10.1093/comnet/cnac049

Examples

#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, trials = 1000, narrative = TRUE, class = "igraph") #An FDSM backbone...
plot(bb) #...is sparse with clear communities

backbone documentation built on Feb. 16, 2023, 6:13 p.m.