simmiad: Simulate replicate populations

In ellisztamas/simmiad: Simulations of Emmer wheat at the Ammiad kibbutz

Simulate replicate populations

Description

simmiad Simulates multiple replicate populations under a set of input parameters, and outputs a summary of the clustering among genotypes.

Usage

simmiad(
  mean_dispersal_distance,
  outcrossing_rate,
  n_generations,
  n_starting_genotypes = 50,
  density = 3,
  n_sample_points = 30,
  sample_spacing = 5,
  range_limit = 1.5,
  nsims,
  progress = TRUE,
  dormancy,
  years_to_sample = 1:n_generations,
  pop_structure = "uniform",
  mixing = mean_dispersal_distance,
  habitat_labels = NULL,
  var_w = 0
)

Arguments

mean_dispersal_distance	Float >0. Mean seed dispersal distance. The reciprocal of this is used as the rate parameter to draw from the exponential distribution.
outcrossing_rate	Float between 0 and 1. Probability that an individual is outcrossed.
n_generations	Int >12. Number of generations to run the simulations.
n_starting_genotypes	Int >0. Number of initial genotypes to start with. Defaults to 50
density	Float >0. Average density of plants per square metre.
n_sample_points	Number of points to sample along the transect.
sample_spacing	Distance between sampling points.
range_limit	Float >1 defining how much wider than the transect the width of the habitat should be. This, along with plant density, determines how many plants will be simulated. Defaults to 1.5. Ignored if pop_structure="hardcoded"
nsims	Int >0. Number of replicate populations to simulate.
progress	If TRUE, a progress bar is printed.
dormancy	Float between 0 and 1. Probability that a seedling is drawn from the seed bank. Seedlings are drawn from the prior generation with probability 1-dormancy.
years_to_sample	Vector of integers indexing which generations to sample the transect to calculate spatial structure and temporal stability. Defaults to the last 36 generations of the simulation
pop_structure	Character string indicating the initial population structure to be simulated. Passing "uniform" simulated a panmictic population. 'clusters' simulates clusters of identical individuals that disperse from distinct mothers via exponential dispersal set by mean_dispersal_distance. This is likely to generate very disperate clumps. Passing "mvnorm" simulates uniformly distributed coordinates for indiduals, as well as centroid positions for genotypes. Individuals are assigned a genotype in proportion to their distance to each genotype centroid based on multivariate-normal probabilities. The variance covariance matrix for this is set as sqrt(habitat_size/n_starting_genotypes) / 3 such that the tail of each genotype just about touches those of its neighbours, on average. If pop_structure='hardcoded' and a vector of genotypes is passed to n_starting_genotypes, for example observed genotypes from along all real-world transects, this simulates bands of identical genotypes by copying the vector over an evenly- spaced grid (giving horizontal but not vertical structure). There is one round of dispersal from this initial generation via exponential dispersal (controlled by mixing) and to get the population to the correct population density.
mixing	Float >0. Parameter controlling the degree of spatial clustering of genotypes. Smaller values indicate more structure populations. If pop_structure='mvnorm' this is a scaler multiplier for the variance of the multivariate normal probability density. If pop_structure="clusters" or pop_structure='hardcoded' this is the reciprocal of the rate parameter to draw dispersal distances from the exponential distribution. #' @habitat_labels Optional vector of habitat labels when ⁠pop_structure = 'hard-coded⁠, with an element for each sample given in n_starting_genotypes.
var_w	Additive variance for (log) fitness. Defaults to zero (no selection).

Details

simmiad is a wrapper function to call multiple instances of sim_population, estimate the degree of clustering in each, and save results to disk. See the help file ?sim_population for details of individual population simulations.

For each simulation, simmiad draws a horizontal transect at each generation across the whole time series. For a subset of those generations it calculates three kinds of summary information about this transect to disk for a subset. First it estimates the degree of clustering estimated using transect_cluster, and averages over points between years. This summarises the number and mean distance between pairs of identical genotypes and between pairs of non-identical genotypes. Second, it estimates the temporal stability of the populations by calculating how often a sampling point is occupied by identical genotypes at different at the start of the samplinh period, and at subsequent time points. Third, it calculates the probability that adjacent sampling points only are occupied by identical genotypes for each year separately.

Selection can be simulated by modelling fitness as log-normally distributed. Genotypes are automatically assigned a log fitness values drawn from a normal distribution with mean zero and variance var_w. Following Morrisey and Bonnet (2019; J. Heredity 110:396–402) absolute fitness is then the exponent of these values, which is then divided by the mean to get relative fitness. Seeds ar drawn in proportion to relative fitness.

Value

A list of seven dataframes.

1. parameters A data.frame giving input parameters.

2. clustering The covariance between distance along the transect and the frequency of identical genotypes.

3. matching_pairs: The number of pairs of identical genotypes in the transect.

4. count_NA: The number of empty sampling points.

5. n_genotypes: The number of unique genotypes sampled in the transect (note that this will be different from what you gave as distance_identity, because the latter reflects genotypes in the whole population, not just in the transect).

6. stability: How often individual sampling points are occupied by the same genotype in the final generations and 1, 2, ..., n generations back.

7. distance_identity: Probabilities of finding identical genotypes in pairs of sampling points at all possible distances between transects. For example, if there are five evenly spaced sampling points as in the example above, there are four possible distances between sampling points. Rows indicate replicate simulations.

8. di_by_year The probability of finding identical genotypes in pairs of sampling points across generations. Only values for adjacent sampling points are shown.

For 2-6 and 8, rows indicate replicate simulations and columns generations.

Author(s)

Tom Ellis

See Also

sim_population, transect_cluster, transect_stability

ellisztamas/simmiad documentation built on Dec. 12, 2023, 5:32 a.m.