mcfly: Title Simulation framework to estimate the influence of niche...

In GabrielNakamura/mcfly: Simulation framework to estimate the influence of niche adaptation rate and dispersal limitation on species diversity distribution across environmental gradients

Title Simulation framework to estimate the influence of niche adaptation rate and dispersal limitation on species diversity distribution across environmental gradients.

Description

We introduce mcfly, an R package to estimate the influence of niche adaptation rate and dispersal limitation on species diversity distribution of a given phylogenetic lineage across environmental gradients. For this, mcfly adopts the individual-based metacommunity simulation framework algorithm implemented in the package MCSim (See MCSim package for more information on individual based model) coupled to Approximate Bayesian Computation (ABC) to estimate the posterior distribution of (i) the adaptation rate parameter of Ornstein-Uhlenbeck (OU) evolutionary model and (ii) the slope the dispersal kernel, i.e, the probability density function of the dispersal success from a source to a sink assemblage)that maximizes the association between species diversity across a set of sites and a given environmental gradient.

Usage

mcfly(
  comm,
  phylo,
  envir,
  xy.coords,
  occurrence = TRUE,
  entropy.order = 1,
  niche.breadth = 10,
  m = 0.5,
  n.timestep = 50,
  OU.alpha = c("uniform", "half-life"),
  W.r.prior = FALSE,
  tol = 0.2,
  sample.size.posterior = 240,
  max.sample.size.prior = 2400,
  HPD = 0.9,
  return.comm = FALSE,
  plot.res = FALSE,
  parallel = NULL,
  scenario.ID = "mcfly",
  output.dir.path = "delorean"
)

Arguments

comm	Matrix containing occurrences or abundances of species in sites. Species in columns and sites in rows.
phylo	Newick object containing the phylogenetic relationship among species.
envir	A one column matrix containing environmental variable for each community
xy.coords	A two column matrix containing the coordinates of each community
occurrence	Logical argument (TRUE or FALSE) indicating if community matrix must be transformed to presence/absence
entropy.order	Numeric value indicating the scale of Rényi diversity, as accepted by renyi. Default is 1
niche.breadth	Numeric value indicating the width of niche of species in the metacommunity, as accepted by metasim. Default is 10
m	Numeric value indicating the immigration rate at each site, reported as Hubbel´s m. This is the same parameter accepted by metasim.
n.timestep	Numeric value indicating the number of timesteps used in the simulation of metacommunities, this is the same argument used in metasim. Default is 50, it is not recommended the use of lower values.
OU.alpha	Character indicating the type of prior that will be used in ABC model. The options were "uniform" for a uniform sample of alpha values and "half-life" for a prior of alpha values represented as being half-life values, calculated as being log().
W.r.prior	Logical (TRUE or FALSE) indicating if the the W.r parameter would be a single value (FALSE) with value of 0, indicating a panmictic metacommunity or follow a prior distribution (TRUE) of values calculated as being the slopes of dispersal kernel indicating the contribution of species from neighboring patches to the local immigrant pool.
tol	Numeric value that defines the tolerance value (calculated as 1 - correlation) used in ABC model to assemble the posterior distribution. Default is 0.2.
sample.size.posterior	Numeric value that defines the minimum size of the posterior distribution. Default is 240.
max.sample.size.prior	Numeric value that defines the maximum size of the posterior distribution. Default is 2400.
HPD	Numeric value indicating the probability mass for the Highest Density Interval for the posterior probability distribution obtained in ACB model. This is the same value used in hdi. Default is 0.9.
return.comm	Logical (TRUE/FALSE), indicating if the simulated metacommunities must be returned in the output. Default is FALSE.
plot.res	Logical, indicates if a plot with posterior and prior distribution, as well as the HPD must be showed. Default is FALSE
parallel	Numerical value indicating the numbers of cores that must be used in the parallel computation. Default is NULL, indicating that the calculations of ABC model will not be parallelized.
scenario.ID	Character indicating the name of the simulation scenario. The same as used in metasim. Default is "mcfly".
output.dir.path	Character indicating the name of directory to save simulations results and metadata used in metasim. Default is "delorean".

Details

This function estimate the influence of niche selection on species diversity across environmental gradients by applying to a occurrence matrix of species containing presence/absence or abundance an Approximate Bayesian Computation (ABC) framework. We used in ABC a individual based-model from MCSim package

Value

A list containing the following objects:

Time.spent	The amout of time spent to run the analysis.
Simulated.Metacomm	Simulated community matrix.
Data.Attributes	A matrix containing the number of species in the phylogeny, the number of species in the metacommunity, number of sites in the metacommunity, maximmun distance between two species in the phylogenetic tree, tree depth
Sample.Attributes	A matrix containing information of posterior distribution as the maximum size of the posterior, total sample sample size of prior, the type of posterior (if alpha or half-life) and total size of posterior
Alpha.Limits	A matrix containing the minimum and maximum alfa parameters in the posterior distribution
Alpha.prior.mode	A character indicating the type of prior used in ABC (alpha or half-life)
Alpha.prior.mode	A character indicating the type of prior used in ABC (alpha or half-life)
Alpha_Prior_Distribution	Numeric vector with alpha values used as the prior distribution
W.Prior.Distribution	Numeric vector with w values used as the prior distribution
Theta	Numeric values indicating theta parameters in the simulation
K.niche	Numeric vector with Blomberg's K statistic of phylogenetic signal calculated for simulated traits
Distance.measure	Numeric vector with correlations between observed and simulated diversity metrics
Alpha.Posterior.Distribution	Numeric vector containing alpha values estimated from ABC model (posterior distribution)
HPD.Alpha	Numeric vector indicating the range of alpha posterior distribution corresponding to the High Posterior Density in a probability density distribution
W.Posterior.Distribution	Numeric vector containing the w values estimated from ABC model (posterior distribution)
HPD.w	Numeric vector indicating the range of w posterior distribution corresponding to the High Posterior Density in a probability density distribution
Coordinates	A matrix with x and y coordinates of sites in a metacommunity
Observed.Entropy	A vector containing the observed values of diversity for each site in the metacommunity
Mean.Simulated.Entropy	A vector containing mean values of diversity for each site computed from simulated metacommunities

GabrielNakamura/mcfly documentation built on July 27, 2023, 12:45 p.m.