sim.metapopgen.monoecious.multilocus: Simulate metapopulation genetics (multiple loci)

In MarcoAndrello/MetaPopGen-2.0: Simulation of metapopulation genetics

Description

Simulates the metapopulation genetics.

Usage

sim.metapopgen.monoecious.multilocus(init.par,
                                    sigma,
                                    phi_F, phi_M,
                                    fec.distr_F = "poisson", fec.distr_M = "poisson",
                                    migration = "forward",
                                    delta.prop, delta.ad, migr,
                                    recr.dd = "settlers", kappa0,
                                    T_max,
                                    save.res = FALSE, save.res.T = seq(1:T_max),
                                    output.var = "N",
                                    verbose = FALSE)
                                    
sim.metapopgen.dioecious.multilocus(init.par,
                                    sigma_F, sigma_M,
                                    phi_F, phi_M,,
                                    fec.distr_F = "poisson", fec.distr_M = "poisson",
                                    delta.prop, delta.ad,
                                    recr.dd = "settlers", kappa0,
                                    T_max,
                                    save.res = FALSE, save.res.T = seq(1:T_max),
                                    output.var = "N",
                                    verbose = FALSE)

Arguments

init.par	A list of arguments necessary to initialize the simulations and obtained with the function initialize.multilocus. See the example.
sigma, sigma_F, sigma_M	Survival probabilities. 4-D array of length c(m,n,z,T_max). sigma[j,i,x,t] is the survival probability for individuals of genotype j, age x in deme i at time t. Alternatively, sigma can be a 3-D array of length c(m,n,z): this will be interpreted as survival probabilities constant in time. All the elements of sigma are bounded between [0,1].
phi_F, phi_M	Mean female and male fecundity. 4-D array of length c(m,n,z,T_max). phi_F[j,i,x,t] is the female fecundity for individuals of genotype j, age x in deme i at time t. Alternatively, phi_F and phi_M can be a 3-D array of length c(m,n,z): this will be interpreted as female or male fecundities constant in time. Female fecundity is the per capita number of female gametes (eggs for animals, embrio sacs for plants). Male fecundity is the per capita number of male gametes (sperms for animals, pollen grains for plants). All the elements of phi_F and phi_M must be positive integers.
fec.distr_F, fec.distr_M	The distribution used to set fecundities: one of "fixed" or "poisson" (default). The "fixed" option sets the fecundity of each individual equal to the mean (phi_F and phi_M). Option "poisson" draws individual fecundities form a Poisson distribution with means phi_F and phi_M.
migration	The type of propagule migration used, "forward" (the default) or "backward". With forward migration, dispersal of propagules is modelled using the delta.prop argument (see below), while argument migr is disregarded. With backward migration, migration is modelled using argument migr as in a finite island model (Latter, 1973). In this model, the gene pool of the jth deme contains a proportion 1-migr of gametes derived at random from adults resident in the jth deme in the previous generation, and a proportion migr/(n-1) of gametes derived at random from adults resident in each of the remaining n-1 demes. Variables L and S are not calculated with backward migration (see argument output.var), because the number of individuals recruiting the deme is calculated directly from the gamete frequencies of the previous generations. Arguments phi_F, phi_M, fec_distr_F, fec_distr_M and delta.prop are disregarded. Backward migration is currently limited to only one age class and monoecious life cycles. migration does not affect adult dispersal.
migr	Migration rate used when migration = "backward".
delta.prop	Dispersal probabilities for propagules. Square matrix of size n*n. delta.prop[i,j] is the dispersal probability from deme j to deme i (see also Details). Alternatively, delta.prop can be a 3-D array of length c(n,n,T_max): this will be interpreted as dispersal varying in time.
delta.ad	Dispersal probabilities for adults. Square matrix of size n*n. delta.ad[i,j] is the dispersal probability from deme j to deme i (see also Details). Alternatively, delta.ad can be a 3-D array of length c(n,n,z): this will be interpreted as dispersal varying with age; or delta.ad can be a 4-D array of length c(n,n,z,T_max), which will be interpreted as dispersal varying with age and in time. To set dispersal probabilities constant with age and varying in time, use the 4-D format.
recr.dd	Defines how population regulation is performed. Currently inactive.
kappa0	2-D array of length c(n,T_max). Deme carrying capacity used to perform population regulation. kappa0 can also be a 1-D array of length n: this will be interpreted as a carrying capacity constant in time.
T_max	Number of years of simulations.
save.res	Boolean. If FALSE (default), the result of the simulation is stored in memory and returned to the user. If TRUE, the function does not return anything, but save the result in different files on disk. See "value" below.
save.res.T	Vector. If save.res=TRUE, this argument is used to define the time steps for which the state of the metapopulation will be saved on disk. It is used to save disk space in the case of long simulations with many demes or genotypes. It deafults to seq(1,T_max), that is, the results are saved every time step.
output.var	A vector containing the names of the variables output by the simulation: "N", "Nprime", "Nprimeprime", "L" and "S". For example, to output genotype numbers in adults and propagules, set output.var = c("N","L"). Default to "N". This argument is set in the same way for the monoecious and the dioecious functions. However, the dioecious function returns two variables corresponding to female and male numbers. For example, setting output.var = c("N","L") in sim.metapopgen.dioecious.multilocus will return four variables giving genotype numbers in adult females, adult males, propagule females and propagule males.
verbose	If TRUE, the function will print additional information, mainly used for debugging purposes. Default to FALSE.

