Daniel S. Maynard, Carlos A. Serván, Stefano Allesina (2018) Ecology Letters, doi: 10.1111/ele.12912

The corresponding R files include assembly_functions.R, which contains the core functions for building communities; and launch_assembly.R, which contains various examples. These can be downloaded from the R_code folder at https://github.com/dsmaynard/network_spandrels.

Assembling communities

The code requires the following R packages:

Once the packages are installed, the next step is to source the main R file containing the assembly functions:

source("assembly_functions.R")

At this point, there are seven assembly scenarios to choose from:

  1. notraits_immigration_search (immigration, no traits)
  2. notraits_immigration_uniform (immigration, no traits, uniform search)
  3. notraits_radiation_search (radiation, no traits)
  4. traits_binary_immigration (immigration, binary traits)
  5. traits_binary_radiation (radiation, binary traits)
  6. traits_continuous_immigration (immigration, continuous traits)
  7. traits_continuous_radiation (radiation, continuous traits)

To call one of these scenarios, use the assemble_community function. The program will run until the number of unique species in the community reaches target_size. Here, we are using a niche-overlap traits model with binary traits, and species are joining via immigration. We specify a total of 100 traits (default ntraits=200), with each species being assigned 30% of the traits (default bin.prob=0.50).

outcom<-assemble_community(target_size=50,scenario="traits_binary_immigration",ntraits=100,bin.prob=0.3)
## [1] "Iteration 20. Found 19 of 50 species."
## [1] "Iteration 40. Found 33 of 50 species."
## [1] "Iteration 60. Found 46 of 50 species."

In the radiation scenarios, we can also specify the mutation rate (default mutation.rate=0.03):

outcom<-assemble_community(50,scenario="traits_binary_radiation",mutation.rate=0.05,show.prog=F)

(In the above, we also suppress the printing of the assembly status with show_prog=F.)

Changes to the default threshold for survival (default THRESH=1e-6) or the initial abundance of the invader (default INITIAL=1e-5) can be passed to any assembly scenario:

outcom<-assemble_community(50,scenario="notraits_immigration_search",INITIAL=1e-3,THRESH=1e-8,show_prog=F)

Currently, all growth rates are set equal to r=1 by default, and the intraspecific interaction coefficients are all set equal to a_ii=-1. These defaults can be changed in the assemble_community function call, but doing so has not been fully tested – so experiment at your own risk!

Plotting the observed and expected spectra

For any scenario, the observed and expected spectra (eigenvalue distribution) can be plotted by using the compare_spectra function, which will plot the observed histogram and the expected histogram. In the no-traits scenarios, the expected histogram is given by the semicircle law:

outcom<-assemble_community(50,scenario="notraits_immigration_search",show_prog=F)
compare_spectra(outcom)

And in the traits scenarios, the null distribution of the scaled covariance matrix is given by the Marchenko-Pastur distribution:

outcom<-assemble_community(50,scenario="traits_binary_immigration",show_prog=F)
compare_spectra(outcom)

Calculating network metrics

The interaction matrix can be discretized into a binary 1-0 matrix for calculating network metrics. Here, the strongest 10% of the interactions are set equal to 1, and the weakest 90% of the interactions are set equal to zero:

Abin<-binarize_A(outcom,cutval=0.9)

At which point, the values of nestedness, modularity, or motif counts can be calculated on the binary matrix:

motifs_func(Abin)
## [1] 427
nestedness_func(Abin)
## [1] 5.142331
modularity_func(Abin)
## [1] 0.3816598

Creating a custom assembly scenario

The assemble_community function is quite general. If you want to include your own assembly scenario, you need to create a function that takes as its arguments:

And optionally, if doing a trait-based model

Any additional scenario-specific arguments (e.g., my_param1 and my_param2 in the example below) can be passed to the function through the ... argument in assemble_communities. Importantly, if the scenario includes a trait matrix P, then this custom assembly function must also initialize the P matrix for the first species.

The function must then return a list of A and P, with P=NULL if no traits are included. The general outline of this function typically would follow something like this, though there is no reason why it cannot include more creative scenarios (e.g., complex trait evolution models):

 custom_assembly_scenario<-function(x,r,A,P=NULL,my_param1,my_param2,...){
 
       [code for initializing the P matrix for the first species (if using a trait model)]
       [code for generating a new set of interaction coefficients OR a new set of trait values]
       [code for translating trait values into interaction coefficients (if using a trait model)]
       [code for testing the desired invasion criterion]
       [repeat until a successful invader is found]
       
       return(list(A=newA, P=newP))
 
 }

This function can then be directly called in the assemble_community function:

outcom<-assemble_community(50,scenario="custom_assembly_scenario",my_param1=0.5, my_param2=6)

For a custom non-traits scenario, the assembly function will generally need to include a subroutine for generating new interaction coefficients, e.g., by selecting these at random from some distribution, or by permuting an existing species’ values in some way (see notraits_immigration_search and notraits_radiation_search for examples). In a traits scenario, the assembly function typically has two subroutines: (1) a function to generate new traits (see new_binary and new_continuous for examples), and (2) a distance function that translates this new trait vector into a vector of interaction coefficients (see get_A_from_P_binary and get_A_from_P_continuous for examples).

As noted, the growth rates and intraspecific effects are, by default, set equal to 1 and -1, respectively. This assumption certainly can be modified in a custom function, but doing so will require some revising of the other functions so as to deal with more flexible scenarios.

If you have any questions or if you find a bug in the code, please email Dan Maynard: dmaynard at uchicago.edu; or Stefano Allesina: sallesina at uchicago.edu