Demographic models

class Migrator

class Migrator

This operator migrates individuals from (virtual) subpopulations to other subpopulations, according to either pre-specified destination subpopulation stored in an information field, or randomly according to a migration matrix.

In the former case, values in a specified information field (default to migrate_to) are considered as destination subpopulation for each individual. If subPops is given, only individuals in specified (virtual) subpopulations will be migrated where others will stay in their original subpopulation. Negative values are not allowed in this information field because they do not represent a valid destination subpopulation ID.

In the latter case, a migration matrix is used to randomly assign destination subpoulations to each individual. The elements in this matrix can be probabilities to migrate, proportions of individuals to migrate, or exact number of individuals to migrate.

By default, the migration matrix should have m by m elements if there are m subpopulations. Element (i, j) in this matrix represents migration probability, rate or count from subpopulation i to j. If subPops (length m) and/or toSubPops (length n) are given, the matrix should have m by n elements, corresponding to specified source and destination subpopulations. Subpopulations in subPops can be virtual subpopulations, which makes it possible to migrate, for example, males and females at different rates from a subpopulation. If a subpopulation in toSubPops does not exist, it will be created. In case that all individuals from a subpopulation are migrated, the empty subpopulation will be kept.

If migration is applied by probability, the row of the migration matrix corresponding to a source subpopulation is intepreted as probabilities to migrate to each destination subpopulation. Each individual’s detination subpopulation is assigned randomly according to these probabilities. Note that the probability of staying at the present subpopulation is automatically calculated so the corresponding matrix elements are ignored.

If migration is applied by proportion, the row of the migration matrix corresponding to a source subpopulation is intepreted as proportions to migrate to each destination subpopulation. The number of migrants to each destination subpopulation is determined before random indidividuals are chosen to migrate.

If migration is applied by counts, the row of the migration matrix corresponding to a source subpopulation is intepreted as number of individuals to migrate to each detination subpopulation. The migrants are chosen randomly.

This operator goes through all source (virtual) subpopulations and assign detination subpopulation of each individual to an information field. Unexpected results may happen if individuals migrate from overlapping virtual subpopulations.

Migrator(rate=[], mode=BY_PROBABILITY, toSubPops=ALL_AVAIL, begin=0, end=-1, step=1, at=[], reps=ALL_AVAIL, subPops=ALL_AVAIL, infoFields=["migrate_to"])

Create a Migrator that moves individuals from source (virtual) subpopulations subPops (default to migrate from all subpopulations) to destination subpopulations toSubPops (default to all subpopulations), according to existing values in an information field infoFields*[0], or randomly according to a migration matrix *rate. In the latter case, the size of the matrix should match the number of source and destination subpopulations.

Depending on the value of parameter mode, elements in the migration matrix (rate) are interpreted as either the probabilities to migrate from source to destination subpopulations (mode = BY_PROBABILITY), proportions of individuals in the source (virtual) subpopulations to the destination subpopulations (mode = BY_PROPORTION), numbers of migrants in the source (virtual) subpopulations (mode = BY_COUNTS), or ignored completely (mode = BY_IND_INFO). In the last case, parameter subPops is respected (only individuals in specified (virtual) subpopulations will migrate) but toSubPops is ignored.

Please refer to operator BaseOperator for a detailed explanation for all parameters.

class BackwardMigrator

class BackwardMigrator

This operator migrates individuals between all available or specified subpopulations, according to a backward migration matrix. It differs from Migrator in how migration matrixes are interpreted. Due to the limit of this model, this operator does not support migration by information field, migration by count (mode = BY_COUNT), migration from virtual subpopulations, migration between different number of subpopulations, and the creation of new subpopulation, as operator Migrator provides.

In contrast to a forward migration matrix where $m_{ij}$ is considered the probability (proportion or count) of individuals migrating from subpopulation i to j, elements in a reverse migration matrix $m_{ij}$ is considered the probability (proportion or count) of individuals migrating from subpopulation j to i, namely the probability (proportion or count) of individuals originats from subpopulation j.

If migration is applied by probability, the row of the migration matrix corresponding to a destination subpopulation is intepreted as probabilities to orignate from each source subpopulation. Each individual’s source subpopulation is assigned randomly according to these probabilities. Note that the probability of originating from the present subpopulation is automatically calculated so the corresponding matrix elements are ignored.

If migration is applied by proportion, the row of the migration matrix corresponding to a destination subpopulation is intepreted as proportions to originate from each source subpopulation. The number of migrants from each source subpopulation is determined before random indidividuals are chosen to migrate.

