Package 'econullnetr'

Title: Null Model Analysis for Ecological Networks
Description: Tools for using null models to analyse ecological networks (e.g. food webs, flower-visitation networks, seed-dispersal networks) and detect resource preferences or non-random interactions among network nodes. Tools are provided to run null models, test for and plot preferences, plot and analyse bipartite networks, and export null model results in a form compatible with other network analysis packages. The underlying null model was developed by Agusti et al. (2003) Molecular Ecology <doi:10.1046/j.1365-294X.2003.02014.x> and the full application to ecological networks by Vaughan et al. (2018) econullnetr: an R package using null models to analyse the structure of ecological networks and identify resource selection. Methods in Ecology & Evolution, <doi:10.1111/2041-210X.12907>.
Authors: Ian Vaughan
Maintainer: Ian Vaughan <[email protected]>
License: MIT + file LICENSE
Version: 0.2.1
Built: 2024-11-26 03:37:11 UTC
Source: https://github.com/ivaughan/econullnetr

Help Index

Test for significant differences in a range of network metrics between the observed and null bipartite networks

Description

Acts as a wrapper for the bipartite package's networklevel, grouplevel and specieslevel functions, allowing a wide range of measures to be calculated (Dormann et al., 2008, 2009; Dorman 2011). These are calculated both for the observed network and across the iterations of the null model, allowing for simple tests of whether the observed values differ from those expected by chance.

Usage

bipartite_stats(
  nullnet,
  signif.level = 0.95,
  index.type,
  indices,
  prog.count = TRUE,
  ...
)

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
index.type

String specifying which function to call from the bipartite package: specieslevel, grouplevel or networklevel, according to the level at which the statistics are required. For specieslevel, statistics are calculated for both 'higher' and 'lower' levels i.e. level = "both" and cannot be changed: adding a level argument will produce an error: statistics from higher and lower levels are easily separated in the output from bipartite_stats.
indices

Vector listing the bipartite network statistics to calculate. All indices are currently supported, with the exception of the dependence matrix: if ALL is specified, it will default to ALLBUTD.
prog.count

A logical value specifying whether the progress count should be shown. Defaults to TRUE.
...

Other arguments that may be supplied to bipartite's specieslevel, grouplevel or networklevel functions.

Details

Allows most of the network metrics in the bipartite package to be calculated for an observed bipartite network and compared to the distribution of those network metrics across the iterations of the null model. This indicates whether the observed network differs from the structure of the network that could be expected if consumers simply used resources in proportion to their relative abundance.

The user sets the significance level (default = 95% confidence limits), and the metrics selected are classified into those that are higher, lower or consistent with the null model at that significance level. Significance is determined by comparing the observed value of the statistic to the 1-alpha/2 percentiles from the frequency distribution, with 'significant' values falling outside the confidence interval (Manly 2006).

Value

Returns one or more data frames according to the level at which the statistics are calculated (specieslevel, grouplevel or networklevel). If index.type = "networklevel" or index.type = "grouplevel" a single data frame is returned, listing the chosen network statistics and with the following column headings:

Observed

Value of the statistic for the observed network

Null

Mean value of the statistic across the iterations of the null model

Lower.CL

Lower confidence limit for the metric

Upper.CL

Upper confidence limit for the network metric

Test

Whether the value of the statistic with the observed network is significantly higher than expected under the null model, lower or consistent with the null model (ns)

SES

The standardised effect size for the difference between the observed network and the null model (see Gotelli & McCabe 2002 for details)

If index.type = "specieslevel", a list comprising two data frames for each statistic, representing the higher and lower levels in the network. Each data frame has the same format as for networklevel except that the rows are individual nodes (species) in the network. See examples for how to call the individual data frames.

References

Dormann, C.F., Gruber B. & Frund, J. (2008). Introducing the bipartite package: analysing ecological networks. R news, 8, 8–11.

Dormann, C.F., Frund, J., Bluthgen, N. & Gruber, B. (2009). Indices, graphs and null models: analyzing bipartite ecological networks. Open Ecology Journal 2, 7–24.

Dormann, C.F. (2011) How to be a specialist? Quantifying specialisation in pollination networks. Network Biology, 1, 1-20.

