Package 'bipartite'

Description

Bipartite provides functions to visualise webs and calculate a series of indices commonly used to describe pattern in (ecological) networks, a.k.a. webs. It focusses on webs consisting of only two levels, e.g. pollinator-visitation or predator-prey webs. Visualisation is important to get an idea of what we are actually looking at, while the indices summarise different aspects of the webs topology.

Details

Note: We only had three types of bipartite webs in mind when starting this package: seed-disperser, plant-pollinator and host-parasitoid systems. In how far it makes sense to use these functionalities for other systems (or indeed even for these systems) lies in the hands of the user. Please refer to the literature cited for details on the theory behind the indices.

Networks can be either binary (0/1 or FALSE/TRUE matrices) or quantitative (matrices containing estimates of pairwise interaction strength, usually assumed here to be interaction frequency).

Input for most analyses is an interaction matrix of m nodes (= species) from one group (“higher”) with n nodes (= species) from another group (“lower”), i.e. a n x m matrix, where higher level nodes are in columns, lower level nodes in rows. Column and row names can be provided. This is fundamentally different from “one-mode” networks, which are organised as k x k matrix, i.e. one group of nodes only, in which each node can link (= interact) with each other. Such a format is incompatible with the functions we provide here. (Note, however, that functions as.one.mode and web2edges are convenience functions to morph bipartite networks into one-mode webs. Furthermore, some indices build on one-mode networks and are called from bipartite.)

Before you start with the network, you have to get the data into the right shape. The function frame2webs aims to facilitate this process. Arranging a web, e.g. by size, is supported by sortweb.

The typical first step is to visualise the network. Two functions are on offer here: one (visweb) simply plots the matrix in colours depicting the strength of an interaction and options for re-arranging columns and rows (e.g. to identify compartments or nesting). The other function (plotweb) plots the actual web with participants (as two rows of rectangles) connected by lines (proportional to interaction strength). Both can be customised by many options.

The second step is to calculate indices describing network topography. There are three different levels this can be achieved at: the entire web (using function networklevel), at the level of each group (also using function networklevel) or the individual node (= species; thus somewhat inconsistently called specieslevel). Most other functions in the package are helpers, although some can be called on their own and return the respective result (dfun, H2fun and second.extinct with slope.bipartite).

The third step is to compare results to null models. Many interaction matrices are very incomplete snapshots of the true underlying network (e.g. a one-week sampling of a pollination network on a patch of 4 x 4 meters). As a consequence, many species were rarely observed, many are singletons (only one recording). To make analyses comparable across networks with different sampling intensity and number of species per group, we need a common yardstick. We suggest that users should use a null model, i.e. an algorithm that randomises entries while constraining some web properties (such as dimensions, marginal totals or connectance). The function nullmodel provides a few such null models, but this is a wide field of research and we make no recommendations (actually, we do: see Dormann et al. 2009 and Dormann 2011, both shipping in the doc-folder of this package). You can also simulate networks using genweb or null.distr.

Finally, bipartite comes with 23 quantitative pollination network data sets taken from the NCEAS interaction webs data base (use data(package="bipartite") to show their names) and it has a few miscellaneous functions looking at some special features of bipartite networks (such as modularity: computeModules or potential for apparent competition: PAC).

See help pages and vignette for details and examples.

For an overview of other computing resources, data, books, journals etc. check out this page: https://github.com/briatte/awesome-network-analysis.

versionlog

Please see help page versionlog for all changes and updates prior to version 2.00. This page will only list most recent changes.

• 2.21 (XX-XXX-2024)

  Code changes to as.one.mode.

  Until version 2.21, projections to higher and lower level were based on reasoning what the correct weights should be from the perspective of an ecologist: If, say, species A and B interact with species a-z, then the link weight would be the sum of the minima of the two vectors A with a-z and B with a-z. In other words, the minimal overlap. In network science, the projection is defined differently, however, namely as the maximum! Thus, bringing bipartite's as.one.mode closer to common mathematical practice, we now use the proper definition as default. The old definition remains available by setting legacy=TRUE. The new definition is: $AA^T$, with diagonal set to 0. (Taken from both Thurner et al.'s 2018 and Wikipedia's entry on the Laplacian matrix).

