This mating scheme is the base class of all mating schemes. It evolves a population generation by generation but does not actually transmit genotype.
A homogeneous mating scheme that uses a parent chooser to choose parents from a prental generation, and an offspring generator to generate offspring from chosen parents. It can be either used directly, or within a heterogeneous mating scheme. In the latter case, it can be applied to a (virtual) subpopulation.
Create a homogeneous mating scheme using a parent chooser chooser and an offspring generator generator.
If this mating scheme is used directly in a simulator, it will be responsible for creating an offspring population according to parameter subPopSize. This parameter can be a list of subpopulation sizes (or a number if there is only one subpopulation) or a Python function which will be called at each generation to determine the subpopulation sizes of the offspring generation. Please refer to class MatingScheme for details about this parameter.
If this mating shcme is used within a heterogeneous mating scheme. Parameters subPops and weight are used to determine which (virtual) subpopulations this mating scheme will be applied to, and how many offspring this mating scheme will produce. Please refer to mating scheme HeteroMating for the use of these two parameters.
A heterogeneous mating scheme that applies a list of homogeneous mating schemes to different (virtual) subpopulations.
Create a heterogeneous mating scheme that will apply a list of homogeneous mating schemes matingSchemes to different (virtual) subpopulations. The size of the offspring generation is determined by parameter subPopSize, which can be a list of subpopulation sizes or a Python function that returns a list of subpopulation sizes at each generation. Please refer to class MatingScheme for a detailed explanation of this parameter.
Each mating scheme defined in matingSchemes can be applied to one or more (virtual) subpopulation. If parameter subPops is not specified, a mating scheme will be applied to all subpopulations. If a list of (virtual) subpopulation is specified, the mating scheme will be applied to specific (virtual) subpopulations.
If multiple mating schemes are applied to the same subpopulation, a weight (parameter weight) can be given to each mating scheme to determine how many offspring it will produce. The default for all mating schemes are 0. In this case, the number of offspring each mating scheme produces is proportional to the size of its parental (virtual) subpopulation. If all weights are negative, the numbers of offspring are determined by the multiplication of the absolute values of the weights and their respective parental (virtual) subpopulation sizes. If all weights are positive, the number of offspring produced by each mating scheme is proportional to these weights. Mating schemes with zero weight in this case will produce no offspring. If both negative and positive weights are present, negative weights are processed before positive ones.
If multiple mating schemes are applied to the same subpopulation, offspring produced by these mating schemes are shuffled randomly. If this is not desired, you can turn off offspring shuffling by setting parameter shuffleOffspring to False.
A conditional mating scheme that applies different mating schemes according to a condition (similar to operator IfElse). The condition can be a fixed condition, an expression or a user-defined function, to determine which mating scheme to be used.
This mating scheme evolves a population following an existing pedigree structure. If the Pedigree object has N ancestral generations and a present generation, it can be used to evolve a population for N generations, starting from the topmost ancestral generation. At the k-th generation, this mating scheme produces an offspring generation according to subpopulation structure of the N-k-1 ancestral generation in the pedigree object (e.g. producing the offspring population of generation 0 according to the N-1 ancestral generation of the pedigree object ). For each offspring, this mating scheme copies individual ID and sex from the corresponing individual in the pedigree object. It then locates the parents of each offspring using their IDs in the pedigree object. A list of during mating operators are then used to transmit parental genotype to the offspring. The population being evolved must have an information field 'ind_id'.
This parent chooser chooses a parent from a parental (virtual) subpopulation sequentially. Natural selection is not considered. If the last parent is reached, this parent chooser will restart from the beginning of the (virtual) subpopulation.
This parent chooser chooses two parents (a father and a mother) sequentially from their respective sex groups. Selection is not considered. If all fathers (or mothers) are exhausted, this parent chooser will choose fathers (or mothers) from the beginning of the (virtual) subpopulation again.
This parent chooser chooses a parent randomly from a (virtual) parental subpopulation. Parents are chosen with or without replacement. If parents are chosen with replacement, a parent can be selected multiple times. If individual fitness values are assigned to individuals ( stored in an information field selectionField (default to "fitness"), individuals will be chosen at a probability proportional to his or her fitness value. If parents are chosen without replacement, a parent can be chosen only once. An RuntimeError will be raised if all parents are exhausted. Natural selection is disabled in the without- replacement case.
This parent chooser chooses two parents, a male and a female, randomly from a (virtual) parental subpopulation. Parents are chosen with or without replacement from their respective sex group. If parents are chosen with replacement, a parent can be selected multiple times. If individual fitness values are assigned (stored in information field selectionField, default to "fitness", the probability that an individual is chosen is proportional to his/her fitness value among all individuals with the same sex. If parents are chosen without replacement, a parent can be chosen only once. An RuntimeError will be raised if all males or females are exhausted. Natural selection is disabled in the without-replacement case.
This parent chooser is similar to random parents chooser but instead of selecting a new pair of parents each time, one of the parents in this parent chooser will mate with several spouses before he/she is replaced. This mimicks multi-spouse mating schemes such as polygyny or polyandry in some populations. Natural selection is supported for both sexes.
This parent chooser accepts two parent choosers. It takes one parent from each parent chooser and return them as father and mother. Because two parent choosers do not have to choose parents from the same virtual subpopulation, this parent chooser allows you to choose parents from different subpopulations.
This parent chooser accepts a Python generator function that repeatedly yields one or two parents, which can be references to individual objects or indexes relative to each subpopulation. The parent chooser calls the generator function with parental population and a subpopulation index for each subpopulation and retrieves parents repeatedly using the iterator interface of the generator function.
This parent chooser does not support virtual subpopulation directly. However, because virtual subpopulations are defined in the passed parental population, it is easy to return parents from a particular virtual subpopulation using virtual subpopulation related functions.
An offspring generator generates offspring from parents chosen by a parent chooser. It is responsible for creating a certain number of offspring, determinning their sex, and transmitting genotypes from parents to offspring.
Create a basic offspring generator. This offspring generator uses ops genotype transmitters to transmit genotypes from parents to offspring.
A number of during-mating operators (parameter ops) can be used to, among other possible duties such as setting information fields of offspring, transmit genotype from parents to offspring. This general offspring generator does not have any default during-mating operator but all stock mating schemes use an offspring generator with a default operator. For example, a mendelianOffspringGenerator is used by RandomMating to trasmit genotypes. Note that applicability parameters begin, step, end, at and reps could be used in these operators but negative population and generation indexes are unsupported.
Parameter numOffspring is used to control the number of offspring per mating event, or in another word the number of offspring in each family. It can be a number, a Python function or generator, or a mode parameter followed by some optional arguments. If a number is given, given number of offspring will be generated at each mating event. If a Python function is given, it will be called each time when a mating event happens. When a generator function is specified, it will be called for each subpopulation to provide number of offspring for all mating events during the populating of this subpopulation. Current generation number will be passed to this function or generator function if parameter “gen” is used in this function. In the last case, a tuple (or a list) in one of the following forms can be given:
In this case, the number of offspring will be determined randomly following the specified statistical distributions. Because families with zero offspring are silently ignored, the distribution of the observed number of offspring per mating event (excluding zero) follows zero-truncated versions of these distributions.
Parameter numOffspring specifies the number of offspring per mating event but the actual surviving offspring can be less than specified. More spefically, if any during-mating operator returns False, an offspring will be discarded so the actually number of offspring of a mating event will be reduced. This is essentially how during-mating selector works.
Parameter sexMode is used to control the sex of each offspring. Its default value is usually RANDOM_SEX which assign MALE or FEMALE to each individual randomly, with equal probabilities. If NO_SEX is given, offspring sex will not be changed. sexMode can also be one of
Finally, parameter sexMode accepts a function or a generator function. A function will be called whenever an offspring is produced. A generator will be created at each subpopulation and will be used to produce sex for all offspring in this subpopulation. No parameter is accepted.
This offspring generator populates an offspring population and controls allele frequencies at specified loci. At each generation, expected allele frequencies at these loci are passed from a user defined allele frequency trajectory function. The offspring population is populated in two steps. At the first step, only families with disease alleles are accepted until until the expected number of disease alleles are met. At the second step, only families with wide type alleles are accepted to populate the rest of the offspring generation. This method is described in detail in “Peng et al, (2007) PLoS Genetics”.
Create an offspring generator that selects offspring so that allele frequency at specified loci in the offspring generation reaches specified allele frequency. At the beginning of each generation, expected allele frequency of alleles at loci is returned from a user-defined trajectory function freqFunc. Parameter loci can be a list of loci indexes, names, or ALL_AVAIL. If there is no subpopulation, this function should return a list of frequencies for each locus. If there are multiple subpopulations, freqFunc can return a list of allele frequencies for all subpopulations or combined frequencies that ignore population structure. In the former case, allele frequencies should be arranged by loc0_sp0, loc1_sp0, ... loc0_sp1, loc1_sp1, ..., and so on. In the latter case, overall expected number of alleles are scattered to each subpopulation in proportion to existing number of alleles in each subpopulation, using a multinomial distribution.
After the expected alleles are calculated, this offspring generator accept and reject families according to their genotype at loci until allele frequecies reach their expected values. The rest of the offspring generation is then filled with families without only wild type alleles at these loci.
This offspring generator is derived from class OffspringGenerator. Please refer to class OffspringGenerator for a detailed description of parameters ops, numOffspring and sexMode.