feat_migration {coala}

Feature: Migration/Gene Flow

Description

This feature changes the migration rates at a given time point. Per default, no migration between the population occurs, which corresponds to a rate of 0. Set it to a value greater than zero to enable migration from one population to another.

Usage

feat_migration(
  rate,
  pop_from = NULL,
  pop_to = NULL,
  symmetric = FALSE,
  time = "0",
  locus_group = "all"
)

Arguments

rate

The migration rate. Can be a numeric or a parameter. The rate is specified as 4 * N0 * m, where m is the fraction of pop_to that is replaced by migrants from pop_from each generation (in forward time).

pop_from

The population from which the individuals leave.

pop_to

The population to which the individuals move.

symmetric

Use the rate for all pairs of populations.

time

The time point at which the migration with the migration rate is set. The rate applies to the time past warts of the time point, until it is changed again.

locus_group

The loci for which this features is used. Can either be "all" (default), in which case the feature is used for simulating all loci, or a numeric vector. In the latter case, the feature is only used for the loci added in locus_ commands with the corresponding index starting from 1 in order in which the commands where added to the model. For example, if a model has locus_single(10) + locus_averaged(10, 11) + locus_single(12) and this argument is c(2, 3), than the feature is used for all but the first locus (that is locus 2 - 12).

Details

When looking forward in time, a fraction of pop_to that is replaced by migrants from pop_from each generation (see rate). When looking backwards in time, ancestral lines in pop_to move to pop_from with the given rate.

Value

The feature, which can be added to a model created with coal_model using +.

See Also

For creating a model: coal_model

Other features: feat_growth(), feat_ignore_singletons(), feat_mutation(), feat_outgroup(), feat_pop_merge(), feat_recombination(), feat_selection(), feat_size_change(), feat_unphased()

Examples

# Asymmetric migration between two populations:
model <- coal_model(c(5, 5), 10) +
  feat_migration(0.5, 1, 2) +
  feat_migration(1.0, 2, 1) +
  feat_mutation(5) +
  sumstat_sfs()
simulate(model)

# Three populations that exchange migrations with equal
# rates at times more than 0.5 time units in the past:
model <- coal_model(c(3, 4, 5), 2) +
  feat_migration(1.2, symmetric = TRUE, time = 0.5) +
  feat_mutation(5) +
  sumstat_sfs()
simulate(model)