forward: Simulation of neutral and niche-based community dynamics...
In ecolottery: Coalescent-Based Simulation of Ecological Communities

Description Usage Arguments Details Value Author(s) References Examples

Simulates niche-based (habitat filtering and/or limiting similarity) and neutral community dynamics from a given initial composition, over a given number of generations.

forward(initial, prob = 0, d = 1, gens = 150, keep = FALSE,
        pool = NULL, limit.sim = FALSE, coeff.lim.sim = 1,
        sigm = 0.1, filt = NULL, prob.death = NULL,
        method.dist = "euclidean", plot_gens = FALSE)
get_number_of_gens(given_size, pool, nbrep = 5, prob = 1, d = 1, 
                   gens = NULL, limit.sim = FALSE, 
                   coeff.lim.sim = 1, sigm = 0.1, filt = NULL, 
                   prob.death = NULL, method.dist = "euclidean",
                   plot_gens = FALSE)
pick(com, d = 1, prob = 0, pool = NULL, prob.death = prob.death,
     limit.sim = NULL, coeff.lim.sim = 1, sigm = 0.1, filt = NULL, 
     new.index = new.index, method.dist = "euclidean")
pick.mutate(com, d = 1, prob.of.mutate = 0, new.index = 0)
pick.immigrate(com, d = 1, prob.of.immigrate = 0, pool, 
               prob.death = NULL, limit.sim = NULL, coeff.lim.sim = 1,
               sigm = 0.1, filt = NULL, method.dist = "euclidean")

`com, initial`	starting community. It is in principle a three (or more) column matrix or data.frame including individual ID, species names and trait values. For strictly neutral dynamics, it can be a vector of individual species names.
`prob, prob.of.immigrate, prob.of.mutate`	probability of an individual establishing in the community not being a descendant of an existing individual. If descendant from a new ancestor, can be either through immigration (in `pick.immigrate()`) or through mutation (in `pick.mutate()`).
`d`	number of individuals that die in each time-step.
`gens`	number of generations to simulate.
`keep`	boolean value. If `FALSE` (default) the function output only the community composition at the end of the simulation. If `TRUE` the function output a list of community composition at successive time steps (see Value section).
`pool`	the regional pool of species providing immigrants to the local community. It is in principle a three-column matrix or data frame including individual ID, species names and trait values. If trait information is missing, a random trait value is given to individuals, from a uniform distribution between 0 and 1. If `NULL`, the pool is simulated as a metacommunity at speciation-drift equilibrium, based on `prob` for speciation rate.
`given_size`	size of the community you want to have an estimate of the number of generations needed to reach stationarity in species richness.
`nbrep`	number of replicates from which you want to estimate the number of generations needed to reach stationarity in species richness.
`limit.sim`	if `TRUE,` limiting similarity will be simulated, based on species trait distances (computed with the method given by `method.dist`) and a Gaussian overlapping function.
`coeff.lim.sim`	adjust the intensity of limiting similarity.
`sigm`	adjust the variance of the overlap function used to calculate limiting similarity.
`filt`	the function used to represent habitat filtering. For a given trait value `t`, `filt(t)` represents the probability that an individual with trait `t` enters the local community.
`prob.death`	provides a baseline probability of death that is homogeneous across species. It is used in niche-based dynamics to represent the balance of baseline and niche-dependent mortality.
`method.dist`	provide the method to compute trait distances between individuals (syntax of function `dist`, can be in the list `c("euclidean", "maximum", "manhattan", "canberra", "binary", "minkowski")`).
`new.index`	prefix used to give a new species name when speciation occurs.
`plot_gens`	plot the number of unique individuals and species over generations.

It is a zero-sum game, so that the number of individuals of the community is fixed to the number of individuals in initial community.

When niche-based dynamics are simulated, the niche-based constraints influence both immigration and mortality.

