simulate_policy {simRestore}

Simulate the effect of a restoration policy over time.

Description

Using this function, the user can simulate the effect of an intended management policy on the genetic composition of a focal population. The population is assumed to have overlapping generations, and the user can specify two genetic models, either using a simplified average ancestry representation (genetic_model = "point"), or a more detailed model tracking explicit recombination among chromosomes, using genetic_model = "junctions".

Usage

simulate_policy(
  initial_population_size = 400,
  reproduction_success_rate = 0.387,
  reproductive_risk = c(0.2, 0),
  K = 400,
  num_generations = 20,
  pull = 0,
  put = 0,
  starting_freq = 0.5,
  sd_starting_freq = 0.05,
  morgan = c(1),
  max_age = 6,
  mean_number_of_offspring = 6,
  sd_number_of_offspring = 1,
  genetic_model = "point",
  establishment_burnin = 30,
  num_replicates = 1,
  seed = NULL,
  smin = 0.5,
  smax = 0.9,
  b = -2,
  p = 0.5,
  sex_ratio_put = 0.5,
  sex_ratio_pull = 0.5,
  sex_ratio_offspring = 0.5,
  ancestry_put = 1,
  ancestry_pull = 1,
  random_mating = FALSE,
  extra_pair_copulation = 0,
  verbose = FALSE,
  return_genetics = FALSE
)

Arguments

initial_population_size

population size at the start

reproduction_success_rate

frequency of females that yield offspring at the end of the breeding season (e.g. a fraction of 1 - reproduction_success_rate of females. This is a joint effect of breeding females getting killed (see female_death_rate) and other sources of failure to produce offspring. Other sources of failure are calculated from reproduction_success_rate and female_death_rate, such that the resulting reproduction failure rate = 1 - reproduction_success_rate / (1 - female breeding risk)

reproductive_risk

Additional death rate of males and females as a result of breeding (e.g. as a result of protecting the offspring against predators). Provide as a vector where the first index indicates the risk for females, the second the risk for males.

K

carrying capacity

num_generations

number of generations

pull

vector of the number of individuals pulled per year

put

vector of the number of individuals added per year

starting_freq

initial frequency of target ancestry in the population.

sd_starting_freq

variation in initial frequency of target ancestry.

morgan

a vector with the size of each chromosome in morgan, e.g. if a single chromosome is to be simulated a single number will suffice, but for two chromosomes of a size of 1 Morgan, a vector like: c(1, 1) will work.

max_age

maximum age an individual can reach.

mean_number_of_offspring

mean number of offspring per female

sd_number_of_offspring

standard deviation of number of offspring per female (assuming the number of offspring is always 0 or larger).

genetic_model

The model can either use the point ancestry model ("point") of underlying genetics, which speeds up simulation considerably, but underestimates genetic variation. Alternatively, a more detailed genetic model is available, making use of the theory of junctions, this can be accessed using the option "junctions". Default is "point".

establishment_burnin

number of generations before establishment

num_replicates

number of replicates

seed

random number seed, if left open, current time is used.

smin

minimum survival rate

smax

maximum survival rate

b

steepness of the survival rate. Negative values indicate a declining survival rate with increasing population size, positive values indicate an increasing survival rate with increasing population size.

p

Density at which the survival rate changes most relative. Expressed in N / K (e.g., for a value of 1.0, the survival rate changes most rapidly around N = K, for a value of 0.5, the survival rate changes most rapidly around N = 0.5K, etc).

sex_ratio_put

sex ratio of individuals that are added (if any) to the population. Sex ratio is expressed as males / (males + females), such that 0.5 indicates an even sex ratio, 0.9 indicates a male biased sex ratio and 0.1 indicates a female biased sex ratio.

sex_ratio_pull

sex ratio of individuals that are removed (if any) from the population. The sex ratio is expressed as males / (males + females), such that 0.5 indicates an even sex ratio, 0.9 indicates a male biased sex ratio and 0.1 indicates a female biased sex ratio.

sex_ratio_offspring

sex ratio of newly born offspring. The sex ratio is expressed as males / (males + females), such that 0.5 indicates an even sex ratio, 0.9 indicates a male biased sex ratio and 0.1 indicates a female biased sex ratio.

ancestry_put

Average ancestry of individuals being used for supplementation. If the target is high focal ancestry (e.g. aiming for focal ancestry of 1.0), ancestry put should reflect this and be set to 1.0 ( which is the default value). When supplementing with non-pure individuals, this value can consequently be lowered.

ancestry_pull

Ancestry level below which individuals are allowed to be pulled - this can reduce the effective number of individuals pulled if none of the individuals in the population match this ancestry level. This can be used to selectively only remove those with low target ancestry.

random_mating

by default, simulations assume fixed pair bonding, e.g. each female mates with exactly one male (if available). Alternatively, if random_mating = TRUE, females will mate with a random male, introducing the possibility that some males mate multiple times.

extra_pair_copulation

probability of offspring to be fathered by another male. We assume that all offspring from one mother can have at most two fathers.

verbose

provides verbose output if TRUE.

return_genetics

returns a tibble containing all local ancestry information for all individuals. This tibble contains the following informative columns: 1) time (the last generation), 2) replicate, 3) individual, 4) sex (0 = male, 1 = female), 5) Linkage Group (if use_simplified_model == FALSE), 6) chromosome (1 or 2, returning phased results), 7) position (if use_simplified_model == FALSE) and 8) local ancestry (0 or 1).

Value

tibble with 8 columns: 1) replicate, 2) time (in generations), 3) average frequency of ancestry across all individuals 4) average frequency of ancestry across all males, 5) average frequency of ancestry across all females, 6) number of individuals, 7) number of males and 8) number of females if return_genetics = TRUE, the output is a list containing the above mentioned tibble, called 'results', and a second tibble called 'genetics', with the local ancestry in long format, split out per generation, replicate, individual, sex, linkage group and chromosome (1 or 2). Here, linkage group indicates the focal chromosome (linkage group), and 'chromosome' indicates which of the diploid pair of chromosomes is measured, allowing for phased output if required.

Examples

sim_pop <- simulate_policy(initial_population_size = 100,
                           num_generations = 20,
                           starting_freq = 0.2,
                           K = 400)
plot(sim_pop$results$num_individuals ~ sim_pop$results$t)