Gotelli, N.J. & McCabe, D.J. (2002) Species co-occurrence: a meta-analysis of J.M. Diamond's assembly rules model. Ecology, 83, 2091–2096.

Manly, B.F.J. (2006) Randomization, Bootstrap and Monte Carlo Methods in Biology (3rd edn). Chapman & Hall, Boca Raton.

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.

See Also

generate_null_net, plot_bipartite, networklevel, grouplevel, specieslevel

Examples

set.seed(1234)
sil.null <- generate_null_net(Silene[, 2:7], Silene.plants[, 2:6], sims = 10,
                              c.samples = Silene[, 1],
                              r.samples = Silene.plants[, 1])
# Network-level analysis
net.stats <- bipartite_stats(sil.null, index.type = "networklevel",
                             indices = c("linkage density",
                             "weighted connectance", "weighted nestedness",
                             "interaction evenness"), intereven = "sum")
net.stats

# Group-level analysis
grp.stats <- bipartite_stats(sil.null, index.type = "grouplevel",
                             indices = c("generality",
                             "vulnerability", "partner diversity"),
                             logbase = 2)
grp.stats

# Species-level statistics
spp.stats <- bipartite_stats(sil.null, index.type = "specieslevel",
                             indices = c("degree", "normalised degree",
                             "partner diversity"), logbase = exp(1))

spp.stats # Show all data frames of results
spp.stats$normalised.degree # Select one statistic
spp.stats$normalised.degree$lower # Select one statistic at one level

Part of the highly-resolved food web from Broadstone Stream, UK

Description

Part of the highly-resolved macroinvertebrate food web from Broadstone Stream in south-east England (see Woodward et al., 2005 for full details of the web). This data frame contains data collected in August 1996, with 19 macroinvertebrate taxa. Predation was determined via visual gut contents analysis, with identification of hard parts allowing counts of the number of individual prey organisms each individual predator consumed. There are three accompanying data sets:

  1. Broadstone.prey Gives the total abundance of each prey taxon from 30 Surber samples collected at the same time as the interaction data.

  2. Broadstone.fl Specifies 'forbidden' links which are not allowed in the null model.

  3. Broadstone.nodes The abundance and mean body mass for each taxon in the food web in a format for use alongside a generate_null_model object with the cheddar package (Hudson et al., 2013). Body size is taken from cheddar's 'BroadstoneStream' data set.

Usage

Broadstone

Format

A data frame with 319 rows and 20 columns. Each row represents the gut contents of an individual predator. There are 20 columns in total, with the first column (Predator) indicating the predator taxon (seven taxa in total) and the remaining 19 columns indicating the number of individuals eaten of each of the 19 potential prey taxa.

Source

Woodward, G., Speirs, D.C. & Hildrew, A.G. (2005) Quantification and resolution of a complex, size-structured food web. Advances in Ecological Research, 36, 84–135.

'Forbidden' links to accompany the Broadstone data set

Description

Networks often contain 'forbidden links', where interactions are not possible between two taxa due to factors such as large differences in body size, spatio-temporal mismatches or specialised flower morphology in flower visitation networks. Broadstone.fl summarises the forbidden links in the Broadstone food web, estimated from the interactions observed from a complete year's sampling (Table 3 in Woodward et al. 2005). This table is illustrative, and should not be considered a definitive list.

Usage

Broadstone.fl

Format

A data frame with 20 columns and seven rows, one row for each of the seven predator taxa. The first column (Predator) lists the seven taxa, whilst the remaining 19 columns are the invertebrate taxa in the food web: each element indicates whether the predator can consume that taxon (1) or whether the link is 'forbidden' (0).

Source

Woodward, G., Speirs, D.C. & Hildrew, A.G. (2005) Quantification and resolution of a complex, size-structured food web. Advances in Ecological Research, 36, 84–135.

Abundance and body mass data to accompany the Broadstone data set

Description

Provides additional information about each macroinvertebrate taxon in the Broadstone food web for use alongside null model results in the foodweb package cheddar (Hudson et al. 2013).

Usage

Broadstone.nodes

Format

A data frame with three columns and 19 rows:

node

The name of the macroinvertebrate taxon (node) in the network

M

The mean body mass of an individual of the taxon, from cheddar's BroadstoneStream object

N

