Skip to content

DAISIErobustness R package

Pedro Neves edited this page Mar 13, 2022 · 16 revisions

Project Status: Active – The project has reached a stable, usable state and is being actively developed. GitHub R package version DOI

Branch GitHub Actions logo Codecov logo
master R build status codecov.io
develop R build status codecov.io

DAISIErobustness Conducts a robustness test of the island biogeography DAISIE model to the effects of geodynamics or trait dependency. Tests processes such as island ontogeny, sea-level change and land-bridge dynamics. Contains acessory code for easy use with the University of Groningen Peregrine HPCC.

Installing the R package

DAISIErobustness and all the packages it depends on can be easily installed from GitHub by making use of the remotes package which is itself available on CRAN. To install the most up-to-date stable state of DAISIErobustness run the following code in your R console:

if (isFALSE("remotes" %in% rownames(installed.packages()))) {
  install.packages("remotes")
}
remotes::install_github("Neves-P/DAISIErobustness")

Should you want to install a specific version, the releases and their patch notes can be accessed from GitHub and are similarly archived on zenodo. Additionally, each version can be installed directly from GitHub R by appending a version tag: remotes::install_github("Neves-P/[email protected]"). This may be useful if you are trying to replicate one of the published studies to ensure you are running package versions that match those used for the publications. See here for more details on versions and software.

Running the DAISIErobustness pipeline

The DAISIErobustness pipeline can be run by calling the main function run_robustness(). To do so, a number of options must be chosen and passed on as arguments. Firstly, one must decide which of the several novel models which fall into two broad categories: geodynamics1 or traits2.

Category Model code
Traits trait_CES
Geodynamics continental_cs
Geodynamics continental_iw
Geodynamics continental_di
Geodynamics continental_land_bridge_cs
Geodynamics continental_land_bridge_iw
Geodynamics continental_land_bridge_di
Geodynamics oceanic_sea_level_cs
Geodynamics oceanic_sea_level_iw
Geodynamics oceanic_sea_level_di
Geodynamics oceanic_ontogeny_cs
Geodynamics oceanic_ontogeny_iw
Geodynamics oceanic_ontogeny_di
Geodynamics oceanic_ontogeny_sea_level_cs
Geodynamics oceanic_ontogeny_sea_level_iw
Geodynamics oceanic_ontogeny_sea_level_di

The codes in mono-spaced font are the available options for the param_space_name argument of the run_robustness() function. Each of these refers to a specific parameter space. While it is not necessary, a user can inspect these parameter spaces since they are available as non-exported data objects (of type data.frame) inside DAISIErobustness, and can be accessed thusly:

oceanic_ontogeny_cs_param_space <- DAISIErobustness::load_param_space(
  param_space_name = "oceanic_ontogeny_cs"
)
View(oceanic_ontogeny_cs_param_space)

Each parameter space is made up of a collection of parameter sets, each of which corresponds to a line in its data frame. Alternatively to looking up the corresponding paramter set on the data frame, each individual parameter set can be obtained as a named list:

oceanic_ontogeny_cs_param_space <- DAISIErobustness::load_param_space(
  param_space_name = "oceanic_ontogeny_cs"
)
oceanic_ontogeny_cs_param_set_1 <- DAISIErobustness::extract_param_set(
  param_space_name = "oceanic_ontogeny_cs"
  param_space = oceanic_ontogeny_cs_param_space,
  param_set = 1
)

The suffixes *_cs, *_iw, and *_di refer indicate if a given parameter space implements Clade-Specific (cs), or Island-Wide (iw) diversity dependence, or assumes Diversity Independence (di). Please refer to the DAISIE package documentation or to the accompanying publication1 for a longer explanation of these concepts.

Example run

run_robustness(
  param_space_name = "continental_cs",
  param_set = 1,
  replicates = 2,
  save_output = TRUE
)

This code will run the pipeline for the first parameter set in the continental clade-specific parameter space. When save_output = TRUE, all the objects generated by the pipeline will be stored in the the session's working directory, into /results/param_space_name/, param_space_name corresponding to the parameter space chosen when the function is called. These directories will be created if not present and if write permissions allow. If save_output = FALSE, then the objects will be returned by the function, allowing them to be saved to an R object and handled in an interactive session.

Error metrics

The following results are used to determine the error between models:

  • The nLTT1 statistic for endemic species, non-endemic species and all species.
  • The difference at the end of the simulation of the number of species, endemic and nonendemic species.

These metrics are then aggregated between all replicates of a given parameter space in the following way:

  • Mean and standard deviation in the difference of all nLTTs
  • Mean and standard deviation of number of species, endemics and nonendemics

Paper Figures

The code used to generate the figures found in the REFREFREF paper can be found in the ´/scripts/plots/´ directory. Functions that generate the figures are found within the /functions/ sub-directory, while the scripts that load, plot and save the files are found in the root of the /plots/ directory. How to load files, and download files.

References

1Janzen, Thijs, Sebastian Höhna, and Rampal S. Etienne. "Approximate Bayesian Computation of diversification rates from molecular phylogenies: introducing a new efficient summary statistic, the nLTT." Methods in Ecology and Evolution 6.5 (2015): 566-575.