Package org.evoludo.simulator.modules

Class Moran

Object
Module
Discrete
Moran
All Implemented Interfaces:
Runnable, IBS.HasIBS, MilestoneListener, ODE.HasDE, ODE.HasODE, PDE.HasPDE, SDE.HasSDE, Features, Features.Static, HasHistogram, HasHistogram.Degree, HasHistogram.Fitness, HasHistogram.StatisticsProbability, HasHistogram.StatisticsStationary, HasHistogram.StatisticsTime, HasMean, HasMean.Fitness, HasMean.Strategy, HasPop2D, HasPop2D.Fitness, HasPop2D.Strategy, HasPop3D, HasPop3D.Fitness, HasPop3D.Strategy, CLOProvider
Direct Known Subclasses:
simMoran
public class Moran extends Discrete implements Features.Static, IBS.HasIBS, ODE.HasODE, SDE.HasSDE, PDE.HasPDE, HasPop2D.Strategy, HasPop3D.Strategy, HasMean.Strategy, HasPop2D.Fitness, HasPop3D.Fitness, HasMean.Fitness, HasHistogram.Fitness, HasHistogram.Degree, HasHistogram.StatisticsProbability, HasHistogram.StatisticsTime, HasHistogram.StatisticsStationary
The module for investigating the evolutionary dynamics in the classical Moran process with two types of individuals that have constant fitness values. In the limit of infinite populations the type with the higher fitness invariably takes over regardless of its fitness advantage. However, in finite populations the less fit type may nevertheless reach fixation or the fitter type vanish. In particular, a single mutant in a population of size \(N\) with (scaled) fitness \(r\) in an otherwise homogeneous resident population with fitness \(1\) reaches fixation with probability \begin{align} \rho_N &= \dfrac{1-\frac1r}{1-\frac1{r^N}}. \end{align} Interestingly, for beneficial mutants, \(r>1\), the fixation probability \(\rho\) does not approach \(1\) even in the limit \(N\to\infty\) but rather \(\rho_\infty = 1-1/r\).

In structured populations the situation gets even more interesting in that certain population structures can act as evolutionary amplifiers or evolutionary suppressors by increasing or decreasing the fixation probabilities of advantageous mutants.