The total abundance of each taxon from the 30 Surber samples (see Broadstone.prey for details)

Macroinvertebrate abundance data to accompany the Broadstone data frame

Description

The abundance of the 19 macroinvertebrate taxa present in the Broadstone food web in August 1996 (see Woodward et al. 2005 for full details). The values are the total number of individuals collected from 30 Surber samples.

Usage

Broadstone.prey

Format

A data frame with 19 columns and one row, with each column name representing one taxon. Names match those in Broadstone.

Source

Woodward, G., Speirs, D.C. & Hildrew, A.G. (2005) Quantification and resolution of a complex, size-structured food web. Advances in Ecological Research, 36, 84–135.

econullnetr: tools for using null models to analyse the structure of ecological networks and identify resource selection

Description

econullnetr provides a set of functions for running null models, analysing and plotting the results, and exporting the outputs for use with other network packages in R.

References

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.

Expand a summarised interaction matrix

Description

A simple function for converting interaction matrices that are summarised at (typically) species-level to individual-level matrices, ready for use with generate_null_net. This is only applicable to the special (but common) case where one individual = one interaction (e.g. many pollination networks, ant-seed networks). Data can be stored either with consumers as columns and resources as rows or vice versa. Taxon names for each row in the matrix could either be stored as the row names of the matrix or data frame (as used, for example, by the bipartite package), or as a column containing the names in a data frame.

Usage

expand_matrix(X, r.names = rownames(X), MARGIN = 1)

Arguments

X

A matrix or data frame representing the interaction matrix. This should only include the interaction data (i.e. counts of different interactions) and no additional columns for taxon names, covariates, etc
r.names

An optional object of identical length to the number of rows in X listing the taxon names. In many situations these may be the row names of X (the default). Alternatively r.names can be use to specify a column in a data frame containing the names or a separate vector.
MARGIN

Similar to apply, an integer value indicating whether the data are arranged in rows or columns. MARGIN = 1 (the default) indicates that each column relates to one consumer taxon (the format typically used for bipartite networks), whilst MARGIN = 2 indicates that each row is one consumer taxon, with column names being the resources.

Value

A data frame where each row represents the interaction observed between an individual consumer and one resource species. The first column is named Consumer and records which taxon each indidual belongs to. The remaining columns represent the resources: one column for each taxon.

Examples

# Toy example representing a typical bipartite format.
  bp.inter <- matrix(c(1, 2, 2, 0, 5, 3, 3, 0, 2), nrow = 3, byrow = FALSE,
                     dimnames = list(c("A", "B", "C"),
                                     c("sp1", "sp2", "sp3")))
 bp.inter
 expand_matrix(bp.inter)

# Use a simplified version of the Silene data set, pooling data
# across the 11 visits.
  int.summ <- aggregate(Silene[, 3:7], by = list(Silene$Insect), sum)
  colnames(int.summ)[1] <- "taxon"
  expand_matrix(int.summ[, -1], r.names = int.summ$taxon, MARGIN = 2)

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.

See Also

generate_null_net

Examples

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)
}

Null models for ecological networks

Description

Uses the algorithm of Agusti et al. (2003) to specify and run a null model for an ecological network based upon interaction data and independent estimates of resource abundance (see Vaughan et al., 2018 for full details). Typically, network nodes represent species, and the following documentation uses the term species in place of node, but this need not be the case.

Usage

generate_null_net(
  consumers,
  resources,
  sims = 100,
  data.type = "names",
  maintain.d = NULL,
  summary.type = "sum",
  c.samples = NULL,
  r.samples = NULL,
  r.weights = NULL,
  prog.count = TRUE
)

Arguments

consumers

A matrix or data frame containing the interaction data. The first column should contain the name of the consumer species, with the remaining column names listing the resources (the names must be identical and in the same order as in resources). Each row represents one individual, with the elements in the matrix indicating whether a resource was used or how much was used (see Details).
resources

A matrix or data frame containing the relative abundances of the different resources (e.g. density of different prey species or abundance of different flower species). May either have one row, if all data came from the same location and/or time, or have the same number of rows as there are sampling stratum codes in r.samples and c.samples (e.g. the set of time points or plot names), if the data are subdivided across sampling times/sites. Resource names (column names) in resources and consumers must be identical and in the same order.
sims

