Create a subpopulation

coalestr allows us to create subpopulations that are embedded within a larger metapopulation, and that receive migration from the metapopulation.

• First we create the metapopulation. To create a global metapopulation that takes account of historical patterns of parasite dispersal, a useful shortcut is the coalestr.species() function.

• When we create the subpopulation we specify its metapopulation. When we construct the subpopulation’s history of transmission parameters, we specify the rate of migration from the metapopulation.

• M gives the number of hosts per generation that enter the subpopulation from the metapopulation, which must be less than or equal to N.

We must run get_coalescent on the metapopulation before running get_coalescent on the subpopulation. This is because times to coalescence in the metapopulation are needed to calculate times to coalescence in the subpopulation.

!pip install coalestr
from coalestr import cs

''' CREATING THE METAPOPULATION '''

# This is done in the same way as creating a simple population, e.g.

my_metapop_history = [[20000, 1000, 5, 0.5, 0]]

my_metapopulation = cs.Population(my_metapop_history)

# A shortcut for creating a global metapopulation is to use coalestr.species

my_metapopulation = cs.species()

my_metapopulation.get_coalescent()

Observation time.    Events captured.   Mean coalescence time
                      beho      wiho        beho     wiho
        0             100.0     100.0     17961.7   6421.2

''' CREATING THE SUBPOPULATION

We specify the history of transmission parameters 
with the format [duration, N, Q, X, M]
where M gives the number of hosts per generation
that enter the subpopulation from the metapopulation

When we create the subpopulation we use the keyword argument 'metapopulation'
to state the name of the metapopulation. '''

# In this example M = 1. 
my_subpop_history = [[1000, 30, 5, 1, 1]]

# We state that my_population is the metapopulation.
my_subpopulation = cs.Population(my_subpop_history, metapopulation = my_metapopulation)

my_subpopulation.get_coalescent()

Observation time.    Events captured.   Mean coalescence time
                      beho      wiho        beho     wiho
        0             100.0     100.0     15572.7  13639.6

In the above example M = 1. If we change this to M = 0, we can immediately see how a small rate of migration from the metapopulation into the subpopulation makes a big difference to the coalescence time in the subpopulation.

my_subpop_history = [[1000, 30, 5, 1, 0]]

my_subpopulation = cs.Population(my_subpop_history, metapopulation = my_metapopulation)

my_subpopulation.get_coalescent()

Observation time.    Events captured.   Mean coalescence time
                      beho      wiho        beho     wiho
        0             100.0     100.0       100.6     88.3