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

View source: R/mcfly_function.R

mcflyR Documentation

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 Aug. 9, 2022, 6:55 p.m.