Number of iterations of the null model. The default value is 100, but this should generally be increased to estimate meaningful confidence limits.
data.type

An optional string specifying the type of interaction data. One of three options: "names" (the default), "counts" or "quantities". See Details for a full explanation and examples.
maintain.d

When data.type = "counts" or "quantities", a string indicating whether the degree of each individual consumer (i.e. the number of different resource species it interacted with) should be maintained when allocating individual resources/quantities. Default is FALSE.
summary.type

An optional string indicating how the interactions should be summarised at the species level: one of "sum" (the default), indicating that the interactions between a consumer and resource species will be summed across all individuals, or "mean", indicating that the mean value per individual of a consumer species will be calculated.
c.samples

An optional vector that specifies names for subdivisions of the interaction data when data on interactions and resource abundance were collected across a series of subdivisions (e.g. at different sites or time points). If suddivisions were present, they should be specified for both c.samples and r.samples. The sample names must be identical in c.samples and r.samples (although c.samples is likely to be much longer than r.samples due to >1 individual consumer per subdivision)
r.samples

An optional vector specifying the sample names for the resource abundance data (resources), and corresponding to the names used in c.samples. Must have the name number of entries as there are rows in resources. Not needed when resources contains a single row/c.samples is absent.
r.weights

An optional data frame or matrix specifying weights to be applied to rows in resources: all entries must be in the range 0–1. The first column should contain the consumer species names, one entry for each species, within the remaining columns listing all species present in resources (names must be identical and in the same order as in resources). Mainly used to specify forbidden links by specifying zero values for forbidden links and ones for the remaining entries. Only one table is supplied, which then applies across all subdivisions of the data (if present).
prog.count

A logical value specifying whether the progress count should be shown. Defaults to TRUE.

Details

A basic call to generate_null_net only needs two arguments: consumers and resources, but it is recommended that sims is also specified to run a larger number of iteration of the null model (e.g. 1000). It is important to ensure that species names are consistent throughout and that the resource species used as column names in resources, consumers and (optionally) r.weights are in the same order (both consumers and r.weights should be one column wider than resources, because they include an extra column at the start to list the consumer species).

The same species can appear as both a consumer and a resource e.g. when a species is both predator and prey in a food web. Interactions can be excluded from the modelled networks by specifying forbidden links with r.weights, based either on existing data/literature or hypothesed choices, generating the network that would be created if those choices were made. Placing limits on the feasible range of resources with which a consumer interacts should lead to more realistic networks: great white sharks not feeding on zooplankton in a marine food web, for example.

The interactions between individual consumers and the resources may be recorded in a range of different ways depending upon the empirical data that are available, and these differences are handled by using the optional data.type argument. Three types of data can be specified:

  1. data.type = "names" (the default value). This is the most common type of data, recording one or more resource species with which an interaction occurred, but without any attempt to quantify the strength of the interaction. For data of this type, resources should simply comprise 1s and 0s, indicating whether an interaction was present or absent respectively: row sums may equal one or be >1 if individual consumers can interact with multiple resources.

  2. data.type = "counts". These data record the number of times an individual consumer interacted with different resource species e.g. the number of times different flower species were visited by an individual pollinator during a 5 minute observation period. When modelling count data there is a choice of whether the total number of interactions (an individual's row sum) can be distributed across all potential resources, which may result in interactions with a different number of resource species (i.e. a change in an individual's degree) or whether the degree is held constant for each individual. This is determined by the additional maintain.d argument: maintain.d = FALSE (the default) does not constrain an individual's degree, whereas maintain = TRUE does.

  3. data.type = "quantities". Quantitative data are obtained from each individual, such as the proportion of a predator's gut contents derived from different prey. The data in consumers can be represented by either proportions (so that the row sum for an individual = 1) or in the native units (so the total <> 1). As for count data, the degree can be free or fixed at the individual consumer level by using the maintain.d argument.

For data types 2 and 3, it does not matter what units are used (e.g. each row does not need to add up to one). The row total will be maintained, so the results are returned in the same units as the original data.