Function get_number_of_gen() allows determining the number of generations needed to reach stationary richness for given parameterization of forward(). The target number of generation is based on assessing the change point in species richness change over time for replicate simulated communities with random initial composition. A conservative measure is proposed as the maximum time to reach stationary richness over the replicate simulated communities.

Functions pick.immigrate() and pick.mutate() are used to simulate immigration and speciation events within a time step. They are embedded in forward and are not really intended for the end user.

`com`	if `keep = FALSE`, a data.frame of simulated individuals, with the label of ancestor individual in the regional pool on first column (as in the first column of the pool), species label on second column (as in the second column of the pool), and species trait (as in the third column of the pool).
`pool`	a data.frame of the individuals of the regional source pool, with the label of ancestor individual in the regional pool on first column (as in first column of input `pool`), species label on second column (as in second column of input `pool`), and species trait (as in third column of input `pool`).
`sp_t`	a vector of species richness at each time step.
`com_t`	if `keep = TRUE`, a list of community composition for each time step (a data.frame as in `com`).
`dist.t`	if `limit.sim = TRUE`, the average value of the limiting similarity function over time.
`new.index`	for `pick.mutate()`, return the new index to be used for species name at a next speciation event.

F. Munoz, derived from the untb function of R. Hankin.

For neutral dynamics, S. P. Hubbell 2001. "The Unified Neutral Theory of Biodiversity". Princeton University Press.

## Not run: 
# Initial community composed of 10 species each including 10 individuals
initial1 <- rep(as.character(1:10), each = 10)

# Simulation of speciation and drift dynamics over 100 time steps
final1 <- forward(initial = initial1, prob = 0.1, gens = 1000)
# The final community includes new species (by default names begins with "new")
final1$com$sp # includes new species generated by speciation events

# A regional pool including 100 species each including 10 individuals
pool <- rep(as.character(1:100), each = 10)

# Simulation of migration and drift dynamics over 1000 time steps
final2 <- forward(initial = initial1, prob = 0.1, gens = 1000, pool = pool)
# The final community includes species that have immigrated from the pool
final2$com$sp # includes new species that immigrated from the pool

# Initial community composed of 10 species each including 10 individuals, 
# with trait information for niche-based dynamics
initial2 <- data.frame(sp = rep(as.character(1:10), each = 10), 
                      trait = runif(100))

# Simulation of stabilizing hab. filtering around t = 0.5, over 1000 time steps
sigm <- 0.1
filt_gaussian <- function(t,x) exp(-(x - t)^2/(2*sigm^2))
final3 <- forward(initial = initial2, prob = 0.1, gens = 1000, pool = pool, 
                 filt = function(x) filt_gaussian(0.5,x))
plot_comm(final3) # trait distribution in final community

# With higher immigration
final4 <- forward(initial = initial2, prob = 0.8, gens = 1000, pool = pool, 
                 filt = function(x) filt_gaussian(0.5,x))
plot_comm(final4) # should be closer to 0.5

# Simulation of limiting similarity, over 1000 time steps
final5 <- forward(initial = initial2, prob = 0.1, gens = 1000, pool = pool, 
                 limit.sim = TRUE)
plot_comm(final5)

# Stronger limiting similarity
final6 <- forward(initial = initial2, prob = 0.1, gens = 1000, pool = pool, 
                 limit.sim = TRUE, coeff.lim.sim = 20)
plot_comm(final6) # the distribution will be more even

# Variation of community richness with time
final7 <- forward(initial = initial2, prob = 0.1, gens = 1000, pool = pool, 
                 limit.sim = TRUE, keep = TRUE, plot_gens = TRUE)

# Check stationarity
plot(unlist(lapply(final7$com_t, function(x) length(unique(x[, 2])))), 
     xlab = "Time step", ylab = "Community richness") 

# Index of limiting similarity over time
plot(final7$dist.t, xlab = "Time step", ylab = "Limiting similarity")

## End(Not run)