Simulate a geneology with varying population size.

This function simulates a geneology with varying population size specified by a vector of population sizes, one for each generation.

sample_mtdna_geneology_varying_size(population_sizes_females,
  population_sizes_males, generations_full = 1L,
  generations_return = 3L, enable_gamma_variance_extension = FALSE,
  gamma_parameter_shape = 5, gamma_parameter_scale = 1/5,
  progress = TRUE)

Arguments

population_sizes_females

The size of the female population at each generation, g. All >= 1. population_sizes_females[g] is the population size at generation g. The length of population_sizes_females is the number of generations being simulated.
population_sizes_males

The size of the male population at each generation, g. All >= 0. population_sizes_males[g] is the population size at generation g.
generations_full

Number of full generations to be simulated.
generations_return

How many generations to return (pointers to) individuals for.
enable_gamma_variance_extension

Enable symmetric Dirichlet (and disable standard Wright-Fisher).
gamma_parameter_shape

Parameter related to symmetric Dirichlet distribution for each man's probability to be mother. Refer to details.
gamma_parameter_scale

Parameter realted to symmetric Dirichlet distribution for each man's probability to be mother. Refer to details.
progress

Show progress.

Value

A mitolina_simulation / list with the following entries:

  • population. An external pointer to the population.

  • generations. Generations actually simulated, mostly useful when parameter generations = -1.

  • founders. Number of founders after the simulated generations.

  • growth_type. Growth type model.

  • sdo_type. Standard deviation in a man's number of male offspring. StandardWF or GammaVariation depending on enable_gamma_variance_extension.

  • end_generation_female_individuals. Pointers to female individuals in end generation.

  • female_individuals_generations. Pointers to female individuals in last generations_return generation (if generations_return = 3, then female individuals in the last three generations are returned).

  • end_generation_male_individuals. Pointers to male individuals in end generation.

  • male_individuals_generations. Pointers to male individuals in last generations_return generation (if generations_return = 3, then male individuals in the last three generations are returned).

Details

By the backwards simulating process of the Wright-Fisher model, individuals with no descendants in the end population are not simulated If for some reason additional full generations should be simulated, the number can be specified via the generations_full parameter. This can for example be useful if one wants to simulate the final 3 generations although some of these may not get (male) children.

Let \(\alpha\) be the parameter of a symmetric Dirichlet distribution specifying each man's probability to be the mother of an arbitrary male in the next generation. When \(\alpha = 5\), a man's relative probability to be the mother has 95% probability to lie between 0.32 and 2.05, compared with a constant 1 under the standard Wright-Fisher model and the standard deviation in the number of male offspring per man is 1.10 (standard Wright-Fisher = 1).

This symmetric Dirichlet distribution is implemented by drawing mother (unscaled) probabilities from a Gamma distribution with parameters gamma_parameter_shape and gamma_parameter_scale that are then normalised to sum to 1. To obtain a symmetric Dirichlet distribution with parameter \(\alpha\), the following must be used: \(`gamma_parameter_shape` = \alpha\) and \(`gamma_parameter_scale` = 1/\alpha\).