Author:
Christoph Hauert

  • Field Details

    • RESIDENT

      public static final int RESIDENT
      The trait (and index) value of residents.
      See Also:

    • MUTANT

      public static final int MUTANT
      The trait (and index) value of mutants.
      See Also:

    • typeScores

      protected double[] typeScores
      The array with the scores for each trait.

    • rhoAi

      double rhoAi
      Store fixation probability of i individuals of type A.

    • tAi

      double tAi
      Store fixation time of i individuals of type A.

    • taui

      double taui
      Store absorption time of i individuals of type A.

    • cloFitness

      public final CLOption cloFitness
      Command line option to set the fitness values for residents and mutants.

  • Constructor Details

    • Moran

      public Moran(EvoLudo engine)
      Create a new instance of the module for the Moran process.
      Parameters:
      engine - the manager of modules and pacemaker for running the model

  • Method Details

    • load

      public void load()
      Description copied from class: Module
      Load new module and perform basic initializations.
      Overrides:
      load in class Discrete
      See Also:

    • unload

      public void unload()
      Description copied from class: Module
      Unload module and free all resources.
      Overrides:
      unload in class Discrete
      See Also:

    • getAuthors

      public String getAuthors()
      Description copied from class: Module
      Returns a string with information about the authors of the module.
      Overrides:
      getAuthors in class Module
      Returns:
      the names of the authors

    • getTitle

      public String getTitle()
      Description copied from class: Module
      Returns title of active module, e.g. 2x2 games in TBT returns "2x2 Games".
      Specified by:
      getTitle in class Module
      Returns:
      the title of active module

    • getDependent

      public int getDependent()
      Description copied from class: Module
      Get the index of dependent type or -1 if Module does not have an dependent type.

      Notes:

      • Dependent types are used by replicator type models where the frequencies of all types must sum up to one. Currently only used by Discrete modules.
      • Density modules do not have dependent types.
      • By default use vacant type as the dependent
      Specified by:
      getDependent in interface ODE.HasDE
      Overrides:
      getDependent in class Module
      Returns:
      the index of the vacant type

    • getMinGameScore

      public double getMinGameScore()
      Description copied from class: Module
      Calculates and returns the minimum payoff/score of an individual. This value is important for converting payoffs/scores into probabilities, for scaling graphical output and some optimizations.
      Specified by:
      getMinGameScore in class Module
      Returns:
      the minimum payoff/score
      See Also:

    • getMaxGameScore

      public double getMaxGameScore()
      Description copied from class: Module
      Calculates and returns the maximum payoff/score of an individual. This value is important for converting payoffs/scores into probabilities, for scaling graphical output and some optimizations.
      Specified by:
      getMaxGameScore in class Module
      Returns:
      the maximum payoff/score
      See Also:

    • getMonoGameScore

      public double getMonoGameScore(int type)
      Description copied from class: Discrete
      Calculate and return the payoff/score of individuals in monomorphic populations with trait/strategy type.

      Note: Optional implementation. Returns Double#NaN if not defined or not implemented.

      Overrides:
      getMonoGameScore in class Discrete
      Parameters:
      type - trait/strategy
      Returns:
      payoff/score in monomorphic population with trait/strategy type

    • getStaticScores

      public double[] getStaticScores()
      Description copied from interface: Features.Static
      Gets the static scores for the different types.
      Specified by:
      getStaticScores in interface Features.Static
      Returns:
      the array with the static scores

    • avgScores

      public void avgScores(double[] density, int n, double[] avgscores)
      Description copied from interface: ODE.HasDE
      Calculate the average payoff/score for the frequency of traits/strategies specified in the array density for interactions in groups of size n. The average payoffs/scores for each of the nTraits traits/strategies must be stored and returned in the array avgscores.

      Note: needs to be thread safe for parallel processing of PDE's.

      IMPORTANT: one of

      should be implemented in modules that advertise the model types ODE, SDE or PDE.

      Alternatively, the method ODE.getDerivatives(double, double[], double[], double[]) may be overridden in a subclass of ODE, which may prevent calls to avgScores(...) altogether.

      Specified by:
      avgScores in interface ODE.HasDE
      Parameters:
      density - the frequency/density of each trait/strategy
      n - the size of interaction groups
      avgscores - the array for storing the average payoffs/scores for each strategic type

    • setFitness

      public void setFitness(double[] aValue)
      Set the fitness values for residents and mutants.
      Parameters:
      aValue - the array with fitness values

    • setFitness

      public void setFitness(double aValue, int aType)
      Set the fitness value for trait aType to aValue.
      Parameters:
      aValue - the fitness for trait aType
      aType - the trait to set the fitness

    • getFitness

      public double[] getFitness()
      Get the array of fitness values for residents and mutants.
      Returns:
      the array of fitness values

    • getFitness

      public double getFitness(int aType)
      Get the fitness value for trait aType.
      Parameters:
      aType - the trait to get the fitness
      Returns:
      the fitness value

    • getCustomLevels

      public double[] getCustomLevels(Data type, int trait)
      Description copied from interface: HasHistogram
      Some models may provide reference values for histograms as a horizontal line marking a particular value. For example this is the case for statistics of fixation probabilities or times in the org.evoludo.simulator.modules.Moran Moran module where the analytical results are provided as a reference to highlight the effects of population structures.
      Specified by:
      getCustomLevels in interface HasHistogram
      Parameters:
      type - the type of data shown in the histogram
      trait - the index of the trait
      Returns:
      the array of levels for reference

    • modelSettings

      public void modelSettings()
      Description copied from interface: MilestoneListener
      Called when the settings of the EvoLudo model changed but no reset was necessary.
      Specified by:
      modelSettings in interface MilestoneListener

    • getReferenceProb

      private double[] getReferenceProb(int trait)
      Helper method to retrieve the reference fixation probabilities for trait trait for the initial number of mutants according to init. In order to optimize repeated calls the result is stored in the field statRefProb and storage allocated as necessary.
      Parameters:
      trait - the trait for which to get the reference fixation probability
      Returns:
      the reference fixation probability
      See Also:

    • getReferenceTime

      private double[] getReferenceTime(int trait)
      Helper method to retrieve the reference fixation times for trait trait for the initial number of mutants according to init. In order to optimize repeated calls the result is stored in the field statRefTime and storage allocated as necessary.
      Parameters:
      trait - the trait for which to get the reference fixation time
      Returns:
      the reference fixation time
      See Also:

    • collectCLO

      public void collectCLO(CLOParser parser)
      Description copied from interface: CLOProvider
      All providers of command line options must implement this method to collect their options.

      Each command line option is (uniquely) identified by it's name (see CLOption.getName()), which corresponds to the long version of the option. If an attempt is made to add an option with a name that already exists, the parser issues a warning and ignores the option. Thus, in general, implementing subclasses should first register their options and call super.collectCLO(CLOParser) at the end such that subclasses are able to override command line options specified in a parental class.

      Override this method in subclasses to add further command line options. Subclasses must make sure that they include a call to super.

      Specified by:
      collectCLO in interface CLOProvider
      Overrides:
      collectCLO in class Discrete
      Parameters:
      parser - the reference to parser that manages command line options
      See Also:

    • Tplus

      private double Tplus(int i, int n)
      Transition probability to go from i to i+1 mutants in a population of size N.
      Parameters:
      i - the number of mutants
      n - the size of the population
      Returns:
      the transition probability

    • Tratio

      private double Tratio(int i)
      The ratio of transition probabilities to go from i to i+1 mutants over the reverse, i.e. \(T_i^-/T_i^+). In the classical Moran process this is simply a constant and, in particular, independent of i.
      Parameters:
      i - the number of mutants
      Returns:
      the ratio of transition probabilities

    • rhoA

      protected double rhoA(int i, int n)
      The fixation probability of i mutants in a population of constant size N (and N-i residents).
      Parameters:
      i - the number of mutants
      n - the size of the population
      Returns:
      the fixation probability

    • t1

      protected double t1(double rhoA, int n)
      The absorbtion time (in generations) of a single mutant in a population of constant size N (and N-1 residents).
      Parameters:
      rhoA - the fixation probability of a single mutant
      n - the size of the population
      Returns:
      the absorbtion time
      See Also:

    • ti

      protected double ti(int i, int n, double t1)
      The absorbtion time (in generations) of i mutants in a population of constant size N (and N-i residents).
      Parameters:
      i - the number of mutants
      n - the size of the population
      t1 - the absorbtion time of a single mutant
      Returns:
      the absorbtion time of i mutants
      See Also:

    • tA1

      protected double tA1(int n)
      The conditional fixation time of a single mutant in a population of fixed size N (and N-1 residents) measured in generations.
      Parameters:
      n - the size of the population
      Returns:
      the conditional fixation time

    • tAi

      protected double tAi(int i, int n, double rhoA, double tA1)
      The conditional fixation time of i mutants in a population of fixed size N (and N-i residents) measured in generations.
      Parameters:
      i - the number of mutants
      n - the size of the population
      rhoA - the fixation probability of a single mutant
      tA1 - the fixation time of a single mutant
      Returns:
      the conditional fixation time