One problem that may arise in specifying the null model is in situations where an interaction is recorded with a particular resource, but that resource was not actually detected in the abundance data (i.e. abundance = 0). This may occur, for example, when a predator eats a rare species that was missed during concomitant sampling of prey abundance: in effect, the predator's 'sampling' was more comprehensive. The implication of this is that the resource species will not be sampled in the null model – a potential source of bias. generate_null_net will issue a warning if it detects this situation. Possible corrective actions include removing that resource species altogether or replacing its zero abundance with a small constant.

Value

Returns an object of class "nullnet", which is a list containing the following components:

rand.data

Data frame containing the results from all of the iterations of the null model

obs.interactions

Interaction matrix summarising the observed interactions (from consumers)

n.iterations

The value of sims i.e. the number of interations of the null model

References

Agusti, N., Shayler, S.P., Harwood, J.D., Vaughan, I.P., Sunderland, K.D. & Symondson, W.O.C. (2003) Collembola as alternative prey sustaining spiders in arable ecosystems: prey detection within predators using molecular markers. Molecular Ecology, 12, 3467–3475.

Davey, J.S., Vaughan, I.P., King, R.A., Bell, J.R., Bohan, D.A., Bruford, M.W., Holland, J.M. & Symondson, W.O.C. (2013) Intraguild predation in winter wheat: prey choice by a common epigeal carabid consuming spiders. Journal of Applied Ecology, 50, 271–279.

King, R.A, Vaughan, I.P., Bell, J.R., Bohan, D.A, & Symondson, W.O.C. (2010) Prey choice by carabid beetles feeding on an earthworm community analysed using species- and lineage-specific PCR primers. Molecular Ecology, 19, 1721–1732.

Pearson, C.E., Symondson, W.O.C., Clare, E.L., Ormerod, S.J., Iparraguirre Bolanos, E. & Vaughan, I.P. (2018) The effects of pastoral intensification on the feeding interactions of generalist predators in streams. Molecular Ecology, 27, 590-602.

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.

See Also

test_interactions, plot_preferences

Examples

null.1 <- generate_null_net(Silene[, 2:7], Silene.plants[, 2:6], sims = 10,
  data.type = "names", summary.type = "sum", c.samples = Silene[, 1],
  r.samples = Silene.plants[, 1])

Plot a bipartite network, colour coding individual links according to whether they are stronger or weaker than expected under the null model

Description

Acts as a wrapper for the bipartite package's plotweb function (Dormann et al., 2008), colour coding the links in the familiar bipartite plots according to whether they are stronger, weaker or consistent with the null model.

Usage