Details

Element i,j of propagule and adult dispersal matrices always indicates dispersal from deme j to deme i. Note that this may be not equal to the dispersal probability from deme i to deme j. As a consequence, the sum of the elements of each column is bounded to one, while the sum of the elements of rows is unbounded.

Value

• If save.res = FALSE:
  
  a named list where each element is one of the tracked variables (see argument output.var). Each of these elements is an array giving the number of individuals of each genotype and deme. Specifically,

  N (monoecious life-cycle) or N_F and N_M (dioecious life-cycle)

  a 4-D array (ex: N[k,i,x,t]) of length c(m,n,z,T_max) giving the number of individuals of genotype k, age x in deme i at time t. This is the number of individuals at the beginning of the life cycle, just after recruitment and before adult survival.

  Nprime (monoecious life-cycle) or Nprime_F and Nprime_M (dioecious life-cycle)

  a 4-D array (ex: Nprime[k,i,x,t]) of length c(m,n,z,T_max) giving the number of individuals of genotype k, age x in deme i at time t after adult survival and before adult dispersal.

  Nprimeprime (monoecious life-cycle) or Nprimeprime_F and Nprimeprime_M (dioecious life-cycle)

  a 4-D array (ex: Nprimeprime[k,i,x,t]) of length c(m,n,z,T_max) giving the number of individuals of genotype k, age x in deme i at time t after adult dispersal.

  L (monoecious life-cycle) or L_F and L_M (dioecious life-cycle)

  a 3-D array (ex: L[k,i,t]) of length c(m,n,T_max) giving the number of propagules of genotype k, in deme i at time t before propagule dispersal.

  S (monoecious life-cycle) or S_F and S_M (dioecious life-cycle)

  a 3-D array (ex: S[k,i,t]) of length c(m,n,T_max) giving the number of propagules of genotype k, in deme i at time t after propagule dispersal.

• If save.res = TRUE:
  
  the function does not return anything. Results are saved in files on disk. The function will create a folder named with the date and time of your simulation and create one RData file per year of simulation (but see argument save.res.T for defining the time steps for which the results are saved) and per chosen output variables (N, Nprime, Nprimeprime, L and S). The files will be named with the name of the output variable and the time step of simulation, e.g. N1.RData, S1.RData, etc.
  
  The variables contained in each file are as described above for the case (save.res = FALSE), but they do not have the time dimension. Specifically, N, Nprime and Nprimeprime have length c(m,n,z), and L and S have length c(m,n).
  
  For the dioecious life-cycle, each file contains two variables giving the genotype numbers for females and males for the specific output variable and time step.

Author(s)

Christelle Noirot
Marco Andrello

See Also

initialize.multilocus create.dispersal.coord create.dispersal.IM

Examples

## Not run: 
data("MultilocusMonoecious")
res <- sim.metapopgen.monoecious.multilocus(init.par = init.par,
                                            sigma = sigma,
                                            phi_F = phi_F, phi_M = phi_M,
                                            delta.prop = delta.prop, delta.ad = delta.ad,
                                            T_max = T_max)
                                            
data("MultilocusDioecious")
res <- sim.metapopgen.dioecious.multilocus(init.par = init.par,
                                            sigma_F = sigma_F, sigma_M = sigma_M,
                                            phi_F = phi_F, phi_M = phi_M,
                                            delta.prop = delta.prop, delta.ad = delta.ad,
                                            T_max = T_max)


## End(Not run)

MarcoAndrello/MetaPopGen-2.0 documentation built on Nov. 25, 2020, 11:20 p.m.