• 2.20 (19-May-2024)

  Code changes to

  plotweb, plotweb2, visweb and compart as well as the namespace, due to changes in the cca-function in vegan. Many thanks to Jari Oksanen (maintainer of vegan) to provide these patches!

  Added new option effective to networklevel:

  With this option, diversity, H2' and evenness indices are turned into “effective” diversity and evenness indices, by exponentiating them. It has been repeatedly argued that Shannon's H is ecologically difficult to interpret and should instead be exponentiated to yield the “effective number of species, if all were equally abundant” (e.g. Jost 2006). The same logic goes for evenness (Jost 2010) and, by extension, for H2'. Since H2' then becomes an index with data-dependent upper bound, rather than one on [0,1], this version may not fly. For diversity, exponentiating will yield the same values as indices “vulnerability” and “generality”, which is why we had removed that option from an earlier version (and now it's back). So largely this option is useful for “interaction evenness” and for experimenting.

• 2.19 (29-Nov-2023)

  Fixed missing any causing a problem when plotting modules,

  reported by rubenroos and Celia Ferriol Gonzalez: many thanks!

  When a matrix has more columns/rows than the sum of entries, r2dexternal

  will not work without external abundances. The fix is incomplete, as it is only applied to columns in the moment, and not to vaznullexternal either. Thanks to Emilie Ellis for reporting!

  Warning fix in internal function isCorrectModuleWebObject:

  Incorrect testing of dimensions of modularity object. Thanks to Frazer Moore for reporting.

• 2.18 (22-Oct-2022)

  Bug fix in robustness:

  For large matrices, the (too short) subdivision length and the possible non-zero starting values caused an error. Thanks to Rafael Pinheiro for reporting.

  Small semantic

  fixes newly picked up by sterner CRAN checks (e.g. non-UTF in comment; escaped ampersand in title).

• 2.17 (release date: 12-Apr-2022)

  New null model for "compound network structure" using restrictednull:

  This function, contributed by Gabriel Felix, Rafael Pinheiro, and Marco Mello from the Ecological Synthesis Lab (SintECO) in São Paulo, constructs null model expectations for networks with modules. So far, nestedness could not be properly tested for within null model modules, only at the level of the entire network. This function uses information from previously identified modules (typically using computeModules) to generate expectations based on marginal totals and observed connectivity. It builds on vaznull in that respect, but adds the modular structure.

  Major rehaul of mgen:

  1. the biggest change is that keep.species=TRUE now respects the probabilities of the input web (before it had used marginal totals) already for the first interaction of each species, and tries to minimize the number of interactions assigned in this first part of the function. 2. the main part of the function has been changed, not using a while-loop anymore and thus dropping the argument trials. 3. handling of autotransfrom has been slightly changed, avoiding unnecessary warnings. 4. the output web now keeps dimnames of input web.

  Slight changes to specieslevel,

  where the weighted betweenness values could be wrongly placed if the web contained compartments without indirect links. Thanks to Marco Mello for drawing our attention to this!

  computeModules used to remove

  all-1 rows and columns in a binary network, as they contain no information on modules. However, this affects the modularity value. Now the function always keeps the full network. Note that all-0-values are still removed. Thanks to Elvira D'Bastiani for reporting this problem!

  Substantial speed boost to vaznull,

  thanks to an improvement suggested by Rafael Pinheiro!

  Bug fix in webs2array,

  which caused problems when called within another function.

  Added index modularity (= Newman's Q) to networklevel.

  No options are available, hence this value is the likelihood of the default setting of computeModules.

  Bug fix in index PSI in specieslevel,

  where the beta-exponent was on the wrong matrix, and hence it did not yield species strength for beta=0.

  Retired binmatnest as called by nestedness.

  Binmatnest was one of the first nice nestedness algorithms, implemented in C++. It has been kept merely for historical reasons, as vegan's nestedtemp is more reliable. We finally decided to kick binmatnest out, using this function as legacy-call to nestedtemp and leaving the legacy help page. (Also makes package maintenance a bit easier: one C++ function less to think about.)

  Added text-option to plotPAC.

  Species names have a tendency to always be in the way, and too long. Therefore the original function only plotted numbers. Now we added the option to plot (and scale and move) labels for each species. Not nice, but practical.

  Function networklevel now

  calls vegan's nesteddisc when computing the index "discrepancy". That function tries to handle ties in the data consistently, although for webs with many columns (or rows) with the same number of links this will still lead to slightly different values. Thanks to Valentin Stefan for drawing our attention to this! Also, we added an explicit note of this behaviour in networklevel.

  Bug fix in r2dexternal and vaznullexternal:

  Sometimes did not yield the correct row/column sums, when margins were extremely skewed.

  Addressed long-standing confusion in nested,

  which reports some indices in [0,1], others in [0, 100] (i.e. as percent). Thanks to Jari Oksanen for reminding me of this point. All but one now report in the 0-100% range. While fixing this, also added WNODA (based on nest.smdm) to the fray.

• 2.16 (release date: 08-Jan-2021)

  Bug fix in H2fun:

  threw an error when H2_integer=TRUE. Thanks to mxdub for finding and fixing this! (Sorry that I managed to click on “comment and close” before “confirm accept merg”; this github interaction is still somewhat new to me.)

  Bug fix in betalinkr:

  Now standardization to proportions also works for empty webs as division by zero is avoided. 2. specmx.higher.unique can now be assessed even for 1-link-networks, as setting drop=FALSE keeps the dimensions of the matrix. Thanks to Benjamin Schwarz for providing these fixes! (And don't ask me why the pull request on github does not show.)

  Added multicolour-option to arrow.col in plotPAC,

  following a question by Horacio Silva. We can now colour each arrow of the plot individually, although the sequence of colours provided may require some fiddling around.

• 2.15 (release date: 04-Apr-2020)

  A pair of new functions for plotting: sortmatrix and plotmatrix,

  both provided by Rafael Pinheiro and Gabriel Felix from the University of Campinas in Brazil. The functions' scope is to plot interaction networks of nested, modular and mixed topology (Pinheiro et al. 2019). As plotting is not the forte of bipartite so far, and these two functions help to add a bit of plotting facilities. Many thanks for contributing!

  Bug fix in robustness:

  in my previous updates of the discontinued class-issues I managed to omit a crucial “!” in the code. Thanks to Hanlun Liu and Felix Neff for reporting!

  Bug fix in extinction:

  for sparse networks, the function sometimes returned a vector rather than a matrix, due to incorrectly dropping a dimension. Thanks to Felix Neff for reporting and providing the solution!

  Expanded help of as.one.mode:

  in particular the way the weights were computed was not documented at all, as pointed out by Lennart Dittmer. This is now rectified and also the R-code now features in-line comments as to what is happening at each step.

• 2.14 (release date: 07-Jan-2020)

  Updates

  of betalinkr-options.

  Future R-version 4.x.x

  requires discontinuation of class(x) == "y"-like code (rather using is(x, "y") or inherits(x, "y")). Updated accordingly.

  C++-style changes

  requiring identifyModules-Arguments to be labelled slightly differently. Impossible to check without setting up a linux chain, but still reason for CRAN not to accept.

• 2.13 (release date: 21-May-2019)

  Several small fixes,

  e.g. check for binary networks in nullmodel failed if values < 1 were in the matrix.

  Added a lengthy vignette,

  illustrating the use of the package.

  (Small) bug fix in empty:

  something was stupidly wrong for matrices of only one row or column. Spotted by Benjamin Schwarz, thanks!

  New function vaznullexternal,

  as wished by Matt Funaki. This is the “normal” vaznull-nullmodel, but now external abundances for either or both groups can be provided. Modelled on r2dexternal.

  Important bug fix and new option in webs2array:

  name indexing was wrong, so that entries were entered in wrong cells. Also, the function now also accepts a weblist as input.

  New function betalinkr:

  it allows comparison of networks and partitioning of network dissimilarity. Based on betalink package/paper by Tim Poisot, but more integrated into the bipartite package, and importantly implements many more features and corrected partitioning approaches. Two more new functions come with it: array2linkmx, betalinkr_multi.

  New function decimalr2dtable:

  it allows to simulate matrices with the same marginal totals as the input, but for non-negative, non-integer inputs. Doing so, it “smears” out the entries over the entire matrix and will hence be meaningless for any index comparison which responds to matrix filling. An attempt to deal with webs composed of rates rather than observed interactions. Useful probably only in a very few cases, as marginal totals are unlikely to be interpretable as abundance-activity, and hence implying a very different kind of null model to nullmodels.

• 2.12 (release date: 11-Mar-2019)

  New function nest.smdm

  by Rafael Pinheiro, Gabriel Felix, Marco Mello, and the team of the Ecological Synthesis Lab, University of São Paulo, which computes the nestedness measure NODF (as present in vegan) more flexibly, by allowing the matrix to be sorted not only by number of filled cells (think: binary networks), but also by absolute marginal totals. NODF does not work for completely filled matrices, but this version (called NODA) does. Also, nest.smdm compute nesting within modules, if module identities are provided (e.g. by computeModules and the new little helper function module2constraints). All these metrics are computed for binary or weighted networks.

  Function NOS

  yields NA when one or more nodes are 0. The original equation allows an alternative way to compute NOS, which has been implemented by tchen98: many thanks!

• 2.11 (relase date: 12-Jul-2018)

  Change of defaults in metaComputeModules

  , from DormannStrauss to Beckett. Beckett's algorithm is far less variable in its performance, thus I assumed that one would not actually need metaComputeModules for it at all. However, also Beckett is not foolproof and benefits from a few re-runs with different starting configurations. Now defaults are consistent with computeModules. Thanks to Laura Burkle for raising the issue.

  Bug fix in nested

  , which didn't correctly pass through the normalised-argument for index "C score". Also the naming of "C score" (rather than previously "C.score") was changed for consistency with networklevel. Many thanks to Carlos Zamora-Manzur for reporting!

  Deprecation of the command register in C++17

  required attention in the MersenneTwister.h-code used in computeModules. Thanks to Brian Ripley, for the R Core Team, for notifying all maintainers using this command in advance of future CRAN-submission problems!

• 2.10 (release date: 20-Dec-2017)

  Removed option weighted

  from CC, which had no effect on the way sna::closeness computes the value. Thanks to Thais Zanata for making me aware of this!

  Fixed bug in option rescaled

  of CC, which did not properly rescale values so that they sum to 1. Thanks to Thais Zanata for making me aware of this!

  Added NODF

  to the indices available in networklevel.

  Added network of Olito & Fox (2015)

  as olito2015; data from dryad (URL given in help page).

• 2.09 (release date: 30-Jun-2017)

  Fixed type of object returned by computeModules,

  when using method="DormannStrauss", which I had broken after changing the default. Many thanks to Abdul Shakoor for reporting. Also added an error catcher to exclude, from binary webs, species that interact with every other species (i.e. are all 1; all-0 were already excluded).

  Fixed imprecise explanation in plotweb's

  low/high.spacing, which now correctly describes its effect on the horizontal space within a level. (Thanks to Jeff Ollerton for reporting.)

• 2.08 (release date: 30-Mar-2017)

  New modularity algorithm called by computeModules.

  Although the excellent algorithm DIRT_LPA_wb_plus by Stephen Beckett has been around for a year, I never managed to find the time to put it into bipartite. By now, Stephen has even written a wrapper code so that the output is fully compatible with existing code for plotting (plotModuleWeb) there was really no argument left to postpone it. Stephen's DIRT_LPA_wb_plus will be the new default, replacing 'QuanBiMo', which remains available under method='DormannStrauss'. While DIRT could be called recursively, thereby making modules-within-modules computable, this is not packaged yet. So currently the much slower DormannStrauss-option is the only way to get recursive modules. Many thanks to Stephen for making this code available!

  networklevel and grouplevel inconsistently

  returned different values for secondary extinction, because the former by default purged empty columns/rows, while the latter didn't. It does now. Thanks to Gianalberto Losapio for bringing this to my attention.

• 2.07 (release date: 08-Nov-2016)

  Bug fixed in vaznull,

  filled the matrix with 1s instead of 0s (although it was a ‘sophisticated’ logical mistake I made, not a simple typo). Thanks to Sandra Bibiana Corea for reporting!

  Small patch in C++-code of binmatnest

  for compatibility with clang. Thanks to Brian Ripley for fixing one of these C++-things that I never will understand! (In this case, the original code (by Miguel Rodríguez-Gironés) defined a pointer to "vector", which caused ambiguities in which "vector" should be used during compilation: the such defined pointer, or the std::vector.)

  Smaller typographic

  and referencing corrections/additions (e.g. in plotPAC).

• 2.06b (release date: 10-May-2016)

  Some explanation addded to czvalues,

  where a z-value of NA is returned if a species is alone (in its trophic level) in a module. This is due to the way z-values are computed, and not a bug.

  Function nestedcontribution

  was not exported in the namespace. Fixed. Thanks to various people reporting this.

• 2.06 (release date: 29-Sep-2015)

  Bug fix in C.score,

  which did not compute the maximum number of possible checkerboards correctly, and hence let the normalised C-score to be incorrect. Now it uses a brute-force approach, which works fine but takes its time.

  Function nestedcontribution

  was not exported (i.e. not listed in the namespace file). Fixed. Thanks to Wesley Dátillo for reporting.

  Help page of specieslevel

  now correctly described a species' degree as sum of its links. Thanks to Bernhard Hoiß for the correction!

  C++-warnings addressed:

  outcommented some unused variables in dendro.h and removed some fprintf-warnings in bmn5.cc

  Little bug fix in vaznull:

  Threw an error when matrix was without 0s. Thanks to Thais Zanata for reporting.

• 2.05 (release date: 24-Nov-2014)

  New function nestedcontribution

  which computes the contribution of each species to the overall nestedness, based on Bascompte et al. 2003 and as used by Saavedra et al. 2011. Many thanks to Daniel Stouffer for contributing this function!

  New function mgen:

  this function is based on R-code written by Diego Vázquez (many thanks for sending the code), with a bit of brushing up options by CFD. The function takes a probability matrix generated by whatever mechanism and builds a null model from it. This is a niffty little idea, making null modelling concerned with generating ideas on what makes an interaction probable and leaving the step of producing and integer-network of simulated interactions to this function.

  minor fixes in networklevel

  “weighted connectance” was only returned when “linkage density” was in “index” call; now also available on its own. Also sligthly revised the help file.

  nested with option weighted NODF called the unsorted version of this function,

  while calling the same index in networklevel called the sorted. This is not nice (although not strictly wrong). Now both call the sorted version and users have to directly invoke nestednodf for the unsorted option. Many thanks to Julian Resasco for reporting!

  Changes to the help page of vaznull:

  I (CFD) misread the original paper introducing this null model and hence assumed thatvaznull would constrain marginal totals and connectance. However, this was not intended in Diego Vázquez original implementation and never stated anywhere (except in the help pages of this function here in bipartite). Hence, the help pages were changed to now reflect both intention and actual action of this function. This also means that currently only one null model with constrained marginal totals and connectance is available: swap.web. Many thanks to Diego for clearing this up!

  Some example code had to be re-written

  to adapt to the upcoming/new structure of vegan, which got rid of function commsimulator (replaced by simulate). Many thanks to Jari Oksanen for informing me about this!

  Added an error message

  to function second.extinct for the case that a user wants to provide an extinction sequence for both trophic levels. There is no obvious way to simulate this across the two groups, and hence it is not implemented. Also added error messages for non-matching vector/web dimensions and alike.

• 2.04 (release date: 25-Mar-2014)

  R-C++-communication bug fixed in computeModules:

  This bug has been a constant thorn in my side. Somehow the C-code behind computeModules could only be called once. On second call, it returned an error because somehow it kept some old files in memory. So far, I used a work-around (unloading and re-loading the dynamic library), which only worked on Windows and Mac. I still don't fully understand it, but thanks to Tobias Hegemann (whom I paid for being more competent than myself) we now have a function running bug-free on all platforms. (Deep sigh of relief.)

  The call of index “functional complementarity” through networklevel did not work.

  Fixed this legacy issue, which was due to a confusion created by the index' earlier name of “functional diversity”.

  Help page to specieslevel gave incomplete name for one index:

  Should be interaction push pull; also the function itself had the “push pull”-bit messed up. Thanks to Natacha Chacoff for reporting!

  Sequence of indices differed between lower and higher level. (Fixed.)

  Both should be the same and should fit the description in the help file. Thanks to Jimmy O'Donnell for reporting!

• 2.03 (release date: 15-Jan-2014)

  Some ghost text led to conflicts with the updated package checking.

  Ghost text deleted. Thanks to Brian Ripley of the R-Team and CRAN for not only reporting the issue but also pointing to its solution!

  Option empty.web added to specieslevel:

  Similar to the argument in networklevel; non-interacting species from the network were always excluded so far; new option FALSE not fully tested yet.

  Minor bug fix in specieslevel:

  “pollination support index” returned “PSI”; “PDI” now referenced correctly as “paired differences index”.

  Simplification in grouplevel and correspondingly in networklevel:

  Previously, index="generality" or "vulnerability" was identical to "effective partners" with option weighted=TRUE, but different for weighted=FALSE (to which only "effective partners" responded). We reduced this to one index called "generality" or "vulnerability" (depending on the focal group), but which will now give the non-weighted mean if option weighted=FALSE. It can still be called by "effective partners" for backward compatibility.

  Function grouplevel used fd wrongly!

  Instead of returning the value for rows, it returned the functional diversity for columns (and vice versa). We also used the opportunity to rename the index to its correct name: “functional complementarity” and the function to fc. Help pages for fc and grouplevel were adapted accordingly. Thanks to Mariano Devoto for pointing out this mistake!

  New index “weighted connectance” in function networklevel:

  This index is simply computed as linkage density divided by number of species in the network. Note that using empty.web=TRUE will affect this value (which is intended). Thanks to Becky Morris for suggesting to add this index here.

  Help page for function PDI corrected.

  Thanks to Timothy Poisot for reporting some issues in the help page.

• 2.02 (release date: 30-Sep-2013)

  Glitch fixed in grouplevel (thus also affecting networklevel).

  Networks with only one species in one of the two levels resulted in errors, rather than simply return NA for C-score and secondary extinction computation. Thanks to whoever it was for reporting (at the INTECOL workshop).

  Minor bug fixes in specieslevel:

  Gave error messages for closeness and betweenness if the network had no shortest path. Now returns a warning and NAs instead. Reported: JF.

  Minor bux fix in networklevel:

  Failed to work when an index was listed twice in the function call. Reported: JF.

  New function r2dexternal:

  This function is a null model algorithm like Patefields (r2dtable, but it excepts externally measured abundances to compute the null model-expectation. Experimental.

  Memory leak in computeModules fixed.

  Because some object was not deleted, memory consumption of this function shot through the roof (with time). Since R has a somewhat weird way of handling memory, I think that also subsequent operations were slower (because the dynamically expanded memory is not being shrunken again, which is a problem if you use the hard drive as RAM). Thanks to Florian Hartig for investing the time to fix it!

• 2.01 (release date: 28-Jun-2013) This release features smoothing of various glitches that were introduced when we cleaned up the code for version 2.00.

  New index for specieslevel:

  Computes the nestedness rank (as proposed by Alarcon et al. 2008). Can also be employed directly using the new function nestedrank with options for weighting for number of interactions per link, normalising the rank and different method to compute the nestedness-arranged matrix.

  Polishing specieslevel:

  Now returns an error message if the index is not recognised, instead of an empty list.

  Function plotweb

  received an option to plot additional individuals of a species in different ways. For a host-parasitoid network, some hosts are not parasitised. This data vector can now be interpreted in two ways, making the plotting function a bit more flexible.

  Function degreedistr

  can now be invoked for each level separately. Also arguments can be passed to the plotting options.

  New data set junker2013:

  a nice and large pollination network. Thanks to Robert Junker for providing this data set!

  Fixed computation of secondary extinction slopes for both levels simultaneously

  for random extinction sequences. This was so far not possible, because the function did not combine extinction sequences of different lengths. This was simply an oversight, reported by Richard Lance. (Thanks!)

• 2.00 (release date: 15-Mar-2013) A new version number usually indicates substantial changes. In this case, we have re-named and re-grouped some of the output of networklevel and specieslevel for greater consistency and transparency. Beware! Running the same functions now (2.00 and up) will yield different results to <2.00 (because the same values are now in a different sequence).

  We also started carefully renaming indices and re-writing help files. The main reason is that we started this work thinking of pollination networks. Over time, however, other types of ecological networks came into focus, and now also non-ecological networks are on the table. Thus, we started (and shall continue) referring to lower and higher levels, rather than plant and pollinators, hosts and predators or even trophic levels. Thus, in our emerging nomenclature the two levels are referred to as “groups” (their members remain “species” interacting with their “partners” in the other group).

  Please read (or at least skim) the help pages before using a function of version 2.00 for the first time.

  In function specieslevel indices can now be computed for levels separately (or together). Few user-visible changes, but complete re-structuring under the hood. Option species number was moved to grouplevel as number of species.

  In the new function grouplevel we collected all indices that can be computed for each of the two groups (i.e. trophic or other levels). Indices can be computed for each group separately or for both simultaneously. All group-level indices are also accessible through networklevel!

  In the new function linklevel we collected all indices that can be computed for each cell of the bipartite matrix. Currently, there are few such indices, however.

  In function networklevel we dropped the plotting options. Users wanting to plot degree distributions or extinction slopes are encouraged to use the functions degreedistr and slope.bipartite, respectively.

  Furthermore, due to licensing issues, we copy-pasted several functions from the package tnet, created and maintained by Tore Opsahl, to bipartite. We have so far called these functions from tnet, but only recently did R start to enforce license compatibility, which caused this step (bipartite being GPL and tnet being CC by-NC 3.0). We are really very grateful to Tore for allowing us to include the following functions: as.tnet, betweenness_w, closeness_w, clustering_tm, distance_w, symmetrise_w, tnet_igraph.

  Here a more detailed list of changes:

  networklevel

  • Function call and output now more consistent in naming and sequence. When higher and lower level indices are given (e.g. extinction slopes, number of shared partners), the first will always be the one referring to the property of the lower level. From a pollinator network perspective, the first value in such a pair describes a plant-level index, the second a pollinator-level index.

  • Indices mean interaction diversity dropped from networklevel. We found no reference to this metric and saw little use for it. It is very similar to vulnerability/generality and can easily be computed from the output of specieslevel as mean(specieslevel(web, index="diversity")).

  • Now also accepts non-integer values as input. The argument H2_integer will then automatically be set to FALSE. Will return NA for those indices that cannot be computed (e.g. Fisher's alpha). As a knock-on effect, H2fun had to be slightly adapted to round to machine precision when searching for H2min. (A somewhat technical detail, but making H2fun getting caught sometimes.)

  New function grouplevel

  in which we collected indices that can be computed for each of the two groups (i.e. trophic or other levels). Indices can be computed for each group separately or for both simultaneously. All group-level indices are also accessible through networklevel!

  New function linklevel

  in which we collect indices that can be computed for each cell of the bipartite matrix.

  New option to PDI:

  normalise=FALSE offers the option of using the index as originally proposed, although we prefer to use TRUE and made this the default.

  Corrected network bezerra2009.

  Network was actually the transpose of the correct network and hence wrongly had plant species as columns.

  New function endpoint

  computes end-point degrees following Barrat et al. (2004); one of the indices computed at linklevel.

  New function frame2webs

  helps organising data into one or more webs.

  New function webs2array

  helps organising webs into one array.

  Function specieslevel

  gained two new indices (thanks to Jochen Fründ): proportional similarity and proportional generality. See help page of that function for details.

  New function npartite

  Experimental function to analyse more-than-2-level networks.

  visweb

  now obeys the label size to make sure labels are always in the plotting area. Thanks to Zachary Grinspan for drawing our attention to this issue.

  Little bug fix in second.extinct

  Function failed for argument participant="both" because I filled the extinction sequence with the wrong number of 0s (to achieve always the same dimensionality of results in repeated runs). Thanks to Carine Emer for reporting!

  specieslevel

  failed to work for non-matrix data (i.e. data.frames). It now coerces data.frames to matrix as a first step and hence should work also on data.frames. Thanks to Marina Wolowski for drawing our attention to this problem.

  Minor bug fix in dfun:

  When external abundances were provided with a 0 in it, dfun could throw up Inf-values. Reported by Indrani Singh and fixed by Jochen Fründ.

  Settings for functions called by nested

  are now enshrined in stone. The initial reason was to set only the default for one function (nestedness) to a faster setting (null.models=FALSE), but then I decided to restrict all settings to the defaults of the functions called (except for this one option).

  Bug fix for the rarely used function null.t.test:

  Did not work if only one index was given.

Author(s)

Carsten F. Dormann, Jochen Fründ and Bernd Gruber, with additional code from many others (referred to in the respective help file), noticeably from Tore Opsahl's tnet package.

Maintainer: Carsten Dormann [email protected]

References

Alarcon, R., Waser, N.M. and Ollerton, J. 2008. Year-to-year variation in the topology of a plant-pollinator interaction network. Oikos 117, 1796–1807

Almeida-Neto, M. and Ulrich, W. (2011) A straightforward computational approach for measuring nestedness using quantitative matrices. Environmental Modelling & Software, 26, 173–178

Bascompte, J., Jordano, P. and Olesen, J. M. (2006) Asymmetric coevolutionary networks facilitate biodiversity maintenance. Science 312, 431–433

Beckett, S.J. 2016. Improved community detection in weighted bipartite networks. Royal Society open science 3, 140536

Bersier, L. F., Banasek-Richter, C. and Cattin, M. F. (2002) Quantitative descriptors of food-web matrices. Ecology 83, 2394–2407

Blüthgen, N., Menzel, F. and Blüthgen, N. (2006) Measuring specialization in species interaction networks. BMC Ecology 6, 12

Blüthgen, N., Menzel, F., Hovestadt, T., Fiala, B. and Blüthgen, N. (2007) Specialization, constraints, and conflicting interests in mutualistic networks. Current Biology 17, 1–6

Corso G., de Araújo A.I.L. and de Almeida A.M. (2008) A new nestedness estimator in community networks. arXiv, 0803.0007v1 [physics.bio-ph]

Dalsgaard, B., A. M. Martín González, J. M. Olesen, A. Timmermann, L. H. Andersen, and J. Ollerton. (2008) Pollination networks and functional specialization: a test using Lesser Antillean plant-hummingbird assemblages. Oikos 117, 789–793

Devoto M., Bailey S., Craze P. & Memmott J. (2012) Understanding and planning ecological restoration of plant-pollinator networks. Ecology Letters 15, 319–328

Dormann, C.F., Fründ, J., Blüthgen, N., and Gruber, B. (2009) Indices, graphs and null models: analysing bipartite ecological networks. The 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

Galeano J., Pastor J.M. and Iriondo J.M. (2008) Weighted-Interaction Nestedness Estimator (WINE): A new estimator to calculate over frequency matrices. arXiv 0808.3397v1 [physics.bio-ph]

Jost, L. (2006). Entropy and diversity. Oikos, 113, 363–375. https://doi.org/10.1111/j.2006.0030-1299.14714.x

Jost, L. (2010). The relation between evenness and diversity. Diversity, 2, Article 2. https://doi.org/10.3390/d2020207

Martín Gonzáles, A.M., Dalsgaard, B. and Olesen, J.M. (2009) Centrality measures and the importance of generalist species in pollination networks. Ecological Complexity, 7, 36–43

Memmott, J., Waser, N. M. and Price, M. V. (2004) Tolerance of pollination networks to species extinctions. Proceedings of the Royal Society B 271, 2605–2611

Morris, R. J., Lewis, O. T. and Godfray, H. C. J. (2004) Experimental evidence for apparent competition in a tropical forest food web. Nature 428, 310–313

Morris, R. J., Lewis, O. T. and Godfray, H. C. J. (2005) Apparent competition and insect community structure: towards a spatial perspective. Annales Zoologica Fennici 42, 449–462.

Müller, C. B., Adriaanse, I. C. T., Belshaw, R. and Godfray, H. C. J. (1999) The structure of an aphid-parasitoid community. Journal of Animal Ecology 68, 346–370

Pinheiro, R.B.P. et al. 2019. A new model explaining the origin of different topologies in interaction networks. Ecology 100, 1–30

Poisot, T., Lepennetier, G., Martinez, E., Ramsayer, J., and Hochberg, M.E. (2011a) Resource availability affects the structure of a natural bacteria-bacteriophage community. Biology Letters 7, 201–204

Poisot, T., Bever, J.D., Nemri, A., Thrall, P.H., and Hochberg, M.E. (2011b) A conceptual framework for the evolution of ecological specialisation. Ecology Letters 14, 841–851

Thurner, S., Hanel, R. and Klimek, P. (2018) Introduction to the Theory of Complex Systems. Oxford University Press, Oxford

Tylianakis, J. M., Tscharntke, T. and Lewis, O. T. (2007) Habitat modification alters the structure of tropical host-parasitoid food webs. Nature 445, 202–205

Vázquez, D. P. and Aizen, M. A. (2004) Asymmetric specialization: A pervasive feature of plant-pollinator interactions. Ecology 85, 1251–1257

Vázquez, D.P., Chacoff, N.,P. and Cagnolo, L. (2009) Evaluating multiple determinants of the structure of plant-animal mutualistic networks. Ecology 90, 2039–2046.

Examples

## Not run: 
data(Safariland)
plotweb(Safariland)
visweb(Safariland)
networklevel(Safariland)
specieslevel(Safariland)

## End(Not run)

Description

Function to turn an array with sites as third dimension into a web by link matrix (e.g. sites X links). This is the "link community matrix" to use for dissimilarity calculations. Mostly just a helper function for betalinkr.

Usage

array2linkmx(webarray)

Arguments

Details

This function converts the two-dimensional adjacency matrices (i.e., bipartite webs) to one-dimensional vectors (similar to what network people call “edgelists”). These vectors become rows of a matrix (which has one row per web). This makes the data available to community ecology methods, e.g. those offered by the vegan package. Links are treated equivalently to species in a “normal” community analysis (note that it makes no difference whether one or both partner of an interaction differ, in both cases the link has a different identity). The function is used here mostly as a helper for interaction dissimilarity calculations with betalinkr.

dimnames are optional but recommended for the webarray. Names of the third dimension will become rownames in the output. Colnames (i.e. names of links) will be created from dimnames[[1]] (“lower species”) and dimnames[[2]] (“higher species”), separated by “__” (double underscore).

Value

A matrix with one row per web and one column per link (i.e. per combination of lower and higher species). All-zero columns may often be included.

Author(s)

Jochen Fründ

Examples

array2linkmx(webs2array(Safariland, vazquenc))

Description

This helper function converts a bipartite matrix into a one-mode matrix.

Usage

as.one.mode(web, fill = 0, project="full", weighted=TRUE, legacy=FALSE)

Arguments

Details

In bipartite (or: two-mode) networks, participants are of different types (e.g. pollinators and plants, actors and parties in social research). Hence, a party cannot connect to another party except through actors. A pollinator interacts with another pollinator only through the host plant.

Much network theory, however, is based on one-mode networks, where all participants are listed in one vector, i.e. plants and pollinators alike, actors together with events. This function here transforms the more condensed bipartite representation into a one-mode-representation, filling the unobserved type of interactions (i.e. plants with plants and pollinators with pollinators) with 0 (unless you specify it differently in fill).

The lower trophic level (e.g. plants or rows) is listed first, then the higher trophic level (e.g. pollinators or columns). Hence, pollinator 2 becomes species number r+2, where r is the number of rows of the network matrix.

In addition to the "full" projection, there are "inner" projections, yielding a network only of the lower or higher level (hence the argument project="lower"/"higher"/"full"). Such an inner projection inevitably loses information: if two pollinators pollinate three plant species, then they are connected in such a projection through 3 links. The weight of each link will be different, but in the projection only one weight can be given. This is where the information is lost. Several indices (betweenness, centrality) depend on one-mode projections of this kind. Still, the user should always ask herself, whether the projection might not have unintended consequences!

If weighted=TRUE, then the returned one-mode network contains the parallel maximum (or minimum, if legacy=TRUE) of the observed interactions between two species. That means, if two species A and B interact with species 1 to 5 in the other group, then the two interaction vectors for A with 1 to 5 and B with 1 to 5 are placed next to each other, and for every species 1 to 5 the maximum for each of these 5 values for the two vectors is retained (the parallel maximum). The idea is that the similarity between A and B is driven by their largest communality in interactions. Next, the five parallel maximal values are added to yield the final weight for this link.

The benefit of this conversion is access to the wonderful R-package Social Network Analysis (sna), with its many one-mode indices (such as betweenness, closeness, centralization, degree, kpath.census and so forth). Furthermore, gplot in that package also provides cool network depictions well worth checking out.

With respect to bipartite, as.one.mode is employed in the function nodespec, which itself uses the sna-function geodist.

Value

A matrix of dimension (n+k) x (n+k), where n and k are the dimensions of the input web. Both dimensions are given the names of the original web (first the lower, then the higher trophic level).

Author(s)

Carsten F. Dormann [email protected]

References

Thurner, S., Hanel, R. and Klimek, P. (2018) Introduction to the Theory of Complex Systems. Oxford University Press, Oxford

See Also

Function projecting_tm in package tnet provide an analogous ways of converting two-modes into one-modes. This function can be accessed after transforming the web-matrix into an edge list using web2edges.

Examples

data(Safariland)
image(Safariland)
image(as.one.mode(Safariland))
par(xpd=TRUE, mar=c(0, 6, 0, 6))
gplot(as.one.mode(Safariland, project="lower"), 
	label=rownames(Safariland), gmode="graph", 
	label.cex=0.6, vertex.cex=2, vertex.col="green")

Description

Checks that a network conforms to the tnet stardards, and attaches a label. If the type parameter is not set, the network is assumed to be a binary two-mode network, a weighted one-mode network, or a longitudinal network if there are 2, 3, or 4 columns respectively. Moreover, if a matrix is entered (more than 4 columns and rows), it is assumed to be a weighted one-mode network if square or a two-mode network if non-square.

Usage

as.tnet(net, type=NULL)

Arguments

Value

Returns the network with an attached label.

Note

version 1.0.0, taken, with permission, from package tnet

Author(s)

Tore Opsahl; https://toreopsahl.com

Examples

## Load sample data
sample <- rbind(
c(1,2,4),
c(1,3,2),
c(2,1,4),
c(2,3,4),
c(2,4,1),
c(2,5,2),
c(3,1,2),
c(3,2,4),
c(4,2,1),
c(5,2,2),
c(5,6,1),
c(6,5,1))

## Run the programme
as.tnet(sample)

Description

This study took place in the boreal forest of central New Brunswick, Canada, from May to September of 1978, 1979, and 1980. The objective was to investigate the role of animals in pollination and seed dispersal. The study was designed to provide basic descriptive information on breeding systems, pollination biology, and phenology of understory herbs.

The authors recorded their data by counting the number of individual flower visitors caught on each plant species. The total number of individuals collected on each plant species provide a rough estimate of the level of visitation that each species received. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

Usage

data(barrett1987)

References

Barrett, S. C. H. and Helenurm, K. (1987) The Reproductive-Biology Of Boreal Forest Herbs. 1. Breeding Systems And Pollination. Canadian Journal of Botany 65, 2036–2046

Examples

data(barrett1987)

Description

This function (betalinkr) is a new implementation of network dissimarility, as proposed by Tim Poisot (originally implemented in the betalink package). Following Poisot, dissimilarity (of a pair of networks) is partitioned into the dissimilarity due to difference in species composition (“ST”) and dissimilarity due to rewiring (“OS”, dissimilarity of shared species subweb). Different partitioning approaches and many binary and quantitative indices are available. The recommended method for additive partitioning is commondenom (originally proposed by Novotny 2009), for which further partitioning into different aspects of species composition differences (partition.st) and into replacement and richness difference components (partition.rr) are also available.

betalinkr_multi is a metafunction that calls betalinkr for all pairs of networks (passing arguments), and returns a data.frame.

Usage

betalinkr(webarray, index="bray", binary=TRUE, partitioning="commondenom",
          proportions=!binary, function.dist="vegdist", distofempty="zero",
          partition.st=FALSE, partition.rr=FALSE)

betalinkr_multi(webarray, ...)

Arguments

Details

The basic idea to calculate dissimilarity (betadiversity) between networks (links instead of species) has been proposed before. Poisot et al. (2012) came up with the idea to separate between rewiring and species turnover as causes of network dissimilarity (but see Novotny 2009). They proposed to calculate rewiring link dissimilarity (“beta_OS” or simply “OS”) by focusing on the sub-web containing only species observed in both webs (i.e. excluding links with species unique to one of the webs). Species turnover link dissimilarity (“beta_ST” or simply “ST”) is then calculated as total dissimilarity minus rewiring dissimilarity, but this assumes an additivity that is rarely given with dissimilarity indices. Although dissimilarity values may not be additive, the number of “unique links” (i.e. only observed in one of the two webs) can be well partitioned into additive components.

With option partitioning="poisot", many different dissimilarity indices can be used with function.dist either vegdist or betadiver, but no guarantee that all of them can be usefully interpreted (following Legendre 2014, Jaccard-family and Sorensen-family dissimilarity indices are recommended; note that with vegdist you get Sorensen-family with bray, and with betadiver Jaccard is 15 and Sorensen is 1, although these go under different names there as Koleff et al. (2003) use the names Jaccard/Sorensen for the corresponding similarity metrics).

The alternative approach (with partitioning="commondenom") was inspired by Legendre (2014). It avoids using an existing dissimilarity function, but rather implements calculation of dissimilarity indices directly (thus more limited options for these: only binary and quantitative Jaccard-type and Sorensen-type). Here, the same denominator as for the total dissimilarity WN is used also for its components OS and ST, thus ensuring additivity. This method was actually already proposed by Novotny (2009), who further splitted ST (see partition.st). If your goal is indeed to partition dissimilarity into its (additive) components, use this method!

Note that if you are interested only in dissimilarity between subwebs (not as an additive component), you should use partitioning="poisot" and look at OS while ignoring ST. This works also for quantitative data (with binary=FALSE). If this is your goal, you should probably set distofempty="na", returning NA/NaN if there are no interactions between shared species.

To generate results identical to Poisot's betalink function in package betalink, use these settings: partitioning="poisot", function.dist="betadiver", distofempty="na" and binary=TRUE.

Again: the output for OS can differ strongly depending on the chosen options! You have to decide: do you want dissimilarity, which is inherently not additive (use partitioning="poisot"), or do you want an additive dissimilarity component, which is not a dissimilarity itself (use partitioning="commondenom")?

Value

A named vector of four (or more) dissimilarities (components), naming follows Poisot et al. 2012.

For betalinkr_multi, output is a dataframe with one row per pair of webs compared.

Note

This function allows to use quantitative dissimilarity indices, which are usually recommended. However, for quantitative networks it is far from trivial how to correctly separate (or even define) which part of the dissimilarity is due to rewiring and which due to difference in species composition! Here I use the concept that all variation between the subwebs of shared species can be attributed to rewiring, BUT this will most likely not be correct. Even if all species are shared among two networks, quantitative species dissimilarity may be large (different [relative] abundances), and this will most likely lead to changes in network frequencies (changing link weights, or even missing links) that should not be called rewiring. How to correctly define and measure that is open to discussion, but thus I would still consider the values for beta_OS as overestimates.

This function should also work for one-mode networks.

Why the name of the function? Short for “betalink revised”.

Why the names of the output values? These are the indices of beta (for betadiversity); I am keeping the names used by Tim Poisot and guess what they stand for: S (Species), OS (Only Shared species links), WN (Whole Network links), ST (Species Turnover links). Some authors would call all this dissimilarity (or dissimilarity components) and reserve the term betadiversity for something not standardized between 0 and 1.

For partitioning into replacement and richness difference, note that replacement in WN can mean richness difference in OS (if shared species switch from interaction with other shared species in one network to interactions with non-shared species in another network, changing the size of shared-species subweb), so finding OS.rich > WN.rich is not a bug.

Thanks to Carsten Dormann, Benjamin Schwarz, Benoit Gauzens, Nacho Bartomeus and Timothee Poisot for their contributions to this function.

Author(s)

Jochen Fründ

References

Poisot, T., E. Canard, D. Mouillot, N. Mouquet, D. Gravel, and F. Jordan. 2012. The dissimilarity of species interaction networks. Ecology Letters 15, 1353–1361.

Legendre, P. 2014. Interpreting the replacement and richness difference components of beta diversity. Global Ecology and Biogeography 23, 1324–1334.

Koleff, P., Gaston, K.J., and J.J. Lennon. 2003. Measuring beta diversity for presence–absence data. Journal of Animal Ecology 72, 367–382.

Novotny, V. 2009. Beta diversity of plant-insect food webs in tropical forests: a conceptual framework. Insect Conservation and Diversity 2, 5–9.

Noreika, N., Bartomeus, I., Winsa, M., Bommarco, R., and E. Öckinger. 2019. Pollinator foraging flexibility mediates rapid plant-pollinator network restoration in semi-natural grasslands.Scientific Reports, 9, 1–11. doi:10.1038/s41598-019-51912-4

See Also

vegdist and betadiver for vegan package functions calculating dissimilarity / betadiversity, used here unless partitioning="commondenom".

For reshaping web data to the array input format expected here, see webs2array and frame2webs.

Examples

# two examples that give the same results as would the 
# \code{betalink} function in the package of the same name
betalinkr(webs2array(list(Safariland=Safariland, vazarr=vazarr)), 
    partitioning="poisot")
betalinkr(webs2array(list(Safariland=Safariland, vazarr=vazarr)), 
    function.dist="betadiver",index=1, partitioning="poisot")

# same data, with recommended partitioning method plus further partitioning
betalinkr(webs2array(list(Safariland=Safariland, vazarr=vazarr)), 
    partitioning="commondenom", partition.st=TRUE)

# another example (no shared links)
testdata <- data.frame(higher = c("bee1","bee1","bee1","bee2","bee1","bee3"), 
  lower = c("plant1","plant2","plant1","plant2","plant3","plant4"), 
  webID = c("meadow","meadow","meadow","meadow","bog","bog"), freq=c(5,1,1,1,3,7))

# more than two webs:
betalinkr_multi(webs2array(Safariland, vazquenc, vazarr), index="jaccard")

Description

This function calculates betweenness scores for nodes in a weighted network based on the distance_w-function.
Note: This algorithm relies on the igraphs package's implementation of Dijkstra's algorithm. Currently, it does not find multiple shortest paths if two exist.

Usage

betweenness_w(net, directed=NULL, alpha=1)

Arguments

Value

Returns a data.frame with two columns: the first column contains the nodes' ids, and the second column contains the nodes' betweenness scores.

Note

version 1.0.0, taken, with permission, from package tnet

Author(s)

Tore Opsahl; https://toreopsahl.com/

References

https://toreopsahl.com/2009/02/20/betweenness-in-weighted-networks/

Examples

## Load sample data
sampledata <- rbind(
c(1,2,1),
c(1,3,5),
c(2,1,1),
c(2,4,6),
c(3,1,5),
c(3,4,10),
c(4,2,6),
c(4,3,10))

## Run the programme
betweenness_w(sampledata)

Description

Observation of 38 individual plants from 13 oil-flower species of the family Malphighiaceae. Flower visitors were collected. Only legitimate visitors were considered. Numbers in cells refer to the amount of visits of each bee species collected in each flower species.

The species interaction matrix describes the number of bee visits to 138 individual plants in natural clumps of 13 Malpighiaceae species during the flowering peak of each species. The number of bee visits to flowers was registered over four consecutive days, from 5.00 to 17.00 with a total of 1392 h of observations.

Location: Parque Nacional do Catimbau, Brazil (8°24'00” - 37° 36'35”S and 3° 09'30” - 37° 14'40”W)

Biome: Caatinga (Brazilian steppe)

The paper itself contrasted a network of Malpighiaceae oil-flowers and associated oil-collecting bees from a Brazilian steppe (“caatinga”) to whole pollination networks from all over the world available in the Interaction Web Database. The caatinga network had a perfectly balanced proportion of plants and animals (13 x 13) and was more nested and less modular than all of the 22 whole pollination networks studied. The authors concluded that the oil-flower subweb is more cohesive and resilient than whole pollination networks, reinforcing the hypothesis that each ecological service is in fact a mosaic of different subservices with a hierarchical structure (“webs within webs”).

Take from the NCEAS interaction web database (https://iwdb.nceas.ucsb.edu).

Usage

data(bezerra2009)

References

Bezerra, E.L.S., Machado, I.C.S. and Mello, M.A.R. 2009. Pollination networks of oil-flowers: a tiny world within the smallest of all worlds. Journal of Animal Ecology 78, 1096–1101.

Examples

data(bezerra2009)

Description

Calculates the C-score for all higher-level species; the C-score represents the average number of checkerboard units for each unique species pair.

Usage

C.score(web, normalise = TRUE, FUN = mean, ...)

Arguments

Details

As a first step, any quantitative matrix is converted to a binary matrix of presences and absences.

Then, the formula given in Stone and Roberts (1990) is calculated for all species combinations, by calling designdist from the package vegan. See code for details.

Value

Returns whatever the FUN produces as output. Default would be a single value, i.e. the mean C-score of the web.

Note

The normalisation, since Jan. 2015, is by brute force: the 1s and 0s are distributed for each pairwise comparison for maximum checkerboardness. (The previously used approach was incorrect!) As a consequence, large matrices will take some time to compute.

The minimum is set to 0.

Author(s)

Carsten F. Dormann

References

Gotelli, N.J. and Rohde, K. (2002) Co-occurrence of ectoparasites of marine fishes: a null model analysis. Ecology Letters 5, 86–94

Stone, L. and Roberts, A. (1990) The checkerboard score and species distributions. Oecologia 85, 74–79

Examples

m <- matrix(c(1,0,0, 1,1,0, 1,1,0, 0,1,1, 0,0,1), 5,3,TRUE)
C.score(m)
C.score(m, normalise=FALSE)
C.score(m, normalise=FALSE, FUN=print)

Description

This function calculates closeness scores for nodes in a weighted network based on the distance_w-function.

Usage

closeness_w(net, directed=NULL, gconly=TRUE, precomp.dist=NULL, alpha=1)

Arguments

Value

Returns a data.frame with three columns: the first column contains the nodes' ids, the second column contains the closeness scores, and the third column contains the normalised closeness scores (i.e., divided by N-1).

Note

version 1.0.0, taken, with permission, from package tnet

Author(s)

Tore Opsahl; https://toreopsahl.com/

References

https://toreopsahl.com/2009/01/09/average-shortest-distance-in-weighted-networks/

Examples

## Load sample data
sampledata <- rbind(
c(1,2,4),
c(1,3,2),
c(2,1,4),
c(2,3,4),
c(2,4,1),
c(2,5,2),
c(3,1,2),
c(3,2,4),
c(4,2,1),
c(5,2,2),
c(5,6,1),
c(6,5,1))

## Run the programme
closeness_w(sampledata)

Description

This function calculates the two-mode clustering coefficient as proposed by Opsahl (2010).

Usage

clustering_tm(net, subsample=1, seed=NULL)

Arguments

Value

Returns the outcome of the equation presented in the paper

Note

version 1.0.0, taken, with permission, from package tnet

Author(s)

Tore Opsahl; https://toreopsahl.com

References

Opsahl, T. 2010. Triadic closure in two-mode networks: Redefining the global and local clustering coefficients. arXiv,1006.0887

Description

Finds number of compartments, based on multivariate ordination techniques, and labels interactions according to the compartment they belong to.

Usage

compart(web)

Arguments

Details

Internal function, to be called by networklevel.

Value

Returns a list with two entries:

Note

Note that up to (and including) version 0.85 we used a code based on correspondence analysis (see Lewinsohn et al. 2006). This is, however, faulty for webs with many same-linked species. Hence we resorted to a brute-force search for compartments, which is orders of magnitude slower, but at least works correctly. Only in version 1.18 Juan M. Barreneche eventually found a solution that is fast and works with ties!

Author(s)

Juan M. Barreneche <[email protected]>, but please co-copy comments/questions to package maintainer: Carsten F. Dormann <[email protected]>

References

Lewinsohn, T. M., P. I. Prado, P. Jordano, J. Bascompte, and J. M. Olesen (2006) Structure in plant-animal interaction assemblages. Oikos 113, 174–184

See Also

See also networklevel.

Examples

# make a nicely comparted web:
web <- matrix(0, 10,10)
web[1,1:3] <- 1 
web[2,4:5] <- 1 
web[3:7, 6:8] <- 1
web[8:10, 9:10] <- 1
web <- web[-c(4:5),] #oh, and make it asymmetric!
web <- web[,c(1:5, 9,10, 6:8)] #oh, and make it non-diagonal
compart(web)

# or, standard, use Safariland as example:
data(Safariland)
compart(Safariland)

Description

This function takes a bipartite weighted graph and computes modules by applying Newman's modularity measure in a bipartite weighted version to it. metaComputeModules re-runs the algorithm several times, returning the most modular result, to stabilise modularity computation.

Usage

computeModules(web, method="Beckett", deep = FALSE, deleteOriginalFiles = TRUE, 
	steps = 1000000, tolerance = 1e-10, experimental = FALSE, forceLPA=FALSE)
	
metaComputeModules(moduleObject, N=5, method="Beckett", ...)

Arguments

Value

An object of class "moduleWeb" containing information about the computed modules. For details, please refer to the corresponding documentation file.

Note

For perfectly compartmentalised networks the algorithm may throw an error message. Please add a little bit of noise (e.g. uniform between 0 and 1 or so) or a small constant (1E-5 or so) and it will work again.

When using the method DormannStrauss, files are written onto the hard drive during the computation. These files are by default deleted after the computation terminates, unless it breaks. Details of the modularity algorithm can be found in Dormann & Strauß (2013).

Author(s)

Rouven Strauss, with fixes by Carsten Dormann and Tobias Hegemann; modified to accommodate Beckett's algorithm by Carsten Dormann

References

Beckett, S.J. 2016 Improved community detection in weighted bipartite networks. Royal Society open science 3, 140536.

Dormann, C. F., and R. Strauß. 2014. Detecting modules in quantitative bipartite networks: the QuanBiMo algorithm. Methods in Ecology & Evolution 5 90–98 (and arXiv [q-bio.QM] 1304.3218.)

Liu X. & Murata T. 2010. An Efficient Algorithm for Optimizing Bipartite Modularity in Bipartite Networks. Journal of Advanced Computational Intelligence and Intelligent Informatics (JACIII) 14 408–415.

Newman M.E.J. 2004. Physical Review E 70 056131

Newman, M.E.J. 2006. Modularity and community structure in networks. Proceedings of the National Academy of Sciences of the United States of America, 103, 8577–-8582.

See Also

See also class "moduleWeb", plotModuleWeb, listModuleInformation, printoutModuleInformation, DIRT_LPA_wb_plus.

Examples

## Not run: 
		data(small1976)
		(res <- computeModules(small1976)) 
		plotModuleWeb(res)
		
		# slow:
		res2 <- metaComputeModules(small1976, method="DormannStrauss")
		res2
	
## End(Not run)

Description

Function to compute c and z values of module members according to Guimerà & Amaral (2005), with formulae taken from Olesen et al. (2007)

Usage

czvalues(moduleWebObject, weighted=FALSE, level="higher")

Arguments

Details

c = 1 - sum( (k.it/k.i)^2) # among-module connectivity = participation coefficient P in Guimerà & Amaral

z = (k.is - ks.bar) / SD.ks # within-module degree

k.is = number of links of i to other species in its own module s; ks.bar = average k.is of all species in module s; SD.ks = standard deviation of k.is of all species in module s; k.it = number of links of species i to module t; k.i = degree of species i

Note that for any species alone (in its level) in a module the z-value will be NaN, since then SD.ks is 0. This is a limitation of the way the z-value is defined (in multiples of degree/strength standard deviations).

Olesen et al. (2006) give critical c and z values of 0.62 and 2.6, respectively. Species exceeding these values are deemed connectors or hubs of a network. The justification of these thresholds remains unclear to me. They may also not apply for the quantitative version.

Value

A list with two vectors, c and z, for all species of the selected trophic level.

Note

These indices were developed for one-mode networks; we'll have to see whether they make sense for bipartite networks, too! In particular, note that this function is based on a higher trophic level perspective. While the modules are identified using both trophic levels, c and z are computed through the strengths/degrees of only one trophic level. It would be desirable to have a truly two-level version. Since there are usually very different numbers of species in the two trophic levels, simply averaging the values of each trophic level won't do. But maybe a weighted average?

Consider the following problem for computing c and z for the higher trophic level: For modules with only one species from the lower trophic level, the z-values will be NaN, since SD.ks is 0! I decided to SET these values to 0, since they only occur when all species in that module will have the same number of links (which is obviously the case when there is only one lower-level species). Then the numerator is also 0. Thus, the value of 0 indicates that this species has no deviation from the rest of the module members (which is what I think z is supposed to represent).

Since computeModules is experimental, also czvalues may not always work (i.e. if object mod is corrupted or ill-formed).

Author(s)

Carsten F. Dormann [email protected], 20 Mar 2012

References

Guimerà, R. and Amaral, L.A.N. (2005) Functional cartography of complex metabolic networks. Nature 433, 895–900.

Olesen, J.M., Bascompte, J., Dupont, Y.L. and Jordano, P. (2007) The modularity of pollination networks. Proceedings of the National Academy of Sciences of the USA 104, 19891-19896.

Examples

## Not run: 
set.seed(2)
mod <- computeModules(memmott1999)
cz <- czvalues(mod)
plot(cz[[1]], cz[[2]], pch=16, xlab="c", ylab="z", cex=0.8, xlim=c(0,1), las=1)
abline(v=0.62) # threshold of Olesen et al. 2007
abline(h=2.5)   # dito
text(cz[[1]], cz[[2]], names(cz[[1]]), pos=4, cex=0.7)

# example for computing a c- or z-threshold:
mod <- computeModules(Safariland)
czobs <- czvalues(mod)
nulls <- nullmodel(Safariland, N=10) # this should be larger, of course
null.mod.list <- sapply(nulls, computeModules)
null.cz <- lapply(null.mod.list, czvalues)
# compute 95
null.cs <- sapply(null.cz, function(x) x$c) # c-values across all species in nulls
quantile(null.cs, 0.95) 
# this could now serve as thresholds for identifying particularly uncommonly high c-values
# and analogously for z, of course

## End(Not run)

Description

Function to generate null model matrices for the cases when the matrix entries are non-negative numbers, possibly non-integers. It maintains marginal totals (as does r2dtable), but "smears" them out over all cells.

Usage

decimalr2dtable(N=10, web, steps=prod(dim(web)))

Arguments

Details

This function is a cross between r2dtable and swap.web. Its output are N matrices of the same dimension as the input, and with same marginal totals, but with different allocation of values to the cells. Here is what the algorithm does:

1. Index a 2 x 2 submatrix by select randomly two rows and two columns.

2. Draw a random value between 0 and the minimum of the diagonal entries in the submatrix.

3. Subtract this value from the diagonals and add it to the counter-diagonal entries.

4. Repeat steps times

The result is a decimal-numbered matrix, typically with values > 0 in each cell.

Indication: This function may be useful in some rare constellations. Imagine you sampled a plant-pollinator network and instead of counting the number of flower visits you recorded the nectar extracted by each pollinator. Then the marginal totals would indicate nectar production (plus confounding nectar attractiveness) and consumption potential for plants and pollinators, respectively. So, given that species differ in nectar production and consumption, what would you expect the network to look like? Enter decimalr2dtable.

If external abundances (even in funny units such as biovolume in ml) are available, this function can easily provide the respective null models. See examples.

Value

A list of N randomised matrices with the same dimensions as the initial web, all probably filled completely.

Note

The output will typically be a fully filled matrix! Computing any index sensitive to matrix filling (such as connectance, degree, nestedness) for such a matrix is non-sensical!

Also, if used as a null model, an implicit assumption is that the values in the original matrix are meaningful as marginal totals. This may often not be the case, for example if entries are rates. Thus, probably this function is of very limited usefulness in the context of network analyses!

Author(s)

Carsten F. Dormann <[email protected]>

See Also

r2dtable, vaznull, shuffle.web and swap.web

Examples

obs <- networklevel(Safariland, index="generality")

nulls <- decimalr2dtable(10, Safariland)
g.dec <- sapply(nulls, networklevel, index="generality")
nullsint <- nullmodel(Safariland, N=10)
g.int <- sapply(nullsint, networklevel, index="generality")
plot(density(g.dec[1,]), xlim=c(1, 3))
lines(density(g.int[1,]), col="red")
abline(v=obs[1], col="green")


## If you want to use external abundances to set up your null model:
set.seed(1)
ext.rows <- runif(9) # imagine these are your external abundances for Safariland
ext.cols <- runif(27)
# standardise to sum = 1:
ext.rows <- ext.rows/sum(ext.rows)
ext.cols <- ext.rows/sum(ext.cols)
web <- tcrossprod(ext.rows, ext.cols) * sum(Safariland) 
# (to get to the same interaction density as original web)
#
# this can now be used as input for decimalr2dtable:
image(decimalr2dtable(N=1, web)[[1]]) # remember: white are high values!

Description

This function first calculates degrees for each species, then constructs a cumulative distribution with them, and finally fits three different functions to these distributions: exponential, power law and truncated power law. Coefficients and fits are returned.

Usage

degreedistr(web, plot.it=TRUE, pure.call=TRUE, silent=TRUE, level="both", ...)

Arguments

Details

Jordano et al. (2003) proposed that plant-animal networks may show scale invariance, as indicated by the presence of a power law in species degrees. They report on consistently better fits of the truncated power law, hypothesising that such patterns may arise from morphological mismatch or phenological uncoupling.

Most problematic with the use of this particular approach is the extreme demand for data. The example web Safariland in this package is large (1130 interactions), but it provides only 5 different degree levels (for plants, only 4 for pollinators). Hence fitting three different non-linear functions to these few points is stretching it a bit.

Furthermore, the least-square-fit to the cumulative distribution is not ideal. While the most common approach, it has a bias (albeit much less so than a fit to the probability density function: see Clauset et al. 2009). In an ideal world, we would want to fit the power law properly. This would require a) an estimation of the lower bound of the power law (xmin) and b) the maximum likelihood fit to the remaining data (x > xmin). The data demand is however such that is unlikely that any ecological bipartite network in the near future will match it. Clauset et al. state that hundreds to thousands of data points are required to yield satisfactory estimates for xmin and the slope itself. If you happen to have this much data, please consult the software they provide (even in R!).

Value

For both trophic levels, a table:

If plots are returned, exponential, power law and truncated power law are given in black, dark grey and light grey, respectively.

Note

The truncated power law fits two coefficients: slope and cut-off. The function only returns the slope. R2-values for non-linear fits are not well liked among statisticians! See the discussion the R-help list (e.g. https://stat.ethz.ch/pipermail/r-help/2002-July/023461.html). Finally, often data are too few to yield any fit. In this case the error message “singular gradient” is returned to signal this problem!

Post finally, yes, I am aware that degrees are integers and unlikely to be normally distributed, and that thus the nls procedure is not really a good idea. My (poor) excuse: I followed the implementation of the above-cited paper and do not believe enough in degree distributions (and power laws, for that matter) to implement a proper likelihood-based approach. Check out the statnet bundle for alternative approaches to this problem.

Author(s)

Carsten F. Dormann [email protected]

References

Clauset, A., Shalizi, C. R., & Newman, M. E. (2009). Power-law distributions in empirical data. SIAM Review 51, 661–703

Jordano, P., Bascompte, J. and Olesen, J. M. (2003) Invariant properties in coevolutionary networks of plant-animal interactions. Ecology Letters 6, 69–81

See Also

networklevel, where degreedistr is called (without picturing the results)

Examples

data(Safariland)
degreedistr(Safariland)

Description

This function returns the specialisation index d' for the lower level, which expresses how specialised a given species is in relation to what partners in the higher level are on offer.

Usage

dfun(web, abuns=NULL)

Arguments

Details

The d' index is derived from Kulback-Leibler distance (as is Shannon's diversity index), and calculates how strongly a species deviates from a random sampling of interacting partners available. It ranges from 0 (no specialisation) to 1 (perfect specialist). In the case of a pollination web, a pollinator may be occurring only on one plant species, but if this species is the most dominant one, there is limited evidence for specialisation. Hence this pollinator would receive a low value. In contrast, a pollinator that occurs only on the two rarest plants would have a very high value of d'.

The idea of this index is laid out in Blüthgen et al. (2006). It basically calculates the Shannon-diversity for each column (delivering the raw d-values) and re-ranges them between the theoretical maximum and minimum (yielding values between 0 and 1). dmax is given analytically (see paper or code), but dmin must be found ‘heuristically’, since the web can only contain integers. The idea behind the heuristic minimum is that d will be minimal when observed values differ least from expected values based on marginal distributions.

The way this function is implemented, it calculates expected values for each cell based on the product of observed marginal sums (i.e. column and row sums) times sum(web). Then it rounds off to integers and allocates the remaining interactions in two steps: First, all columns and rows with marginal sums of 0 obtain one interaction into the cell with the highest expected value. Secondly, all remaining interactions are distributed according to difference between present and expected value: those cells with highest discrepancy receive an interaction until the sum of all entries in the new web equals those in the original web. Now the d-values for this web are calculated and used as dmin.

Simple rounding of expected values would lead to empty columns or rows, i.e. the dmin-web would be of lower dimension than the original web.

dfun returns the d' values for the lower trophic level. Use dfun(t(web)) to get the d'-values for the higher trophic level (as does specieslevel). If you want to provide external abundances, you must provide those of the other trophic level! (This help file is written as if you were interested in the lower trophic level.)

d' is one of several species-level network indices. It's generalisation to the entire interaction web is called H2' (see H2fun).

The abundances vector allows to incorporate independent estimates of the abundances of the higher trophic level. In a pollination web, pollinator abundances may be very different from those estimated by the interaction matrix column sums. This has also, obviously, large consequences for the specialisation: A plant being pollinated by a bee that is common on this plant, but very rare in general, will show a low specialisation unless bee abundances are corrected for. Data given in the abundance vector are here used in replacement for the row sums, both in the d-function itself, as well as in the calculation of the minimum ds.

In contrast to H2fun, finding the minimum value of d violates marginal totals. The idea is that we look at each species in turn. Then, we estimate how its observed number of interactions can be distributed, given the marginal totals (i.e. if 5 interactions were observed, they cannot be put into a link that only has 3 interactions across all species). So, for each species the number of interactions never exceeds the total across all species, but if we would put the web together from this sequential scan, it may well do so. In our view, this is irrelevant, because we are interested in the potential of each species separately to be perfectly specialised (given the marginal totals), not for the entire web. We leave this to H2fun.

Value

Note

When independent abundances were provided, the empty rows/columns are purposefully not removed from the web (because they now still contain information). Logically (and as implemented), this leads to d-values for these species of NA. This makes sense: the pollinator, say, has never been observed on any of the flowers, so how can we quantify its specialisation?

As detailed above, deriving the dmin-values ‘heuristically’ leaves room to some variation. We are very happy with this implementation, but you may want to program something yourself ...

Author(s)

Jochen Fründ and Carsten F. Dormann

References

Blüthgen, N., Menzel, F. and Blüthgen, N. (2006) Measuring specialization in species interaction networks. BMC Ecology 6, 12

See Also

H2fun for a similar function for the entire network. specieslevel for a method that, amongst other indices, calls dfun.

Examples

data(Safariland)
dfun(Safariland) # gives d-values for the lower trophic level
# now using independent abundance estimates for higher trophic level:
dfun(Safariland, abuns=runif(ncol(Safariland)))

dfun(t(Safariland)) #gives d-values for the higher trophic level

Description

Use computeModules to call this function! This function takes a bipartite weighted graph and computes modules by applying Newman's modularity measure in a bipartite weighted version to it. To do so, it uses Stephen J Beckett's DIRTLPAwb+ (or LPAwb+) algorithm, which builds on Liu & Murata's approach. In contrast to the tedious MCMC-swapping QuanBiMo algorithm, this algorithm works by aggregating modules until no further improvement of modularity can be achieved.

Usage

DIRT_LPA_wb_plus(MATRIX, mini=4, reps=10)
LPA_wb_plus(MATRIX, initialmoduleguess=NA)
convert2moduleWeb(MATRIX, MODINFO)

Arguments

Value

LPA_wb_plus computes the modules. DIRT_LPA_wb_plus is a wrapper calling LPA_wb_plus repeatedly to avoid getting stuck in some local minimum. Both return a simple list of row and column labels for the modules, as well as the modularity value. Using convert2moduleWeb turns this into the richer moduleWeb-class object produced by computeModules. For this object, the plotting function plotModuleWeb and summary functions listModuleInformation and printoutModuleInformation are available.

Author(s)

Stephen J Beckett (https://github.com/sjbeckett/weighted-modularity-LPAwbPLUS), lifted, with consent of the author, by Carsten F. Dormann to bipartite

References

Beckett, S.J. 2016 Improved community detection in weighted bipartite networks. Royal Society open science 3, 140536.

Liu X. & Murata T. 2010. An Efficient Algorithm for Optimizing Bipartite Modularity in Bipartite Networks. Journal of Advanced Computational Intelligence and Intelligent Informatics (JACIII) 14 408–415.

Newman M.E.J. 2004. Physical Review E 70 056131

See Also

computeModules; see also class "moduleWeb", listModuleInformation, printoutModuleInformation

Examples

## Not run: 
		(res <- DIRT_LPA_wb_plus(small1976))
		mod <- convert2moduleWeb(small1976, res)
		plotModuleWeb(mod)
	
## End(Not run)

Description

Discrepancy is the number of mismatches between a packed (binary) matrix and the maximally packed matrix (with same row sums)

Usage

discrepancy(mat)

Arguments

Details

Discrepancy is a way to measure the nestedness of a matrix. In a comparative study, Ulrich & Gotelli (2007) showed discrepancy to outperform all other measures and hence recommend its use (together with a fixed-columns, fixed-rows null model, such as implemented in simulate.nullmodel in vegan, see example).

This function follows the logic laid out by Brualdi & Sanderson (1999), although, admittedly, I find their mathematical description highly confusing. Another implementation is given by the function nesteddisc in vegan. The reason to write a new function is simple: I wasn't aware of nesteddisc! (I was sitting on a train and I wanted to use this measure later on, so I put it into a function consulting only the orignal paper. When looking for the swap algorithm to create null models, which I somehow knew to exist in vegan, I stumbled across nesteddisc. If you are interested in the swap algorithm and come across this help page, let me re-direct you to oecosimu in vegan.)

Now that this function exists, too, I found it to differ in output from nesteddisc. Jari Oksanen was quick to point out, that our two implementations differ in the way they handle ties in column totals. This function is, I think, closer to the results given in Brualdi & Sanderson. Jari also went on to implement different strategies to deal with ties, so my guess is that his version may be (slightly) superior to this one. Having said that, values don't differ much between the two implementations.

So what does it do: The matrix is sorted by marginal totals, yielding a matrix A. Then, all 1s in A are “pushed” to the left to maximally compact the matrix, yielding P. Discrepancy is now simply the number of disagreements between A and P, divided by two (to correct for the fact that every “wrong” 1 will necessarily generate a “wrong” 0).

Value

Returns the number of mismatches, i.e. the discrepancy of the matrix from perfecct nestedness.

Note

Discrepancy is well-defined only for matrices that can be sorted uniquely. For matrices with ties no foolproof way to handle them has been proposed. For small matrices, or large matrices with many ties, this will lead to different discrepancy values. See also how nesteddisc in vegan handles this issue! (Thanks to Jari Oksanen for pointing this out!)

Author(s)

Carsten F. Dormann

References

Brualdi, R.A. and Sanderson, J.G. (1999) Nested species subsets, gaps, and discrepancy. Oecologia 119, 256–264

Ulrich, W. and Gotelli, N.J. (2007) Disentangling community patterns of nestedness and species co-occurrence. Oikos 116, 2053–2061

See Also

nestednodf in vegan for the best nestedness algorithm in existence today (for both binary and weighted networks!); nestedness for the most commonly used method to calculate nestedness, wine for a new, unevaluated but very fast way to calculate nestedness; nestedtemp (another implementation of the same method used in our nestedness) and nestedn0 (calculating the number of missing species, which has been shown to be a poor measure of nestedness) in vegan

Examples

## Not run: 
#nulls <- replicate(100, discrepancy(commsimulator(Safariland, 
		method="quasiswap")))
nulls <- simulate(vegan::nullmodel(Safariland, method="quasiswap"), nsim = 100)
null.res <- apply(nulls, 3, discrepancy)
hist(null.res)
obs <- discrepancy(Safariland)
abline(v=obs, lwd=3, col="grey")
c("p value"=min(sum(null.res>obs), sum(null.res<obs))/length(null.res))
# calculate Brualdi & Sanderson's Na-value (i.e. the z-score):
c("N_a"=(unname(obs)-mean(null.res))/sd(null.res))

## End(Not run)

Description

The shortest path length, or geodesic distance, between two nodes in a binary network is the minimum number of steps you need to make to go from one of them to the other. This distance is the quickest connection between nodes when all ties are the same. However, in a weighted network, all ties are not the same. See https://toreopsahl.com/2009/01/09/average-shortest-distance-in-weighted-networks/ for more deatails.

Usage

distance_w(net, directed=NULL, gconly=TRUE, subsample=1, seed=NULL)

Arguments

Value

Returns a distance matrix.

Note

version 1.0.0, taken, with permission, from package tnet

Author(s)

Tore Opsahl; https://toreopsahl.com/

References

https://toreopsahl.com/2009/01/09/average-shortest-distance-in-weighted-networks/

Description

This study took place in the subarctic alpine zone of Latnjajaure, in northern Sweden. Field work was conducted from May 21 to August 23, 1994. The objective was to describe the plant-flower visitor interaction matrix of this area and compare it with the characteristics of other subarctic alpine systems and with pollination systems of lower latitudes, especially in relation to the role of flies as flower visitors at high latitudes.

The authors recorded their data by counting the number of visits of each flower visitor species to each plant species. Regardless of whether insects were observed to forage for nectar and pollen or to perform sun-basking, they were all classified as flower visitors and potential pollinators and the plant species visited were recorded. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

See also https://iwdb.nceas.ucsb.edu/resources.html#plant_pollinator

Usage

data(elberling1999)

Format

A data frame with 12 plant species (in rows) and 102 pollinators (columns).

References

Elberling H. and Olesen J.M. (1999) The structure of a high latitude plant-flower visitor system: the dominance of flies. Ecography 22, 314–323

Examples

data(barrett1987)
## maybe str(barrett1987) ; plot(barrett1987) ...

Description

Gets rid of empty columns and rows in a matrix. Optionally counts removed rows and columns, and returns these values as attribute.

Usage

empty(web, count=FALSE)

Arguments

Details

Helper function to remove empty (i.e. all-zero or all-NA) rows and columns, thereby concentrating the matrix. This function is also invoked for its side effect by extinction to investigate the effect of removing a species from the network.

Value

Returns matrix without empty rows or columns. Its attribute ‘out’ (if count=TRUE) contains a named vector with the number of rows removed and the number of columns removed.

Author(s)

Carsten F. Dormann

See Also

extinction and second.extinct, which repeatedly call empty.

Examples

data(Safariland)
web <- Safariland
web[,5] <- 0
empty(web, count=TRUE)
attr(empty(web), "empty")

Description

Computes end-point degrees for a bipartite network, following the suggestion of Barrat et al. (2004)

Usage

endpoint(web)

Arguments

Details

Computation follows the outline of Gitarranz et al. (2004): “the product k_i k_j of the degree of the two nodes connected by that link”. We then set additionally endpoint degrees for all non-existing links to 0! Thus, only for existing links endpoint degrees are computed. This is (to me) not obvious from the description in Gitarranz et al. (2004).

Value

A matrix of end-point degrees

Note

This approach is, AFAIK, not tested by simulation; whether it is useful has still to be shown.

Author(s)

Carsten F. Dormann

References

Barrat, A., M. Barthélemy, R. Pastor-Satorras, and A. Vespignani. 2004. The architecture of complex weighted networks. Proceedings of the National Academy of Sciences of the USA 101, 3747-–3752. doi: 10.1073/pnas.0400087101.

Gilarranz, L. J., J. M. Pastor, and J. Galeano. 2011. The architecture of weighted mutualistic networks. Oikos 121, 1154–-1162. doi: 10.1111/j.1600-0706.2011.19592.x.

Examples

# reproduces the example of Gitarranz et al. (2011):
data(memmott1999)
ends <- endpoint(memmott1999)
weights.mean <- tapply(memmott1999, ends, mean)
ends.weights <- tapply(ends, ends, mean)
plot(weights.mean, ends.weights, log="xy", pch=16)

Description

Following (how I remember) the paper of Memmott et al. (2004), this function deletes a column (e.g. pollinator) or row (e.g. plant). Only a helper function for second.extinct, really.

Usage

extinction(web, participant = "both", method = "random", ext.row=NULL, 
	ext.col=NULL)

Arguments

Details

In itself rather useless. Called repeatedly by second.extinct to build an extinction sequence and accordingly a sequence of secondary extinctions.

Value

Returns the same matrix that was given as object, just with one row or column being turned into zeros.

Author(s)

Carsten F. Dormann

References

Memmott, J., Waser, N. M. and Price, M. V. 2004 Tolerance of pollination networks to species extinctions. Proceedings of the Royal Society B 271, 2605–2611

See Also

second.extinct

Examples

## Not run: 
	data(Safariland)
	(w <- extinction(Safariland, participant="lower", method="abun"))
	empty(w, count=TRUE)

## End(Not run)

Description

A community-level measure of ecological niche complementarity measured as the total branch length of a functional dendrogram based on qualitative differences in visitor assemblages between plants.

Usage

fc(web, dist="euclidean", method="average", weighted=TRUE)

Arguments

Details

fc measures community-level ecological niche complementarity as the total branch length of a functional dendrogram based on qualitative differences in visitor assemblages between plants. For details see Devoto et al. (2012).

Value

The value of fc, which is not standardised and lies anywhere between 0 and a large number.

Author(s)

Mariano Devoto [email protected]

References

Devoto M., Bailey S., Craze P., and Memmott J. (2012) Understanding and planning ecological restoration of plant-pollinator networks. Ecology Letters 15, 319–328

See Also

networklevel, which uses this function.

Examples

data(Safariland)
fc(Safariland)    
fc(t(Safariland), dist="canberra", method="complete")

Description

Convenience function to convert a table of observations (i.e. an "edge list", typically compiled in a spreadsheet programm) into a network matrix for further use in bipartite.

Usage

frame2webs(dframe, varnames = c("lower", "higher", "webID", "freq"), type.out = 
"list", emptylist = TRUE)

Arguments

Details

This function supports the easy handling of typical recording that are used to compose a network. The assumed structure of the underlying table is two columns for the names of the lower and higher level species, respectively, one column for a network ID (e.g. site, observer or any other grouping code) and, optionally, a number that indicates how often this interaction was observed. If not given, the number of interactions is simply computed from the number of times the same interaction occurred for each network ID. See example code below.

Typically, data are recorded (in a field book or external data logging device), read into a spreadsheet software (such as MS Excel or Open/LibreOffice Spreadsheet), where names are checked, typos corrected and so forth. This table is then imported into R and aggregated into one or more webs (or an array or a list of webs) using frame2webs.

Each link can have multiple entries or a single entry!

Value

A list or an array of networks, each to be used as input for other bipartite functions.

Note

Great care should be taken in checking species names, slightly different spellings will be assumed to be different species! Common problems occur because a space was added to the name or lower and higher case letters were mixed. For example, R is case sensitive and observes white space, while “Homo sapiens”, “Homo sapiens ” (with a trailing space) and “homo sapiens” are not recognized as different in typical spreadsheet software (e.g. Excel).

Author(s)

Jochen Fründ

See Also

empty

Examples

testdata <- data.frame(higher = c("bee1","bee1","bee1","bee2","bee1","bee3"), 
lower = c("plant1","plant2","plant1","plant2","plant3","plant4"), 
webID = c("meadow","meadow","meadow","meadow","bog","bog"), freq=c(5,1,1,1,3,7))
frame2webs(testdata,type.out="array")
sapply(frame2webs(testdata,type.out="list"), networklevel, index=c("connectance", "C score"))

Description

Generates a random bipartite web, based on r2dtable and lognormal marginal distributions.

Usage

genweb(N1 = 10, N2 = 30, dens = 2)

Arguments

Details

This function can be used to create simple, but not necessarily realistic, bipartite webs for given dimensionality and interaction density. Marginal distributions are assumed to be lognormal, mean and standard deviation are calculated from N1, N2 and dens (see code for details).

Value

A matrix with N1 x N2 species.

Note

Can be a bit time-consuming for large webs, because the absolute values for both dimensions have to match perfectly. This involves a rather inelegant while-loop.

Author(s)

Jochen Fründ and Carsten F. Dormann

Examples

genweb()

Description

Calculates a variety of indices and values for each group of a bipartite network (one.grouplevel is the actual function to do the computations and is not intended to be called by the user)

Usage

grouplevel(web, index="ALLBUTDD", level="both", weighted=TRUE, empty.web=TRUE, 
dist="horn", CCfun=mean, logbase="e", normalise=TRUE,  extinctmethod="r", 
nrep=100, fcdist="euclidean", fcweighted=TRUE)

Arguments

Details

This function implements a variety of the many (and still procreating) indices describing network topography at the group level.

Note that Bersier et al. (2002) have three levels of values for some of their indices: qualitative (i.e. based on binary networks), quantitative (based on networks with information on the number of interactions observed for each link), and weighted-quantitative (where each species is given a weight according to the number of interactions it has). At present, we implement a mixture of qualitative, quantitative and weighted-quantitative indices and offer the option weighted to compute the weighted-quantitative version of some of them (mean number of links, mean number of shared partners, cluster coefficient, partner diversity, generality / vulnerability). For all others, the mechanics behind the index do not allow a weighted mean to be computed (e.g. the distance-matrix between all species combinations used to compute niche.overlap).

All indices in this function work with real as well as integer values.

Extinction slope works on a repeated random sequence of species extinctions (within one trophic level), and calculates the number of secondary extinctions (in the other level). These values are then averaged (over the nrep runs) and plotted against the number of species exterminated. The proportion still recent (on the y-axis) regressed against the proportion exterminated (on the x-axis) is hence standardised to values between 0 and 1 each. Through this plot, a hyperbolic regression is fitted, and the slope of this regression line is returned as an index of extinction sensitivity. The larger the slope, the later the extinction takes its toll on the other trophic level, and hence the higher the redundancy in the trophic level under consideration. Using plot.it=F also returns the graphs (set history to recording in the plotting window). Changing the extinctionmethod to “abundance” will always result in the same sequence (by increasing abundance) and hence does not require replication.

Most indices are straightforward, one-line formulae; some, such as betweenness, also require a re-arranging of the matrix; and one, secondary extinction slope, internally requires iterative runs, making the function relatively slow. If you are not interested in the secondary extinction slopes, simply set nrep=1 to make it much faster.

Value

The suffixes LL and HL refer to lower and higher level, respectively. If values for both levels are requested, those for the higher level are given first, followed immediately by those for the lower level.

Depending on the selected indices, some or all of the below (returned as vector if “degree distribution” was not requested, otherwise as list):

Note

If your web returns and NA for some of the indices, this can be because the index cannot be computed. For example, if the web is full (i.e. no 0-cells), extinction slopes cannot be fitted (singularity of gradient). Check if you can expect the index to be computable! If it is, and grouplevel doesn't do it, let me know.

Some indices require rather long computation times on large webs. If you want to increase the speed by omitting some indices, here a rough guide: Ask only for the indices you are interested in! Otherwise, here is the sequence of most time-consuming indices:

1. For somewhat larger networks (i.e. more than 2 dozen species per level), weighted cluster coefficient is very time consuming (an exhaustive search for 4-loops in the one-mode projection of the network). Omitting it can dramatically boost speed.

2. Typically, the slowest function is related to extinction slopes and robustness. Excluding both makes the function faster.

3. Degree distributions are somewhat time consuming.

Author(s)

Carsten F. Dormann [email protected]

References

Bascompte, J., Jordano, P. and Olesen, J. M. 2006. Asymmetric coevolutionary networks facilitate biodiversity maintenance. Science 312, 431–433

Bersier, L. F., Banasek-Richter, C. and Cattin, M. F. 2002. Quantitative descriptors of food-web matrices. Ecology 83, 2394–2407

Blüthgen, N. 2010. Why network analysis is often disconnected from community ecology: A critique and an ecologist's guide. Basic and Applied Ecology 11, 185–195

Blüthgen, N., Menzel, F., Hovestadt, T., Fiala, B. and Blüthgen N. 2007 Specialization, constraints and conflicting interests in mutualistic networks. Current Biology 17, 1–6

Devoto M., Bailey S., Craze P., and Memmott J. (2012) Understanding and planning ecological restoration of plant-pollinator networks. Ecology Letters 15, 319–328.

Dormann, C.F., Fründ, J., Blüthgen, N., and Gruber, B. (2009) Indices, graphs and null models: analysing bipartite ecological networks. The Open Ecology Journal 2, 7–24.

Dunne, J. A., R. J. Williams, and N. D. Martinez. 2002 Food-web structure and network theory: the role of connectance and size. Proceedings of the National Academy of Science USA 99, 12917–12922

Gotelli, N. J., and G. R. Graves. 1996 Null Models in Ecology. Smithsonian Institution Press, Washington D.C.

Jost, L. 2006. Entropy and diversity. Oikos 113, 363-–375.

Krebs, C. J. 1989 Ecological Methodology. Harper Collins, New York.

Memmott, J., Waser, N. M. and Price M. V. 2004 Tolerance of pollination networks to species extinctions. Proceedings of the Royal Society B 271, 2605–2611

Müller, C. B., Adriaanse, I. C. T., Belshaw, R. and Godfray, H. C. J. 1999 The structure of an aphid-parasitoid community. Journal of Animal Ecology 68, 346–370

Roberts, A. and Stone, L. 1990 Island-sharing by archipelago species. Oecologia 83, 560–567

Schluter, D. (1984) A variance test for detecting species associations, with some example applications. Ecology 65, 998-1005.

Stone, L. and Roberts, A. (1990) The checkerboard score and species distributions. Oecologia 85, 74–79.

Stone, L. and Roberts, A. (1992) Competitive exclusion, or species aggregation? An aid in deciding. Oecologia 91, 419–424

Tylianakis, J. M., Tscharntke, T. and Lewis, O.T. (2007) Habitat modification alters the structure of tropical host-parasitoid food webs. Nature 445, 202–205

Watts, D. J. and Strogatz, S. (1998) Collective dynamics of ‘small-world’ networks. Nature 393, 440–442

See Also

This function can (and typically will) be called, with all its arguments, by networklevel. Several indices have their own function as implementation: second.extinct, degreedistr, C.score and V.ratio

Examples

## Not run: 
data(Safariland)
grouplevel(Safariland)
grouplevel(Safariland, level="lower", weighted=FALSE) #excludes degree distribution fits

## End(Not run)

Description

Calculates the overall level of specialisation of all interacting species in a bipartite web.

Usage

H2fun(web, H2_integer=TRUE)

Arguments

Details

H2' is an index describing the level of “complementarity specialisation” (or should one say: selectiveness?) of an entire bipartite network (Blüthgen et al. 2006). It describes to which extent observed interactions deviate from those that would be expected given the species marginal totals. The more selective a species, the larger is H2' for the web.

H2' is an extension of d' (see dfun) for the entire network.

For non-integer values, H2 max can be readily computed and is thus more reliable and much faster.

Value

Author(s)

Carsten F. Dormann and Jochen Fründ

References

Blüthgen, N., Menzel, F. and Blüthgen, N. (2006) Measuring specialization in species interaction networks. BMC Ecology 6, 9.

See Also

dfun following the same idea for each species in the web matrix.

Examples

data(Safariland)
H2fun(Safariland)

Description

This data set reports a community-level study of the pollination biology of alpine plants in Kosciusko National Park in the Snowy Mountains of south-eastern New South Wales, Australia. The flora and their associated insect pollinators were observed from December 1983 until March 1984.

Usage

data(inouye1988)

Format

A data frame with 41 observations on the following 83 variables, with plant species in rows and pollinators in columns.

Details

The authors recorded their data by counting the number of individual flower visitors caught on each plant species. The total number of individuals collected on each plant species provide a rough estimate of the level of visitation that each species received. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

Note

Male and female pollinators were summed when moving this data set from NCEAS to bipartite.

Source

NCEAS data base on interaction webs: https://iwdb.nceas.ucsb.edu/resources.html#plant_pollinator

References

Inouye, D.W. and G.H. Pyke (1988) Pollination biology in the Snowy Mountains of Australia: comparisons with montane Colorado, USA. Australian Journal of Ecology 13: 191–210.

Examples

data(inouye1988)
plotweb(inouye1988)

Description

A large (56 plant species by 257 visitor species) network published by Junker et al. (2013).

Usage

data(junker2013)

Format

The format is: int [1:56, 1:257] 0 0 0 0 0 0 1 0 0 0 ... - attr(*, "dimnames")=List of 2 ..$ : chr [1:56] "Achillea.millefolium" "Alliaria.petiolata" "Bellis.perennis" "Bunias.orientalis" ... ..$ : chr [1:257] "Agrypnus.murinus" "Ampedus.pomorum" "Anaspis.frontalis" "Anthaxia.nitidula" ...

Details

I modified some entries in the table: (1) There were two instances of Prunus.sp.1.Kirsche (cherry), which I summed and represented as one. Similarly, there (2) two species named Apidae_sp._1 and Apidae_sp.1 which I merged and (3) the exact same thing for Apidae_sp._2 and Apidae_sp.2. In all cases, only one or two observations were added to the column containing more counts. I do not think that these changes will have any effect on the analyses.

References

Junker, R. R., Blüthgen, N., Brehm, T., Binkenstein, J., Paulus, J., Schaefer, H. M. and Stang, M. 2013. Specialization on traits as basis for the niche-breadth of flower visitors and as structuring mechanism of ecological networks. Functional Ecology 27, 329–-341

Examples

data(junker2013)
## Not run: plotweb(junker2013)

Description

The study took place at the Kyoto University Forest of Ashu, at the northeastern boundry of the Kyoto Prefecture in Japan, between 1984 and 1987. The paper deals with the flowering phenology of 91 plant species, the community structure of flower-visiting insects, and the spectrum of floral hosts for flower visitors. The emphasis is laid on the pattern of community organization of flower-visiting insects in a primary forest ecosystem of western Japan.

The authors recorded their data by counting the number of individual flower visitors caught on each plant species. The total number of individuals collected on each plant species provide a rough estimate of the level of visitation that each species received. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction. For details and data see https://iwdb.nceas.ucsb.edu/resources.html#plant_pollinator

Usage

data(kato1990)

References

Kato, M., T. Makutani, T. Inoue, and T. Itino. 1990. Insect-flower relationship in the primary beech forest of Ashu, Kyoto: an overview of the flowering phenology and seasonal pattern of insect visits. Contr. Biol. Lab. Kyoto Univ. 27, 309–375

Examples

data(kato1990)
## maybe str(kato1990) ; plot(kato1990) ...

Description

The total number of individuals collected on each plant species provide a rough estimate of the level of visitation that each species received.

Usage

data(kevan1970)

Details

General information

This study sought to determine the importance of insect-flower relations to both plants and insects in a high arctic community as well as the degree to which some of the more common arctic plants are dependent on insects for pollination and reproduction. The research was conducted in 1967 at Hazen Camp (81 49'N, 71 18' W) near Lake Hazen on Northern Ellesmere Island, the most northerly island of the Canadian Arctic Archipelago.

Data type

The authors recorded their data by counting the number of individual flower visitors caught on each plant species. The total number of individuals collected on each plant species provide a rough estimate of the level of visitation that each species received. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

References

Kevan, P. G. 1970. High Arctic Insect-Flower Visitor Relations: The Inter-Relationships of Arthropods and Flowers at Lake Hazen, Ellesmere Island, Northwest Territories. University of Alberta, Canada.

Examples

data(kevan1970)

Description

Computes various indices of a network at the link-level, i.e. for each cell of the network matrix

Usage

linklevel(web, index=c("dependence", "endpoint"))

Arguments

Details

For summaries of such indices see networklevel. It's still early days for this function ...

Value

Returns a list of indices, each entry being a matrix of the same dimensions as the input web.

Note

This function aims to facilitate analyses at the link level. So far, most studies at this level did not correct for the fact that observations per cell are clearly non-independent, nor for the abundances of the species, which also greatly affect indices. Room for improvement, but little room for new findings ...

Author(s)

Carsten F. Dormann [email protected]

References

Barrat, A., Barthélemy, M., Pastor-Satorras, R. & Vespignani, A. (2004) The architecture of complex weighted networks. Proceedings of the National Academy of Sciences of the USA 101, 3747-–3752

See Also

endpoint, specieslevel

Examples

data(Safariland)
linklevel(Safariland)

Description

This function takes an object of class "moduleWeb" and returns information about the names of the nodes of which the computed modules exist.

Usage

listModuleInformation(moduleWebObject)

Arguments

Value

The value of the function is a list of lists of lists of vectors representing the names of the nodes involved in a certain module.

Author(s)

Rouven Strauss

Examples

## Not run: 
data(small1976)

moduleWebObject = computeModules(small1976);
moduleList = listModuleInformation(moduleWebObject);

## End(Not run)

Description

This study was conducted in a 150 m x 250 m meadow plot in the vicinity of Bristol, U.K. in July 1997. The objective was to describe the plant-flower visitor interaction web of this area, taking into account species abundances and their frequency of interaction. Twenty five plant species were studied, and 79 flower visitor species were recorded visiting them.

Usage

data(memmott1999)

Details

The author recorded her data by counting the number of visits of each flower visitor species to each plant species, and by independently measuring the abundance of plant and animal taxa. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

Source

NCEAS

References

Memmott, J. 1999. The structure of a plant-pollinator food web. Ecology Letters2, 276–280.

Examples

data(memmott1999)
## maybe str(memmott1999) ; plot(memmott1999) ...

Description

Generic network simulating algorithm based on a probability matrix and a desired number of interactions.

Usage

mgen(web, n=sum(web), keep.species=TRUE, rep.cell=TRUE, autotransform="sum_warn")

Arguments

Details

This is a generic function to simulate mutualistic networks, based on the original function with the same name used by Vázquez et al. (2009). This function can be used for different purposes, as it allows any type of probability matrix to be used for constructing the simulated matrices. However, this probability matrix must be derived from some other model, either fully synthetic or based on empirical data (if an observed network is given, it will sample from observed interactions, but this is not the typical use case). This function can thus be used for implementing various types of null models, but also highly structured or specialised webs.

The use of an externally generated probability matrix is a key difference to genweb and functions (methods) in nullmodel. Nevertheless, autotransfrom="equiprobable" turns mgen into a null model function, with interaction probabilities according to marginal totals (row and column sums). This null model does not fix row and column totals (otherwise it is similar to the r2dtable null model) nor connectance (in difference to vaznull); also, if keep.species=FALSE, species may be lost (i.e. have no interactions) by chance.

If rep.cell=TRUE, repeated interactions are added, thus generating a quantitative matrix with cell values as positive integers. In this case, connectance is not fixed or constrained. If rep.cell=FALSE, no repeated assignment of interactions is allowed, thus generating a binary matrix of zeros and ones. Note that when rep.cell=FALSE the number of interactions to be assigned must be equal or lower than the number of (nonzero) cells in the matrix. If also keep.species=TRUE, connectance is fixed (n / prod(dim(web))).

References

Vázquez, D. P.; Chacoff, N. P. & Cagnolo, L. 2009. Evaluating multiple determinants of the structure of mutualistic networks. Ecology 90 2039–2046

Examples

## Generate simulated matrix from homogeneous probability matrix
probmat <- matrix(1/100, 10, 10)
mgen(web=probmat, n=100)

## Generate binary matrix with probability proportional to degree
## of an observed binary matrix m
obs.mat <- matrix(c(1,1,1,1,1,1,1,1,1,0,1,1,1,0,0,1,1,0,0,0,1,0,0,0,0), 5, 5)
rs <- rowSums(obs.mat)
cs <- colSums(obs.mat)
web <- rs %*% t(cs)
web <- web/sum(web)
n = sum(obs.mat)
# Allowing zero marginal sums (but there will be none here):
mgen(web, n, keep.species=FALSE, rep.cell=FALSE) 
# Not allowing zero marginal sums:
mgen(web, n, keep.species=TRUE, rep.cell=FALSE) 

## Generate quantitative matrix with probability proportional
## to interaction frequency in an observed matrix m:
# Allowing zero marginal sums:
mgen(mosquin1967, keep.species=FALSE, rep.cell=TRUE) 
# Not allowing zero marginal sums: 
mgen(mosquin1967, keep.species=TRUE, rep.cell=TRUE)

Description

This class is the output of an application of the function computeModules to a graph. It consists of the matrix representing the original graph which has been passed to computeModules in order to compute modules, a matrix representing the same graph but permutated according to the identified modules, two vectors indicating the permutation of row and column indices, respectively, and information about the modules themselves.

Objects from the class

Objects from the class should only be created by using the function computeModules.

Slots

likelihood:

Contains a number with the likelihood-equivalent of the final proposed module structure. This value is the same value as Q (or M), the modularity as given by Newman or Guimerà & Amaral (2005).

originalWeb:

Object of class "matrix" representing the original bipartite graph in which modules have been computed.

moduleWeb:

Object of class "matrix" representing the original bipartite graph but reordered such that plotting modules is possible.

orderA:

Object of class "vector" representing the permutation of the rows of the original graph.

orderB:

Object of class "vector" representing the permutation of the columns of the original graph.

modules:

Object of class "matrix" containing for each module the information about its depth and involved nodes. The first row is just a consecutive number, so of no information; the first two columns can also be ignored. This matrix shows ALL network players (in the sequence of the original matrix, starting with rows), so first rows, then columns. There are as many rows as modules. Each row writes a number if a species is in that module, or a 0 if it isn't. For the modules of Safariland (mod <- computeModules(Safariland); mod@modules[-1, -c(1,2) ]), the third module are species 3 and 24, i.e. Schinus patagonicus (third row) and Ichneumonidae4 (24 - 9 column).

Methods

Objects of this class are used in following functions:

listModuleInformation(moduleWebObject)

printoutModuleInformation(moduleWebObject)

plotModuleWeb(moduleWebObject, plotModules=TRUE, rank=FALSE, weighted=TRUE, displayAlabels=TRUE, displayBlabels=TRUE, labsize=1, plotsize=12, xlabel="", ylabel="", square.border="white", fromDepth=0, upToDepth=-1)

Author(s)

Rouven Strauss

Examples

showClass("moduleWeb")

Description

This study took place on Melville Island, N.W.T., Canada from July 19 to July 31 1965. While collecting plants the authors made some observations on the occurence and behavior of flower visiting insects as well as on the scent and other target characteristics of flowers.

Usage

data(mosquin1967)

Details

The authors recorded their data by counting the number of individual flower visitors caught on each plant species. The total number of individuals collected on each plant species provide a rough estimate of the level of visitation that each species received. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

Source

NCEAS

References

Mosquin, T., and J. E. H. Martin. 1967. Observations on the pollination biology of plants on Melville Island, N.W.T., Canada. Canadian Field Naturalist 81, 201–205

Examples

data(mosquin1967)
## maybe str(mosquin1967) ; plot(mosquin1967) ...

Description

This is a study of the interactions between insects visitors and spring wildflowers in piedmont North Carolina. Spring flowering, entomophilous herbs, shrubs, and understory trees were included in the study.

Usage

data(motten1982)

Details

The author recorded his data by counting the number of visits of each flower visitor species to each plant species. Data are presented as an interaction frequency matrix, in which cells with positive integers indicate the frequency of interaction between a pair of species, and cells with zeros indicate no interaction.

References

Motten, A.F. (1982) Pollination Ecology of the Spring Wildflower Community in the Deciduous Forests of Piedmont North Carolina. Doctoral Dissertation thesis, Duke University, Durham, North Carolina, USA.

Motten, A.F. (1986) Pollination ecology of the spring wildflower community of a temperate deciduous forest. Ecological Monographs 56, 21–42

Examples

data(motten1982)
## maybe str(motten1982) ; plot(motten1982) ...

Description

Calculates normalised degrees, and two measures of centrality, betweenness and closeness. These two are based on one-mode representations of the network and invoke functions from sna.

Usage

ND(web, normalised=TRUE)
BC(web, rescale=TRUE, cmode="undirected", weighted=TRUE, ...)
CC(web, cmode="suminvundir", rescale=TRUE, ...)

Arguments

Details

These functions are convenience functions to enable easy reproduction of the type of analyses by Martín González et al. (2010). BC and CC are wrappers calling two functions from sna, which uses one-mode, rather than bipartite data.

One-mode projections of two-mode networks are carried out by assigning a link to two species that share a interaction with a member of the other set (plant in case of pollinators, or pollinators in case of plants). There are different ways to do this (see as.one.mode), and many authors do not communicate well, which approach they have taken.

If the network is fully connected, all species of the same level will be linked to each other through only one step and hence have the same betweenness. This leads to values of 0.

BC reflects the number of unique shortest paths going through the focal node. Note that different packages compute divergent values for betweenness, as detailed in the vignette (section 5.4.1)! CC is the inverse of the average distance from the focal node to all other nodes.

Both BC and CC can be normalised so that they sum to 1 (using rescale=TRUE). This only affects the absolute values, but not the qualitative results.

The interested user may want to also have a look at the networkX homepage (https://networkx.org) for a Python-based tool to analyse, depict and manipulate (one-mode) networks. It is not specifically meant for bipartite networks such as this package, though.

Value

A list with two entries, “lower” and “higher”, which contain a named vector of normalised degrees, betweenness centrality and closeness centrality, respectively. The lower-entry contains the lower trophic level species, the higher analogously the higher trophic level species.

Note

Experimental. Should work most of the time, but not necessarily always. Also, on trials with the same data as those of Martín González et al. (2010), numerical values differed. Whether this is due to rounding errors, different non-linear least square fits in JMP and R or whatever I cannot tell. See example for my attempt to reproduce their values for the network “Azores” (aka olesen2002flores).

Author(s)

Carsten F. Dormann [email protected]

References

Martín Gonzáles, A.M., Dalsgaard, B. and Olesen, J.M. 2010. Centrality measures and the importance of generalist species in pollination networks. Ecological Complexity 7, 36–41

See Also

centralization, betweenness and closeness in sna; specieslevel which calls them

Examples

## example:
data(olesen2002flores)
(ndi <- ND(olesen2002flores))
(cci <- CC(olesen2002flores))
(bci <- BC(olesen2002flores))

cor.test(bci[[1]], ndi[[1]], method="spear") # 0.532
cor.test(cci[[1]], ndi[[1]], method="spear") # 0.403

cor.test(bci[[2]], ndi[[2]], method="spear") # 0.738
cor.test(cci[[2]], ndi[[2]], method="spear") # 0.827
## Not run: 
## PLANTS:
bc <- bci[[1]]
cc <- cci[[1]]
nd <- ndi[[1]]
# CC:
summary(nls(cc ~ a*nd+b, start=list(a=1,b=1))) # lower RSE
summary(nls(cc ~ c*nd^d, start=list(c=0.072,d=0.2))) 
# BC:
summary(nls(bc ~ a*nd+b, start=list(a=1,b=1)))
summary(nls(bc ~ c*nd^d, start=list(c=2,d=2))) # lower RSE

## ANIMALS:
bc <- bci[[2]]
cc <- cci[[2]]
nd <- ndi[[2]]
# CC:
summary(nls(cc ~ a*nd+b, start=list(a=1,b=1)))  
summary(nls(cc ~ c*nd^d, start=list(c=0.2,d=2))) # lower RSE 
# BC:
summary(nls(bc ~ a*nd+b, start=list(a=1,b=1)))
summary(nls(bc ~ c*nd^d, start=list(c=0.2,d=2))) # lower RSE

## End(Not run)

Description

Calculates network nestedness, also within and between modules, i.e. separate nestednesses for nodes belonging to the same module and between nodes belonging to different modules. Three nestedness metrics are implemented in the function: NODF, WNODF and WNODA.

Usage

nest.smdm(x, constraints=NULL, weighted=FALSE, decreasing="fill", sort=TRUE)
  module2constraints(mod)

Arguments

Value

Function returns a list with elements

If constraints are provided, e.g. based on computeModules, output additionally includes:

Author(s)

Rafael Barros Pereira Pinheiro [email protected], Gabriel Felix, Marco Mello, and the team of the Ecological Synthesis Lab, University of São Paulo

References

Almeida-Neto M, Guimaraes PR, Guimaraes PR Jr, Loyola RD, Ulrich W (2008) A consistent metric for nestedness analysis in ecological systems: reconciling concept and measurement. Oikos 117: 1227–1239

Almeida-Neto, M. & Ulrich, W. (2011). A straightforward computational approach for measuring nestedness using quantitative matrices. Environ. Model. Softw. 26: 173–178

Felix, G.M., Pinheiro, R.B.P., Poulin, R., Krasnov, B.R. & Mello, M.A.R. (2017). The compound topology of a continent-wide interaction network explained by an integrative hypothesis of specialization. bioRxiv

Flores, C.O., Valverde, S. & Weitz, J.S. (2013). Multi-scale structure and geographic drivers of cross-infection within marine bacteria and phages. ISME J. 7: 520–532

See Also

vegan::nestedNODF, computeModules

Examples

nest.smdm(Safariland)
nest.smdm(Safariland, weighted=TRUE)
nest.smdm(Safariland, weighted=TRUE, decreasing="abund")
nest.smdm(Safariland, weighted=TRUE, decreasing="abund", sort=FALSE)
# identify modules using computeModules:
mod <- computeModules(Safariland)
const <- module2constraints(mod)
nest.smdm(Safariland, constraint=const)
nest.smdm(Safariland, constraint=const, weighted=TRUE)

Description

Wrapper function calling one, several or all currently implemented nestedness measures

Usage

nested(web, method = "binmatnest", rescale=FALSE, normalised=TRUE)

Arguments

Details

There are seven different measures (with variations yielding ten indices) currently available:

1

binmatnest calculates nestedness temperature following the function nestedtemp (0 = cold = highly nested; 100 = hot = not nested at all). (Note that we replaced binmatnest, which calls the retired nestedness, which used the original C++-program of Miguel Rodriguez-Girones, by what used to be binmatnest2. Because binmatnest sometimes (and to us unexplicably) invert the matrix, we prefer the vegan's binmatnest2, now binmatnest, option. That is the implementation by Jari Oksanen in nestedtemp of the same algorithm.)

2

Discrepancy calculates the number of non-nested 0s and 1s. While discrepancy calls the function with the same name, discrepancy2 calls nesteddisc, which handles ties differently. Most of the time, these two should deliver very, very similar results. Higher values indicate lower nestedness.

3

NODF is the nestedness measure proposed by Almeida-Neto et al., correcting for matrix fill and matrix dimensions. Values of 0 indicate non-nestedness, those of 100 perfect nesting. NODF2 sorts the matrix before calculating the measure. NODF is, I understand, closer to the version presented in the paper, while NODF2 seems to make more sense for comparisons across different networks (because it is independent of the initial presentation of the matrix). Both call nestednodf in vegan. (Yes, I initially programmed NODF myself, only to find that it was there already. Luckily, there was a perfect agreement between my (depricated) version and nestednodf.) A weighted version is also now available (see point 6 below), following the paper of Almeida-Neto and Ulrich (2010).

4

C.score calculates the number of checkerboard pattern in the matrix. As default, it normalises this value between min and max, so that values of 0 indicate no checkerboards (i.e. nesting), while a value of 1 indicates a perfect checkerboard. checker is the non-normalised version, based on nestedchecker.

5

wine is one of two nestedness measure using the information on the weight of a link. See wine for details.

6

weighted NODF is a version of 3, but now incorporating information on the weights of the link; it is the second quantitative nestedness measure, (chronologically) after wine. It uses the sorted matrix to compute NODF. If you want NODF of the unsorted, you have to directly use nestednodf in vegan.

7

weighted NODA, or WNODA, does try to give a good nestedness measure without correcting for column/row expectations, as that should be left to the null model; see Félix et al. (2017) for details. Also, NODA accounts for modular structures of the network, computing nestedness separately in each (see nest.smdm for further details).

Value

A vector with values for each of the selected nestedness measures.

Note

The idea behind this function is to encourage the comparison of different nestedness measures. That does not mean, we necessarily see much ecological sense in them (see, e.g., the paper by Blüthgen et al. 2008).

nested uses one non-default setting for the nestedness measures called: null.models=FALSE. This is simply to speed up the computation. Null models should be built for all nestedness measures, of course, not only for nestedness!

Author(s)

Carsten F. Dormann [email protected]

References

Almeida-Neto, M., Guimaraes, P., Guimaraes, P.R., Loyola, R.D. and Ulrich, W. 2008. A consistent metric for nestedness analysis in ecological systems: reconciling concept and measurement. Oikos 117, 1227–1239.

Almeida-Neto, M. and Ulrich, W. (2011) A straightforward computational approach for measuring nestedness using quantitative matrices. Environmental Modelling & Software, 26, 173–178

Blüthgen, N., J. Fründ, D. P. Vazquez, and F. Menzel. 2008. What do interaction network metrics tell us about specialisation and biological traits? Ecology 89, 3387–3399.

Brualdi, R.A. and Sanderson, J.G. 1999. Nested species subsets, gaps, and discrepancy. Oecologia 119, 256–264.

Felix, G.M., Pinheiro, R.B.P., Poulin, R., Krasnov, B.R. & Mello, M.A.R. (2017). The compound topology of a continent-wide interaction network explained by an integrative hypothesis of specialization. bioRxiv

Galeano, J., Pastor, J.M., Iriondo and J.M. 2008. Weighted-Interaction Nestedness Estimator (WINE): A new estimator to calculate over frequency matrices. arXiv 0808.3397v2 [physics.bio-ph]

Rodríguez-Gironés, M.A. and Santamaría, L. 2006. A new algorithm to calculate the nestedness temperature of presence-absence matrices. J. Biogeogr. 33, 924–935.

Stone, L. and Roberts, A. 1990. The checkerboard score and species distributions. Oecologia 85, 74–79.

Almeida-Neto, M. and Ulrich, W. 2010. A straightforward computational approach for measuring nestedness using quantitative matrices. Environmental Modelling & Software, in press.

See Also

C.score, wine, nestedness, discrepancy; and, within vegan: nestedtemp, nestedchecker, nesteddisc, nestednodf

Examples

## Not run: 
data(Safariland)
nested(Safariland, "ALL")
nested(Safariland, "ALL", rescale=TRUE)
# illustration that non-normalised C.score and checker are the same:
nested(Safariland, c("C.score", "checker"), normalise=FALSE)

## End(Not run)

Description

Estimates the degree to which the interactions of each row and column species increase or decrease community nestedness.

Usage

nestedcontribution(web, nsimul = 99)

Arguments

Details

The idea behind nestedness contribution is to determine how individual species' interactions change community nestedness compared to a random null model that is designed to control for the effect of differences in degree. For each row and column species, this function compares observed nestedness to an ensemble of nestedness values generated by randomizing the interactions of just that focal species. Nestedness contributions are the z-scores from this comparison. Therefore, a positive contributor to community nestedness (i.e., a species whose interactions increase overall nestedness) will obtain values greater than 0 and negative contributors to nestedness will obtain values less than 0.

Value

For both the “higher trophic level” and the “lower trophic level”, this function returns a data frame with the per-species nestedness contributions.

Note

This function calculates per-species nestedness contributions as described in Saavedra et al. 2011—namely it is based on the metric NODF to measure nestedness and employs a probabilistic null model to randomize interactions (that is described in Bascompte et al. 2003). The underlying methodology is amenable to other choices in both of these cases; however, this is not implemented at present.

The currently implemented null model replaces the observed vector of 0/1s by a probabalistic draw of 0/1s as given by the mean of mean degree in the higher trophic level (rowSums(web)/ncol(web)) and the mean degree for the target higher trophic level species i (colSums(web)[i]/nrow(web)).

Author(s)

Daniel B. Stouffer [email protected]

References

Bascompte, J., Jordano, P., Melián, C.J., and Olesen, J.M. 2003. The nested assembly of plant-animal mutualistic networks. Proceedings of the National Academy of Sciences of the USA 100, 9383–9387

Saavedra, S., Stouffer, D.B., Uzzi, B., and Bascompte, J. 2011. Strong contributors to network persistence are the most vulnerable to extinction. Nature 478, 233–235

Examples

data(Safariland)
  ## Not run: 
    nestedcontribution(Safariland)
  
## End(Not run)

Description

Deprecated: Calculates matrix temperature using the binmatnest approach of Miguel Rodríguez-Gironés

Usage

nestedness(m, null.models = TRUE, n.nulls = 100, popsize = 30, 
n.ind = 7, n.gen = 2000, binmatnestout=FALSE)

Arguments

Details

This is a note that the original function provided here, and detailed below, has been retired. vegan's nestedtemp is more stable and replaces this call whereever we use it in bipartite. Indeed, calling bipartite's nestedness now simply call's vegan's nestedtemp. The function will eventually disappear, but for now this fix is provided as legacy support for dependent packages.

All arguments except first are ignored.

There are several implementations of nestedness-calculators, most noticeably NTC (nestedness temperature calculator), BINMATNEST and aninhado (check Wikipedia's entry on the subject: https://en.wikipedia.org/wiki/Nestedness). While we used BINMATNEST, this does not disqualify any of the others. Miguel was simply the first we contacted and he was readily willing to share his code.

We used BINMATNEST by calling a tweaked version of the C++ program binmatnest. In principle nestedness temperature is calculated by using a line of perfect order (using a genetic algorithm) to determine the reordering of rows and columns that leads to minimum matrix temperature of given size and fills. The deviation from this minimun temperature is the matrix temperature. In addition nestedness uses different null models to check for statistical significance of the matrix temperature. For details on what BINMATNEST does different, and better, than the original NTC see reference below.

Notice also that the original software BINMATNEST is available as a stand-alone application. Check out Miguel's homepage: http://www.eeza.csic.es/eeza/personales/rgirones.aspx

Value

References

Rodríguez-Gironés M.A., and Santamaría L. 2006. A new algorithm to calculate the nestedness temperature of presence-absence matrices. Journal of Biogeography 33, 924–935

Description

Ranks species according to their generality, which is measured as the position in the nestedness matrix. A generalist will interact with more species and thus have a rank closer to 1, while specialists (and rare species) will have ranks with higher values.

Usage

nestedrank(web, method = "NODF", weighted=TRUE, normalise=TRUE, return.matrix=FALSE)

Arguments

Details

The idea is to re-arrange the network matrix according to its nestedness, so that the most “generalist” species with most links will be in the first row/column and decreasing from there. The nestedness matrix can be computed in different ways. There are four different methods currently available:

NODF (or nodf)

will use vegan's nestednodf-function to arrange the matrix. With weighted=TRUE, which is the default, it will use the actual number of interactions, rather than the number of links

binmatnest

will use the vegan's nestedtemp-function to arrange the matrix. This is only using binary information, so weighting has no effect.

wine

will use the wine-function to arrange the matrix. When weighted=FALSE, wine will be applied to a binary matrix.

sort

will simply sort the matrix by marginal totals (i.e. by number of interactions per species when weighted=TRUE or by number links (=degree) when weighted=FALSE. In this case the rank simply represents the abundance of the species in this network.

Value

A list of nestedness ranks vectors for the lower and higher trophic level (smallest value for the most generalist). If return.matrix=TRUE, a third list entry will contain the nested matrix.

Note

Since nestedness is itself not a straight-forward measure of something ecologically meaningful, also these ranks may or may not be. At least there is a high chance that they represent merely abundance of each species. See example for an idea on how to check for the effect of abundance as such.

Author(s)

Carsten F. Dormann [email protected]

References

Alarcon, R., Waser, N.M. and Ollerton, J. 2008. Year-to-year variation in the topology of a plant-pollinator interaction network. Oikos 117, 1796–1807

See Also

nested; nestedrank is called by specieslevel

Examples

## Not run: 
ranks <- sapply(c("nodf", "binmatnest", "wine", "sort"), function(x) 
  nestedrank(Safariland, method=x)[[2]])
cor(ranks) # high correlation between sort and other indicate that only abundance matters

## End(Not run)

Description

Calculates a variety of indices and values for a bipartite network

Usage

networklevel(web, index="ALLBUTDD", level="both", weighted=TRUE, 
   ISAmethod="Bluethgen",  SAmethod = "Bluethgen", extinctmethod = "r", 
   nrep = 100, CCfun=median, dist="horn", normalise=TRUE, empty.web=TRUE, 
   logbase="e", intereven="prod", H2_integer=TRUE, fcweighted=TRUE, 
   fcdist="euclidean", effective=FALSE, legacy=FALSE)

Arguments

Details

For explanations of any of the indices computed for a level (i.e. those with HL and/or LL suffix), please see grouplevel for details.

This function implements a variety of the many (and still procreating) indices describing network topography. Some are embarrassingly simple and mere descriptors of a network's outer appearance (such as number of species in each trophic level or the number of links (= non-zero cells) in the web). Others are variations on Shannon's diversity index applied to within column or within rows. Only extinction slope is newly implemented here, and hence described in a bit more detail.

Currently, you cannot get the qualitative version of quantitative indices such as vulnerability!

Integers or continuous values - what are the quantities in quantitative webs? Some web metrics expect in their typical formulation that the entries in the web-matrix are integers - e.g. H2' is defined relative to minimum and maximum based on marginal totals. Blüthgen et al. (2006) use an algorithm assuming values can only be integers. If your quantities are not constrained to be integers, multiplication and rounding may or may not give consistent results, depending on rounding errors and the factor applied. Multiplication with high numbers such as 10 000 seems to be OK. For H2' a simplified calculation applicable to continuous numbers is available (by declaring option H2_integer=FALSE in H2fun). Note that values of H2' based on integers are not directly comparable to H2' based on continuous values (for sparse webs, H2'_continuous is much higher than H2'_integer). We tentatively think that other indices are hardly affected by non-integer values or by multiplication and rounding. Please let us know your experience.

Value

The suffixes LL and HL refer to lower and higher level, respectively

Depending on the selected indices, some or all of the below (returned as vector if “degree distribution” was not requested, otherwise as list):

Note

Sum or Prod: How to calculate interaction evenness? I shall first put down my argument for “prod” and then Jason Tylianakis' arguments for “sum”.

Carsten: “I do not want to defend a position I cannot hold against the flood of qualified criticism, and shall be happy to change the default to option “sum” (i.e. Jason's proposal). Nevertheless, I shall make a very brief attempt to defend my (and Nico's point of view). Imagine a completely different situation: I have “counted” birds in a landscape. From a more meticulous colleague I know that there are 27 bird species breeding at the moment, but on that two mornings that I went out, I could only hear 15. Now I want to calculate the Shannon diversity (and evenness) of birds in that landscape. The “normal” (in the sense of established) approach to use the data from my 15 species. But hold on: I KNOW there are more species out there. I don't know how many (i.e. there may be more than the 27 my colleague has found), but there are at least 27. If I only use the data from my 15 species, I will get a higher evenness value than when I also include the 12 zeros. My conclusion would be: I don't want to overestimate evenness only because I couldn't look long enough, thus I use all 27 values.”

Jason: “I would disagree because what you “know” is based on your meticulous colleague's ‘sampling’, which will also have its limits. If all you wanted was to know the total number of species there (assuming none have gone extinct), then what you propose is fine. However, the problem comes when you want to compare sites, and then sampling effort should be standardised. In most cases we know we don't have a full representation of the diversity (or food web) of an area, but we know for a given spatial or temporal sampling scale that one site differs from another in certain ways, and to me that is the most important. Anyway, it is all a question of scale and the precise question being asked. So what about making it an option in bipartite that you can either choose to divide by the realised links (give our 2007 paper as a ref, so people know it's comparable to that) or divide by the number of potential links, if that's the question people want to ask?” There you go: it's your choice!

NA values: All error and warning messages are (or at least should be) suppressed! If your web returns and NA for some of the indices, this can be because the index cannot be computed. For example, if the web is full (i.e. no 0-cells), extinction slopes cannot be fitted (singularity of gradient). Check if you can expect the index to be computable! If it is, and networklevel doesn't do it, let me know.

Reducing computation time: Some indices require rather long computation times on large webs. If you want to increase the speed by omitting some indices, here a rough guide: Ask only for the indices you are interested in! Otherwise, here is the sequence of most time-consuming indices:

1. The slowest function is related to extinction slopes and robustness. Excluding both makes the function faster.

2. weighted cluster coefficient is also very time consuming (an exhaustive search for 4-loops in the one-mode projection of the network). Omitting it can dramatically boost speed.

3. Degree distributions are somewhat time consuming.

4. Fisher's alpha is computed iteratively and hence time consuming.

5. Nestedness and weighted nestedness are not the fastest of routines.

6. Number (and diversity) of compartments calls a recursive and hence relatively slow algorithm.

7. H2 and specialisation asymmetry require an iterative, heuristic search algorithm. Finally, excluding discrepancy can also moderately decrease computation time.

Does the species sequence in the data matter? Obviously, it shouldn't, and for most indices it doesn't. However, particularly indices based on binary representation of web will have ties, where several species have the number of links. In this case, it does matter how the matrix is sorted before simulating extinctions or computing discrepancy. There is no (known) foolproof way to get this sequence "right" (see also "Details" of help for nesteddisc). Re-running the same code with a shuffled network may thus yield (slightly) different values for (weighted) nestedness, togetherness, discrepancy, extinction slopes and robustness. (Thanks to Valentin Stefan for making us explicitly addressing this issue!)

Author(s)

Carsten F. Dormann [email protected]

References

Almeida-Neto, M., Loyola, R.D., Ulrich, W., Guimaraes, P., Guimaraes, Jr., P.R. 2008. A consistent metric for nestedness analysis in ecological systems: reconciling concept and measurement. Oikos 117, 1227–1239

Almeida-Neto, M. & Ulrich, W. (2011) A straightforward computational approach for measuring nestedness using quantitative matrices. Environmental Modelling & Software 26, 173–178

Bascompte, J., Jordano, P. and Olesen, J. M. 2006 Asymmetric coevolutionary networks facilitate biodiversity maintenance. Science 312, 431–433

Bersier, L. F., Banasek-Richter, C. and Cattin, M. F. (2002) Quantitative descriptors of food-web matrices. Ecology 83, 2394–2407

Blüthgen, N. (2010) Why network analysis is often disconnected from community ecology: A critique and an ecologist's guide. Basic and Applied Ecology 11, 185–195

Blüthgen, N., Menzel, F., Hovestadt, T., Fiala, B. and Blüthgen N. 2007 Specialization, constraints and conflicting interests in mutualistic networks. Current Biology 17, 1–6

Burgos, E., H. Ceva, R.P.J. Perazzo, M. Devoto, D. Medan, M. Zimmermann, and A. Maria Delbue (2007) Why nestedness in mutualistic networks? Journal of Theoretical Biology 249, 307–313

Corso G, de Araújo AIL, de Almeida AM (2008) A new nestedness estimator in community networks. arXiv 0803.0007v1 [physics.bio-ph]

Devoto M., Bailey S., Craze P., and Memmott J. (2012) Understanding and planning ecological restoration of plant-pollinator networks. Ecology Letters 15, 319–328. http://dx.doi.org/10.1111/j.1461-0248.2012.01740.x

Dormann, C.F., Fründ, J., Blüthgen, N., and Gruber, B. (2009) Indices, graphs and null models: analysing bipartite ecological networks. The Open Ecology Journal 2, 7–24.

Dunne, J. A., R. J. Williams, and N. D. Martinez 2002. Food-web structure and network theory: the role of connectance and size. Proceedings of the National Academy of Science USA 99, 12917–12922

Galeano, J., Pastor, J.M. and Iriondo, J.M. 2008. Weighted-Interaction Nestedness Estimator (WINE): A new estimator to calculate over frequency matrices. arXiv 0808.3397v1 [physics.bio-ph]

Gotelli, N. J., and G. R. Graves. 1996 Null Models in Ecology. Smithsonian Institution Press, Washington D.C.

Jost, L. 2010. The relation between evenness and diversity. Diversity 2, 207–232. https://doi.org/10.3390/d2020207

Krebs, C. J. 1989. Ecological Methodology. Harper Collins, New York.

Memmott, J., Waser, N. M. and Price M. V. 2004. Tolerance of pollination networks to species extinctions. Proceedings of the Royal Society B 271, 2605–2611

Müller, C. B., Adriaanse, I. C. T., Belshaw, R. and Godfray, H. C. J. 1999. The structure of an aphid-parasitoid community. Journal of Animal Ecology 68, 346–370

Roberts, A. and Stone, L. 1990 Island-sharing by archipelago species. Oecologia 83, 560–567

Rodríguez-Girónes M.A., and Santamaría L. 2006. A new algorithm to calculate the nestedness temperature of presence-absence matrices. Journal of Biogeography 33, 924–935

Schluter, D. 1984. A variance test for detecting species associations, with some example applications. Ecology 65, 998-1005.

Stone, L. and Roberts, A. 1990. The checkerboard score and species distributions. Oecologia 85, 74–79.

Stone, L. and Roberts, A. 1992. Competitive exclusion, or species aggregation? An aid in deciding. Oecologia 91, 419–424

Tylianakis, J. M., Tscharntke, T. and Lewis, O.T. 2007. Habitat modification alters the structure of tropical host-parasitoid food webs. Nature 445, 202–205

Watts, D. J. and Strogatz, S. 1998. Collective dynamics of ‘small-world’ networks. Nature 393, 440–442

See Also

Some functions are implemented separately: H2fun, second.extinct, degreedistr, C.score and V.ratio

Examples

## Not run: 
data(Safariland)
networklevel(Safariland)
networklevel(Safariland, index="ALLBUTDD") #excludes degree distribution fits

## End(Not run)

Description

Calculates a specialisation index based on the node positions for all species in a bipartite network, separately for the higher and lower trophic level.

Usage

nodespec(web, inf.replace = NA)

Arguments

Details

This index aims to describe the functional specialisation of pollinators and was proposed by Dalgaard et al. (2008). It is a purely qualitative measure.

After calculating the geodesic distances between species, i.e. the minimum number of steps from one species to another, these values are averaged for each species. This mean geodesic distance is interpreted as functional specialisation (Dalgaard et al. 2008).

Notice that this “new” index is in fact little else than the inverse of (unscaled) closeness centrality in disguise.

Value

A list with two components, names “higher” and “lower”, both containing the node specialisation index for each species.

Note

This index is as yet unevaluated. We don't know how it responds to true specialisation at all. In fact, it is a rather good example of how to get a new thing published without even having demonstrated in which way it differs from existing indices of specialisation (such as standardised d included in the function dfun), or how it performs on artificial data with known properties.

One major disadvantage of any index based on path lenghts is its difficulty with compartments, i.e. species not linked to the rest of the network. There are, generally speaking, three ways to handle this: Firstly, ignore it (that is, set infinite distances to NA; our default). Secondly, leave it as it is (that is, leave infinite distances as infinite). This is not really an option, since then ALL species would have infinite specialisation values. Thirdly, replace infinite by the largest distance plus one (see comments in geodist in sna). That would probably be a plausible thing to do, since we could argue that with a little bit extra observation we might have found a species linking a compartment to the rest of the network. However, this solution is “not canonical”, as put in geodist and hence biased to an unknown extent. To use this option, specify inf.replace=Inf.

Author(s)

Carsten F. Dormann [email protected]

References

Dalsgaard, B., Martín González, A. M., Olesen, J. M., Timmermann, A., Andersen, L. H. and Ollerton, J. (2008) Pollination networks and functional specialization: a test using Lesser Antillean plant-hummingbird assemblages. Oikos 117, 789–793

See Also

See also as specieslevel, which calls nodespec.

Examples

data(Safariland)
nodespec(Safariland, inf.replace=Inf)

Description

This index computes a variation of nestedness, called node overlap and segragation, as well as a modularity measure

Usage

NOS(web, keep.Nij=FALSE, keep.diag=FALSE)

Arguments

Details

According to the authors, NOS is “a new statistical procedure to measure both [the tendency of network nodes to share interaction partners] and the opposite one (i.e. species’ tendency against sharing interacting partners) that we call ‘node segregation’. In addition, our procedure provides also a straightforwardmeasure of modularity, that is, the tendency of a network to be compartmented into separated clusters of interacting nodes.”

Value

Author(s)

Carsten F. Dormann [email protected], with additional code provided by “tchen98” (on github).

References

Strona, G., and Veech, J.A. (2015) A new measure of ecological network structure based on node overlap and segregation. Methods in Ecology & Evolution 15, 319–328

See Also

grouplevel, which eventually shall use this function.

Examples

data(Safariland)
# illustrate difference between keeping/removing the diagonal:
NOS(Safariland)
NOS(Safariland, keep.diag=TRUE)

Description

Computes network indices for networks that are represented as stacks of bipartite networks (“npartite”), thus having many impossible links.

Usage

npartite(as.one.mode.web, index=c("connectance", "links per species", "mean degree"))

Arguments

Value

A named list of indices.

Note

An attempt is made to ensure that these indices converge to the same value as returned for a bipartite network!

Author(s)

Carsten F. Dormann [email protected]

See Also

as.one.mode.

Examples

image(aomw <- as.one.mode(Safariland, fill=NA))
npartite(aomw)
networklevel(Safariland, index=c("connectance", "links per species"))

Description

Given a network, this function fits a distribution to the marginal totals and then draws randomly from this distribution to yield a new network

Usage

null.distr(N, web, distr="lognormal")

Arguments

Details

This package provides several functions to generate null models for the observed data (see nullmodel). However, this function deviates from any of these in that it does not hold the marginal totals as constant. Rather, it sees them as a random draw of some underlying distribution. This distribution is fitted (in a very ad hoc manner) to the data. The inspiration for this function comes from Bl¸thgen et al. (2008).

In the next step, the same number of species is drawn from this distribution randomly, and a new matrix is generated as the cross-product of these new vectors. The matrix is then standardised to sum to 1. It now serves as probability of drawing an interaction for any of its cells.

As many interactions as were observed are drawn (given the above probabilities) and hence a new, null matrix is generated.

In case of the negative binomial fit (and random draw), some 0-values will result from the random draws. As a consequence, the dimension of the matrix can be dramatically lower than the observed. To avoid this, I simply add 1 to each marginal total value. Again, this is very ad hoc and not statistically justified. In fact, values already large should not receive an additional observation (as shown by Dewdney 1998 in a very different context).

NOTE 1: The fitted distribution is not supposed to represent the true distribution behind the abundances, but merely one way to have new marginal totals. In fact, in many cases the marginal totals aren't lognormal (or negative binomial), but much more skewed than that!

NOTE 2: Although the dimensions of the new, null web CAN be the same as that of the original, quite often they will be lower. This is because some species have a very low probability of being observed, and only in webs with many observations they will be. Stochasticity may render some species unobserved. The consequences are potentially large! As species are lost, relative linkage density goes up automatically, which affects virtually every network index!

Value

A list of N new matrices with the same number of interactions, but possibly different dimensions.

Author(s)

Carsten F. Dormann <[email protected]>

References

Blüthgen, N., Fründ, J., Vázquez, D. P. and Menzel, F. 2008. What do interaction network metrics tell us about specialisation and biological traits? Ecology, 89, 3387–3399.

Dewdney, A.K. 1998. A general theory of the sampling process with applications to the “veil line”. Theoretical Population Biology, 54, 294–302.

See Also

nullmodel

Examples

## Not run: 
data(Safariland)
null.distr(N=2, Safariland)
null.distr(N=2, Safariland, distr="negbin")

round(networklevel(Safariland, "info"), 3)
sapply(null.distr(N=5, Safariland), function(x) networklevel(x, index="info"))
# highly connected
sapply(null.distr(N=5, Safariland, distr="negbin"), function(x) networklevel(x, 
	index="info")[3])
# similarly highly connected

## End(Not run)

Description

A little null-model function to check, if the observed values actually are much different to what one would expect under random numbers given the observed row and column totals (i.e.~information in the structure of the web, not only in its species' abundances). Random matrices are based on the function r2dtable. The test itself is a t-test (with all its assumptions).

Usage

null.t.test(web, N = 30, ...)

Arguments

Details

This is only a very rough null-model test. There are various reasons why one may consider r2dtable as an incorrect way to construct null models (e.g.~because it yields very different connectance values compared to the original). It is merely used here to indicate into which direction a proper development of null models may start off. Also, if the distribution of null models is very skewed, a t-test is obviously not the test of choice.

Finally, not all indices will be reasonably testable (e.g.~number of species is fixed), or are returned by the function networklevel in a form that null.t.test can make use of (e.g.~degree distribution fits).

Value

Returns a table with one row per index, and columns giving

Note

This function is rather slow. Using large replications in combination with iterative indices (degree distribution, compartment diversity, extinction slope, H2) may lead to rather long runtimes!

Author(s)

Carsten F. Dormann [email protected]

Examples

data(mosquin1967)
null.t.test(mosquin1967, index=c("generality", "vulnerability",
    "cluster coefficient", "H2", "ISA", "SA"), nrep=2, N=10)

Description

A wrapper function for convenient generation of null models for quantitative and binary networks

Usage

nullmodel(web, N=1000, method="r2d", ...)

Arguments

Details

ADVICE: Look at the same-named function in vegan, as well as the long list of potential null models described in commsim in that package. It offers a richer and more standardised implementation of null models than this (earlier) function. In particular the method shuffle.web is potentially confusing, as it calls bipartite's shuffle.web for quantitative networks, but vegan's quasiswab algorithm for binary. Since vegan also now offers the argument greedyqswap for quantitative networks, please have a look at vegan's nullmodel function.

This is only a wrapper function to facilitate and standardise the generation of null models.

These null models assume that interaction weights are integers that represent frequencies that are “individually” counted, not decimal numbers. Multiplication by 1000 (say) and rounding does NOT necessarily make your value frequencies satisfy this assumption. Null models for “continuously quantitative” webs still have to be developed!

A warning is returned when all entries in a quantitative network are 0 or 1 (which suggests a binary network).

Value

Returns a list of N null model-generated networks. Species names are (obviously) dropped.

Note

When a quantitative network contains only 1s (as may happen when sampling intensity is low), the quantitative null model will be extremely similar (often identical) to the observed network. This is no error. It is reflecting the fact that this network contains little (no) information beyond the abundances.

Author(s)

Carsten F. Dormann [email protected]

See Also

For the functions generating the null model network: shuffle.web, swap.web, vaznull, mgen, vegan::simulate and r2dtable

Examples

## Not run: 
	data(Safariland)
	nullmodel(Safariland, N=2, method=1)
	nullmodel(Safariland>0, N=2, method=4)
	# analysis example:
	obs <- unlist(networklevel(Safariland, index="weighted nestedness"))
	nulls <- nullmodel(Safariland, N=100, method=1)
	null <- unlist(sapply(nulls, networklevel, index="weighted nestedness")) #takes a while ...
	
	plot(density(null), xlim=c(min(obs, min(null)), max(obs, max(null))), 
		main="comparison of observed with null model Patefield")
	abline(v=obs, col="red", lwd=2)    
	
	praw <- sum(null>obs) / length(null)
	ifelse(praw > 0.5, 1-praw, praw)    # P-value
	
	# comparison of null model 4 and 5 for binary:
	nulls4 <- nullmodel(Safariland>0, N=100, method=4)
	nulls5 <- nullmodel(Safariland>0, N=100, method=5)
	null4 <- unlist(sapply(nulls4, networklevel, index="weighted nestedness"))
	null5 <- unlist(sapply(nulls5, networklevel, index="weighted nestedness"))
	
	
	plot(density(null4), xlim=range(c(null4, null5)), lwd=2, 
		main="comparison of null models")
	lines(density(null5), col="red", lwd=2)
	legend("topright", c("shuffle", "mgen"), col=c("black", "red"), lwd=c(2,2), 
		bty="n", cex=1.5)
	abline(v=networklevel(Safariland>0, index="weighted nestedness"))
	
## End(Not run)