plot_bipartite(
  nullnet,
  signif.level = 0.95,
  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
edge.cols

An optional character vector of length three specifying the colours for links in the bipartite plot: they should represent interactions that are weaker than expected, consistent with the null model and stronger than expected in that order. The default is a colourblind friendly blue, white and red scheme, using colorbrewer's Red-Blue colour scheme (Brewer 2017).
...

Other arguments to be supplied to bipartite's plotweb function.

Details

Extensive options can be passed to plotweb to customise the network plot beyond the colour coding of the links. See the appropriate help file in the bipartite package for details.

Value

No return value, called for side effects.

References

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

Dormann, C.F., Gruber B. & Frund, J. (2008). Introducing the bipartite package: analysing ecological networks. R news, 8, 8-11.

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.

See Also

generate_null_net, bipartite_stats, plotweb

Examples

# Run the null model
set.seed(1234)
sil.null <- generate_null_net(Silene[, 2:7], Silene.plants[, 2:6], sims = 10,
                              c.samples = Silene[, 1],
                              r.samples = Silene.plants[, 1])

# Basic plot
plot_bipartite(sil.null)

# With alternative colour scheme and nodes width in the lower level proportional
#  to mean floral abundance
mean.abunds <- colMeans(Silene.plants[, 2:6])
plot_bipartite(sil.null, signif.level = 0.95, edge.cols = c("#67a9cf",
               "#F7F7F7", "#ef8a62"), low.abun = mean.abunds,
               abuns.type = "independent", low.abun.col = "black",
               high.abun.col = "black", high.lablength = 0, low.lablength = 0)

Plot the resource preferences of a consumer

Description

Takes a 'nullnet' object from running a null model with generate_null_net and plots the observed and expected link strengths for every resource for a selected consumer species (node in the network). There are two styles of plot: the default is a dot plot based on dotchart, whilst the alternative is a bar plot based on barplot. There are arguments in plot_preferences to set some of the graphical parameters, but see the respective help files for dotchart and barplot for further options to customise the plots.

Usage

plot_preferences(
  nullnet,
  node,
  signif.level = 0.95,
  style = "dots",
  type = "counts",
  res.col = c("#67A9CF", "#F7F7F7", "#EF8A62"),
  res.order = NULL,
  l.cex = 1,
  p.cex = 1,
  ...
)

Arguments

nullnet

An object of class nullnet from generate_null_net
node

A string specifying the consumer node (species) whose preferences will be plotted
signif.level

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

An optional string to set whether a dotchart or bar chart is plotted. The default (style = "dots") is a Cleveland dot plot, whilst the alternative (style = "bars") is a bar chart of the type used by King et al. (2010) and Davey et al. (2013).
type

Optional string to specify how preferences are displayed. The default (type = "counts") is the total number of interactions or mean interaction strength, depending upon which one was requested in the original call to generate_null_net using the summary.type argument. The alternative is the standardised effect size (type = "SES"). With type = "counts", confidence limits will be drawn, whilst for the standardised effect size, dashed lines are added at +2 and -2, which is approximately equivalent to a 5% significance level: fill colours for type = "SES" are based on the estimated confidence limits, rather than the +2/-2 thresholds.
res.col

An optional character vector of length three specifying the colours with which to fill the dots or bars representing interactions that are weaker than expected, consistent with the null model and stronger than expected (in that order). The default is a red-blue colour scheme.
res.order

An optional data frame used to set the order in which the resource species are plotted. Should have two columns: the first listing the resource species (names must be identical to those used by generate_null_net) and the second the plotting order (bars will be plotted in ascending order)
l.cex

An optional numeric value to set the size of the labels when using style = "dots". Ignored when style = "bars", as barplot's cex.names argument can be used.
p.cex

An optional numeric value to set the size of the points when when using style = "dots".
...

Other arguments to control basic plotting functions in R, such as lwd, xlab, ylab, main, xlim and ylim.

Details

Plots the preferences for individual consumer species. The bar plot format follows the basic style of King et al. (2010; Figure 3) and Davey et al. (2013; Figure 3).

Value

No return value, called for side effects.

References

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

Davey, J.S., Vaughan, I.P., King, R.A., Bell, J.R., Bohan, D.A., Bruford, M.W., Holland, J.M. & Symondson, W.O.C. (2013) Intraguild predation in winter wheat: prey choice by a common epigeal carabid consuming spiders. Journal of Applied Ecology, 50, 271–279.

King, R.A, Vaughan, I.P., Bell, J.R., Bohan, D.A, & Symondson, W.O.C. (2010) Prey choice by carabid beetles feeding on an earthworm community analysed using species- and lineage-specific PCR primers. Molecular Ecology, 19, 1721–1732.

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.

See Also

generate_null_net, plot_bipartite

Examples

null.1 <- generate_null_net(WelshStreams[, 2:18], WelshStreams.prey[, 2:17],
                            sims = 10, c.samples = WelshStreams[, 1],
                            r.samples = WelshStreams.prey[, 1])

# Basic plots, showing the dot and bar plot styles. Increased lower margin
#   on the bar plot so that names fit
plot_preferences(null.1, "Dinocras", signif.level = 0.95, type = "counts",
                 xlab = "Num. of visits", p.cex = 1.2, lwd = 2)

op <- par(mar = c(9, 4, 4, 2) + 0.1)
plot_preferences(null.1, "Dinocras", style = "bars", signif.level = 0.95,
                 type = "counts", ylab = "Num. of visits")
par(op)

# Same results, this time showing the standardised effect sizes
plot_preferences(null.1, "Rhyacophila", signif.level = 0.95,
                 type = "SES", xlab = "SES")

op <- par(mar = c(9, 4, 4, 2) + 0.1)
plot_preferences(null.1, "Rhyacophila", signif.level = 0.95, style = "bars",
                 type = "SES", ylab = "SES")
par(op)

Flower visitation network from an arable field in the UK

Description

A flower visitation network from an arable field site in the UK, notable for the presence of small-flowered catchfly Silene gallica, a rare arable weed species in the UK. Flower visitors and floral abundance were sampled on 11 occasions in the summer of 2002, with all insect flower visitors (31 taxa) recorded on the flower species where they were observed. Gibson et al. (2006) provide full details of the data and analysis of the results.

Usage

Silene

Format

A data frame with 128 rows and seven columns, one row for each individual pollinator. The first column (Visit) represents the sampling occasion on which the pollinator was collected (V1–V11), the second column (Insect) represents the flower visitor taxon, and the remaining five columns are the five flower species, which were either visited (1) or not (0) by each insect.

Source

Gibson, R.H., Nelson, I.L., Hopkins, G.W., Hamlett, B.J. & Memmott, J. (2006) Pollinator webs, plant communities and the conservation of rare plants: arable weeds as a case study. Journal of Applied Ecology, 43, 246–257.

Flower abundance data to accompany the Silene visitation network

Description

Floral abundance data for the five flower species recorded in the Silene flower visitation network (see Silene) for full details.

Usage

Silene.plants

Format

A data frame with 11 rows and six columns. Each row represents the floral abundance on one sampling occasion. The first column (Visit) lists the codes for the sampling visit (V1–V11), whilst the remaining five variables represent the abundance of each of the flower species.

Source

Gibson, R.H., Nelson, I.L., Hopkins, G.W., Hamlett, B.J. & Memmott, J. (2006) Pollinator webs, plant communities and the conservation of rare plants: arable weeds as a case study. Journal of Applied Ecology, 43, 246–257.

Compare observed interaction strengths in a network to those estimated from a null model

Description

Takes the result of running a null model with generate_null_net and tests whether the observed interactions between consumer species and resource species differ those expected under the null model.

Usage

test_interactions(nullnet, signif.level = 0.95)

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

Details

Statistical significance is determined for each consumer-resource interaction according to whether the observed interaction strength falls outside the confidence limits calculated across the iterations of the null model. Confidence limits are calculated as the 1 – alpha/2 percentiles from the frequency distribution (Manly 2006).

The observed and expected interactions strengths are also compared by calculating the standardised effect size (Gotelli & McCabe 2002):

(observedlinkstrength−expectedlinkstrength)/standarddeviationofthelinkstrengthacrosstheiterationsofthenullmodel(observed link strength - expected link strength) / standard deviation of the link strength across the iterations of the null model

test_interactions will issue warnings when:

  1. The number of iterations of the null model was small <100, as the confidence intervals are unlikely to be reliable

  2. The number of tests >50, due to the increasing risk of Type I errors (incorrectly denoting an interaction as significantly different from the null model). Many networks will contain many more than 100 potential interactions, so the significance of individual interactions should be treated with caution. Some form of false discovery rate correction may be valuable (e.g. the local false discovery rate; Gotelli & Ulrich 2010).

Value

Returns a data frame listing all possible consumer and resource species combinations with the following column headings:

Consumer

The name of the consumer species

Resource

The name of the resource species

Observed

The 'strength' of the observed interaction (e.g. total number of interactions summed across the individual consumers)

Null

The mean strength of the interaction across the iterations of the null model

Lower

Lower confidence limit for the interaction strength

Upper

Upper confidence limit for the interaction strength

Test

Whether the observed interaction is significantly stronger than expected under the null model, weaker or consistent with the null model (ns)

SES

The standardised effect size for the interaction

References

Gotelli, N.J. & McCabe, D.J. (2002) Species co-occurrence: a meta-analysis of J. M. Diamond's assembly rules model. Ecology, 83, 2091–2096.

Gotelli, N.J. & Ulrich, W. (2010) The empirical Bayes approach as a tool to identify non-random species associations. Oecologia, 162, 463–477.

Manly, B.F.J. (2006) Randomization, Bootstrap and Monte Carlo Methods in Biology (3rd edn). Chapman & Hall, Boca Raton.

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.

See Also

generate_null_net, plot_preferences

Examples

null.1 <- generate_null_net(WelshStreams[, 2:18], WelshStreams.prey[, 2:17],
                            sims = 10, c.samples = WelshStreams[, 1],
                            r.samples = WelshStreams.prey[, 1])
test_interactions(null.1, 0.95)

Part of the food web from upland streams in south Wales, UK

Description

Part of a food web from upland streams in south Wales, UK, comprising 85 individuals of two macroinvertebrate predator species (the caddisfly Rhyacophila dorsalis and the stonefly Dinocras cephalotes). Data were collected in Dec 2013 from six streams spread across an agricultural intensity gradient as part of a wider study (Pearson et al. 2018). The data comprise presence or absence of predation by each predator on 16 potential prey taxa determined using next generation sequencing of predator gut contents. There are three accompanying data sets:

  1. WelshStreams.prey, which gives the mean abundance of each prey taxon in each of the six streams (counts of individuals from 3–min kick samples)

  2. WelshStreams.fl which specifies forbidden links (one forbidden link for each predator species, ruling out cannibalism)

  3. WelshStreams.order which ranks the 16 prey taxa in taxonomic order according to the Centre for Ecology and Hydrology's Coded Macroinvertebrate List. This is used for plotting the results.

Usage

WelshStreams

Format

A data frame with 85 rows and 18 variables. Each row represents the gut contents of an individual predator. The first column Stream indicates which of the six streams each predator was collected from, whilst the second column indicates which genus the predator belonged to (Dinocras or Rhyacophila). The remaining 16 columns represent the potential prey taxa, which were either predated (1) or not (0) by each individual predator.

Source

Pearson, C.E., Symondson, W.O.C., Clare, E.L., Ormerod, S.J., Iparraguirre Bolanos, E. & Vaughan, I.P. (2018) The effects of pastoral intensification on the feeding interactions of generalist predators in streams. Molecular Ecology, 27, 590-602.

'Forbidden' links to accompany the upland streams food web

Description

A table specifying trophic links that are allowed when modelling part of the food web from upland Welsh stream containing the two macroinvetebrate predators Rhyacophila dorsalis and Dinocras cephalotes (see WelshStreams). There is one forbidden link for each predator species, preventing cannibalism from being included in the null model: this is because the method used to screen predator gut contents for prey (next generation sequencing) cannot distinguish between predator and prey of the same species. Both predators are generalists, so all other trophic links are permitted.

Usage

WelshStreams.fl

Format

A data frame with 2 rows and 17 columns, each row representing one of the two predator genera. The first column (Predator) indicates the predator genus, whilst columns 2–17 indicate which of the 16 potential prey taxa can be consumed (1) or are forbidden (0).

Source

Pearson, C.E., Symondson, W.O.C., Clare, E.L., Ormerod, S.J., Iparraguirre Bolanos, E. & Vaughan, I.P. (2018) The effects of pastoral intensification on the feeding interactions of generalist predators in streams. Molecular Ecology, 27, 590-602.

Additional data to assist with plotting outputs from WelshStreams

Description

The rank order of 16 prey taxa in WelshStreams on the Centre for Ecology and Hydrology's Coded Macroinvertebrate List https://www.ceh.ac.uk/services/coded-macroinvertebrates-list. This is used primarily for controlling the order in which prey taxa are plotted with plot_preferences.

Usage

WelshStreams.order

Format

A data frame with 16 rows and two columns:

Taxon

The names of each prey taxon

CEH

The rank order of the taxa based on the Centre for Ecology and Hydrology's Coded Macroinvertebrate List

Source

Pearson, C.E., Symondson, W.O.C., Clare, E.L., Ormerod, S.J., Iparraguirre Bolanos, E. & Vaughan, I.P. (2018) The effects of pastoral intensification on the feeding interactions of generalist predators in streams. Molecular Ecology, 27, 590-602.

Macroinvertebrate abundance to accompany part of the food web from upland streams in south Wales, UK

Description

The abundance of 16 potential macroinvertebrate prey taxa to accompany the food web data in WelshStreams.

Usage

WelshStreams.prey

Format

A data frame with 6 rows and 17 variables. Each row represents the abundance of individual macroinvertebrate taxa in each of the six streams. Column 1 contains the stream codes, whilst columns 2–17 represent the abundance of each macroinvertebrate taxon summed across three 1-minute kick-samples in each stream.

Source

Pearson, C.E., Symondson, W.O.C., Clare, E.L., Ormerod, S.J., Iparraguirre Bolanos, E. & Vaughan, I.P. (2018) The effects of pastoral intensification on the feeding interactions of generalist predators in streams. Molecular Ecology, 27, 590-602.