generate_edgelist: Export null modelling results

Description

Exports the observed network alongside the mean interaction strengths calculated from the null model and the significance test results in a standard format that can be imported into other network analysis packages e.g. igraph (Csardi & Nepusz 2006) or cheddar (Hudson et al. 2013). This provides access to a wide range of plotting and analysis tools, especially for non-bipartite networks.

Usage

generate_edgelist(
  nullnet,
  signif.level = 0.95,
  export.null = FALSE,
  edge.cols = c("#67A9CF", "#F7F7F7", "#EF8A62")
)

Arguments

nullnet

An object of class nullnet from generate_null_net

signif.level

An optional value specifying the threshold used for testing for 'significant' deviations from the null model. Defaults to 0.95

export.null

An optional logical value specifying whether export should be limited to those interactions that were present in the observed network or should include any additional interactions present across iterations of the null network. Depending upon the data and any forbidden links specified, additional interactions may be present in the modelled networks. Defaults to FALSE (only observed interactions are exported).

edge.cols

An optional character vector of length three specifying potential colours for network links when used with a suitable plotting function: in sequence, these should represent i) interactions that are weaker than expected, ii) consistent with the null model and iii) stronger than expected. The default is a colourblind friendly blue, white and red scheme, using Colorbrewer's Red-Blue colour scheme (Brewer 2017).

Value

A data frame where each row represents the interaction observed between a pair of consumer and resource species, and with the following column headings:

Consumer: Name of the consumer species (node)
Resource: Name of the resource species (node)
Observed: Strength of the observed interaction
Null: Mean strength of the interaction across the iterations of the null model
SES: The standardised effect size for the interaction
Test: Whether the observed interaction is significantly stronger than expected under the null model, weaker or consistent with the null model ns

References

Brewer, C.A. (2017) https://colorbrewer2.org/

Csardi, G. & Nepusz, T. (2006) The igraph software package for complex network research. InterJournal, Complex Systems, 1695.

Vaughan, I.P., Gotelli, N.J., Memmott, J., Pearson, C.E., Woodward, G. & Symondson, W.O.C. (2018) econullnetr: an R package using null models to analyse the structure of ecological networks and identify resource selection. Methods in Ecology and Evolution, 9, 728--733.

Examples

Run this code

# NOT RUN {
set.seed(1234)
bs.null <- generate_null_net(Broadstone, Broadstone.prey,
                             data.type = "counts", sims = 10,
                             r.weights = Broadstone.fl)
BS.export <- generate_edgelist(bs.null, signif.level = 0.95,
                               edge.cols = c("#67A9CF", "black", "#EF8A62"))

if (requireNamespace("igraph", quietly = TRUE)) {
 net.1 <- igraph::graph_from_edgelist(as.matrix(BS.export[, c("Resource",
                                                              "Consumer")]),
                                      directed = TRUE)

 # Add in the null modelling results
 igraph::E(net.1)$obs.str <- BS.export$Observed
 igraph::E(net.1)$test.res <- BS.export$Test
 igraph::E(net.1)$edge.cols <- BS.export$edge.col

 igraph::plot.igraph(net.1, layout = igraph::layout_in_circle,
                     edge.color = igraph::E(net.1)$edge.cols,
                     edge.width = sqrt(igraph::E(net.1)$obs.str),
                     edge.arrow.size = .4)
}

# }