Unlike the forward migration matrix that describes how migration should be performed, the backward migration matrix describes the result of migration. The underlying forward migration matrix is calculated at each generation and is in theory not the same across generations.

This operator calculates the corresponding forward migration matrix from backward matrix and current population size. This process is not always feasible so an error will raise if no valid ending population size or forward migration matrix could be determined. Please refer to the simuPOP user’s guide for an explanation of the theory behind forward and backward migration matrices.

BackwardMigrator(rate=[], mode=BY_PROBABILITY, begin=0, end=-1, step=1, at=[], reps=ALL_AVAIL, subPops=ALL_AVAIL, infoFields=["migrate_to"])

Create a BackwardMigrator that moves individuals between subPop subpopulations randomly according to a backward migration matrix rate. The size of the matrix should match the number of subpopulations.

Depending on the value of parameter mode, elements in the migration matrix (rate) are interpreted as either the probabilities to originate from source subpopulations (mode = BY_PROBABILITY) or proportions of individuals originate from the source (virtual) subpopulations (mode = BY_PROPORTION). Migration by count is not supported by this operator.

Please refer to operator BaseOperator for a detailed explanation for all parameters.

class SplitSubPops

class SplitSubPops

Split a given list of subpopulations according to either sizes of the resulting subpopulations, proportion of individuals, or an information field. The resulting subpopulations will have the same name as the original subpopulation.

SplitSubPops(subPops=ALL_AVAIL, sizes=[], proportions=[], names=[], randomize=True, begin=0, end=-1, step=1, at=[], reps=ALL_AVAIL, infoFields=[])

Split a list of subpopulations subPops into finer subpopulations. A single subpopulation is acceptable but virtual subpopulations are not allowed. All subpopulations will be split if subPops is not specified.

The subpopulations can be split in three ways:

• If parameter sizes is given, each subpopulation will be split into subpopulations with given size. The sizes should add up to the size of all orignal subpopulations.
• If parameter proportions is given, each subpopulation will be split into subpopulations with corresponding proportion of individuals. proportions should add up to 1.
• If an information field is given (parameter infoFields), individuals having the same value at this information field will be grouped into a subpopulation. The number of resulting subpopulations is determined by the number of distinct values at this information field.

If parameter randomize is True (default), individuals will be randomized before a subpopulation is split. This is designed to remove artificial order of individuals introduced by, for example, some non- random mating schemes. Note that, however, the original individual order is not guaranteed even if this parameter is set to False.

Unless the last subpopulation is split, the indexes of existing subpopulations will be changed. If a subpopulation has a name, this name will become the name for all subpopulations separated from this subpopulation. Optionally, you can assign names to the new subpopulations using a list of names specified in parameter names. Because the same set of names will be used for all subpopulations, this parameter is not recommended when multiple subpopulations are split.

Please refer to operator BaseOperator for a detailed explanation for all parameters.

Note

Unlike operator Migrator, this operator does not require an information field such as migrate_to.

class MergeSubPops

class MergeSubPops

This operator merges subpopulations subPops to a single subpopulation. If subPops is ignored, all subpopulations will be merged. Virtual subpopulations are not allowed in subPops.

MergeSubPops(subPops=ALL_AVAIL, name="", begin=0, end=-1, step=1, at=[], reps=ALL_AVAIL, infoFields=[])

Create an operator that merges subpopulations subPops to a single subpopulation. If subPops is not given, all subpopulations will be merged. The merged subpopulation will take the name of the first subpopulation being merged unless a new name is given.

Please refer to operator BaseOperator for a detailed explanation for all parameters.

class ResizeSubPops

class ResizeSubPops

This operator resizes subpopulations to specified sizes. individuals are added or removed depending on the new subpopulation sizes.

ResizeSubPops(subPops=ALL_AVAIL, sizes=[], proportions=[], propagate=True, begin=0, end=-1, step=1, at=[], reps=ALL_AVAIL, infoFields=[])

Resize given subpopulations subPops to new sizes size, or sizes proportional to original sizes (parameter proportions). All subpopulations will be resized if subPops is not specified. If the new size of a subpopulation is smaller than its original size, extra individuals will be removed. If the new size is larger, new individuals with empty genotype will be inserted, unless parameter propagate is set to True (default). In this case, existing individuals will be copied sequentially, and repeatedly if needed.

Please refer to operator BaseOperator for a detailed explanation for all parameters.