metapypulation package

Submodules

metapypulation.individual module

A module containing the individual class.

class metapypulation.individual.Individual(id: int, original_deme_id: int, number_of_features: int, number_of_traits: int, mutation_rate: float = 0.0, features: List = None)

Bases: object

Base class for an individual in the metapopulation.

id

The identifier for the individual (unique within the subpopulation).

Type:

int

original_deme_id

Identifier of the deme where the individual originated.

Type:

int

number_of_features

Number of cultural features of the individual.

Type:

int

number_of_traits

Number of traits per feature of the individual.

Type:

int

mutation_rate

Probability of a random mutation to occur during cultural transmission.

Type:

float

features

List of features of the individual.

Type:

List[int]

number_of_changes

The number of times this individual has changed set of features following an interaction.

Type:

int

axelrod_interaction(interacting_individual: Individual) → None

Interaction following the Axelrod model of culture dissemination. A random individual (source) is selected. The probability of interacting is given by the number of traits in common between the focal individual (self) and the source divided by the total number of features. If they interact, the focal individual copies one of the features of the source for which they are not equal.

Parameters:

interacting_individual (Individual) – Individual with which the self individual interacts. Currently accepts only “axelrod_interaction”.

interact(interacting_individual: Individual, interaction_function: str) → None

Wrapper for interactions, it allows to pass any interaction that is coded for.

Parameters:

• interaction_function (str) – The type of interaction that decides the outcome of the interaction. Current options are “neutral_interaction” and “axelrod_interaction”.

• interacting_individual (Individual) – Individual with which the self individual interacts.

neutral_interaction(interacting_individual: Individual) → None

Interaction following a neutral model, where replication of a trait is purely based on frequency in the population. The focal indivdual changes one trait at random copying from the source individual.

metapypulation.metapopulation module

A module containing the class Metapopulation, which determines the topology of the metapopulation as well as the migration rates between populations.

class metapypulation.metapopulation.Metapopulation(number_of_subpopulations: int, type_of_interaction: str, migration_matrix: ndarray = None, carrying_capacities: List[int] | int = 100, number_of_features: int = 5, number_of_traits: int = 10, mutation_rate: float = 0.0, min_trait: int = 1, max_trait: int = 10)

Bases: object

The base class for a metapopulation containing subpopulations.

number_of_subpopulations

how many subpopulations compose the metapopulation.

Type:

int

subpopulations

the list of Subpopulation objects in the metapopulation.

Type:

SetOfSubpopulations

type_of_interaction

The type of interaction to implement between individuals for cultural changes. Currently accepts only “axelrod_interaction”.

Type:

str

migration_matrix

A matrix determining migration rates between subpopulations.

Type:

np.ndarray

carrying_capacities

A list of carrying capacities (one for each subpopulation) or an integer (same carrying capacity for each subpopulation).

Type:

List[int] | int

number_of_features

Total number of cultural features per individual.

Type:

int

number_of_traits

Number of different possible traits for each cultural feature.

Type:

int, optional

mutation_rate

Probability of a mutation to occur.

Type:

float, optional

min_trait

Minimum value for a trait in each feature.

Type:

int, optional

max_trait

Maximum value for a trait in each feature.

Type:

int, optional

count_origin_id_spread() → ndarray

Counts the spread of individuals from deme of origin by counting how many individuals from each deme are in each deme.

Returns:

NxN matrix where N is the number of subpopulations. Rows are local subpopulations, columns are the original deme id.

Return type:

np.ndarray

get_metapopulation_size() → int

Calculates the full size of the metapopulation. In the absence of population reduction strategies, this is always equal to the sum of all the carrying capacities.

Returns:

the number of individuals in the whole metapopulation.

Return type:

int

gini_diversity_per_subpopulation() → List[float]

Calculates Gini diversity index in each subpopulation.

Returns:

list with the Gini diversity index per subpopulation.

Return type:

List[float]

make_interact() → None

Make one interaction in each subpopulation.

metapopulation_count_sets() → int

Calculates number of unique sets of traits in the whole metapopulation.

Returns:

number of unique sets in the metapopulation.

Return type:

int

metapopulation_gini_diversity() → float

Calculates Gini-Simpson diversity index over the whole metapopulation.

Returns:

Gini-Simpson diversity index of the metapopulation.

Return type:

float

metapopulation_shannon_diversity() → float

Calculates Shannon diversity trait over the whole metapopulation.

Returns:

Shannon diversity index of the metapopulation.

Return type:

float

metapopulation_simpson_diversity() → float

Calculates Simpson diversity index over the whole metapopulation.

Returns:

Simpson diversity index of the metapopulation.

Return type:

float

migrate() → None

A function that causes the migration step for a subpopulation. When called, each subpopulation finds to what subpopulations it needs to send individuals (based on the migration matrix supplied), and it calls upon the subpopulation.receive_migrants() function of the destinations.

After each subpopulation has received the migrants, the function subpopulation.incorporate_migrants_in_population() is called for each subpopulation. This merges the incoming migrants with the already existing population.

populate() → None

Populate all (empty) subpopulations within the Metapopulation class.

The populate step can take either a list of carrying capacities, a different number per each subpopulation, or one single carrying capacity that will determine the same number of individuals for each subpopulation.

shannon_diversity_per_subpopulation() → List[float]

Calculates Shannon diversity index in each subpopulation.

Returns:

list with the Shannon diversity index per subpopulation.

Return type:

List[float]

simpson_diversity_per_subpopulation() → List[float]

Calculates Simpson diversity index in each subpopulation.

Returns:

list with the Simpson diversity index per subpopulation.

Return type:

List[float]

traits_sets_per_subpopulation() → List[int]

Calculates number of unique sets of traits per each subpopulation.

Returns:

list with the number of unique sets per subpopulation.

Return type:

List[int]

whittaker_beta_diversity() → float

Calculate beta diversity as described by Whittaker (1960).

Returns:

Whittaker beta diversity.

Return type:

float

class metapypulation.metapopulation.SetOfSubpopulations(number_of_subpopulations: int, type_of_interaction: str)

Bases: Set

A class inheriting from Set to act as container of Subpopulation objects. Methods are standard for a Set.

class metapypulation.metapopulation.SubpopulationIterator(subpopulations)

Bases: object

An iterator object ot iterate over the SetOfSubpopulations class.

metapypulation.subpopulation module

A module containing the subpopulation class.

class metapypulation.subpopulation.IndividualsIterator(individuals)

Bases: object

An iterator object ot iterate over the SetOfSubpopulations class.

class metapypulation.subpopulation.SetOfIndividuals(deme: Subpopulation)

Bases: MutableSet

A class inheriting from MutableSet to act as container of Individual objects. Methods are standard for a MutableSet.

add(individual: Individual)

Adds an Individual to the SetOfIndividuals.

Parameters:

individual (Individual) – Individual to add to the set.

discard(individual: Individual)

Eliminates an individual from the set (and from the population).

Parameters:

individual (Individual) – Individual to be discarded.

empty_set() → None

Empty the Set.

sample_and_remove(number_of_individuals: int) → List[Individual]

Sample an individual, remove it from the Set and return it in a list.

Parameters:

number_of_individuals (int) – Number of individuals to sample randomly.

Returns:

List of all the individuals that have been sampled from the population.

Return type:

List[Individual]

shuffle() → None

Shuffle the Set.

class metapypulation.subpopulation.Subpopulation(id: int, type_of_interaction: str)

Bases: object

The base class for a subpopulation in the metapopulation.

id

Unique id of the subpopulation.

Type:

int

population

Set containing all the individuals in the subpopulation

Type:

SetOfIndividuals

outgoing_migrants

Set containing individuals that are being prepared for emigration. Empty outside of the migration step.

Type:

SetOfIndividuals

incoming_migrants

Set containind individuals that were received through immigration. Empty outside of the migration step.

Type:

SetOfIndividuals

type_of_interaction

The type of interaction to implement between individuals for cultural changes. Currently accepts only “axelrod_interaction”.

Type:

str

add_individual(individual: Individual) → None

Adds an individual to the subpopulation. This function does not remove the individual from somewhere else (in case of passages from list to list).

Parameters:

individual (Individual) – individual to be added to the subpopulation.

count_deme_origin_id(total_number_of_subpopulations: int) → List[int]

Count how many individuals originally from each deme are found in this deme. It is generally invoked from Metapopulation to get a summary.

Parameters:

total_number_of_subpopulations – number of subpopulations in the whole metapopulation.

Returns:

list containing a count of individuals for each subpopulation present.

Return type:

List[int]

count_traits_sets() → int

This function counts the total of unique sets of traits in the subpopulation. For example, [0, 1, 2, 3, 4] is a set different from [1, 1, 2, 3, 4], which is different from [5, 4, 3, 2, 1], etc.

Returns:

The current number of different sets of traits in the subpopulation.

Return type:

int

create_interaction() → None

Samples two individuals at random in the subpopulation and makes them interact.

get_current_number_of_migrants() → int

Returns the current number of incoming immigrants during. Only returns a non-zero number during the migration step.

Returns:

Current number of immigrants.

Return type:

int

get_population_size() → int

Returns the current subpopulation size.

Returns:

Current subpopulation size.

Return type:

int

get_traits_sets() → ndarray

This function returns all the feature sets found in a subpopulation in an array.

Returns:

All the current sets of features in the subpopulation.

Return type:

np.ndarray

gini_diversity() → float

Calculate the Gini-Simpson diversity index of the subpopulation. This is equal to 1 - Simpson_index

Returns:

The Gini-Simpson diversity index of the subpopulation.

Return type:

float

incorporate_migrants_in_population() → None

Merges incoming migrants into the local population.

is_trait_in_subpopulation(trait: int, feature: int = None) → bool

This function checks whether a given trait at a given feature is in the population.

Parameters:

• trait (int) – the int referring to the trait that needs to be checked against

• feature (Optional, int) – the feature that needs to be checked (index from 0 to N_features-1). If None, it checks for the trait in any feature. Default is None.

Returns:

True if the trait is found in the subpopulation.

Return type:

bool

list_migrants(migration_rate: float) → None

Create a list of migrants that will be sent out of the subpopulation.

Parameters:

migration_rate (float) – The migration rate is defined as the expected percentage of population that will migrate at each generation.

Returns:

A list of individuals from the subpopulation.

Return type:

List[Individual]

receive_migrants(giving_subpopulation: Subpopulation, migration_rate: float) → None

Populate the list of incoming migrants with individuals coming from a giving_subpopulation.

Parameters:

• giving_subpopulation (Subpopulation) – Subpopulation from which individuals are migrating.

• migration_rate (float) – Percentage of the giving subpopulation that will migrate at each generation into the current subpopulation.

Returns:

A list of individuals from the giving subpopulation.

Return type:

List[Individual]

shannon_diversity() → float

Calculate the Shannon diversity index in the subpopulation.

Returns:

The current Shannon diversity index in the subpopulation.

Return type:

float

simpson_diversity() → float

Calculate the Simpson diversity index of the subpopulation.

Returns:

The Simpson diversity index of the subpopulation.

Return type:

float

metapypulation.simulation module

A module containing the tools to simulate a metapopulation and output the result in data tables.

class metapypulation.simulation.Simulation(generations: int, number_of_subpopulations: int, migration_matrix: str | ndarray, interaction: str, carrying_capacities: List[int] | int, replicates: int, output_path: str, burn_in: int = 0, migration_rate: float = 0.001, mutation_rate: float = 0.0, measure_timing: int = 100, verbose: bool = True, verbose_timing: int = 10000)

Bases: object

Base class for the simulation of the metapopulation.

generations

Number of generations to simulate.

Type:

int

burn_in

Number of generations without migration in the beginning of the simulation.

Type:

int

number_of_subpopulations

Number of subpopulations in the metapopulation.

Type:

int

interaction_type

Type of interaction between individuals.

Type:

str

carrying_capacities

Initial population size of each subpopulation.

Type:

List[int] | int

replicates

Number of replicates to simulate.

Type:

int

output_path

Path of folder in which to save results.

Type:

str

measure_timing

Number of generations between measurements.

Type:

int

verbose

Whether to print text during the simulation.

Type:

bool

verbose_timing

Number of generations between each print statement.

Type:

int

migration_matrix

Type of migration topology (‘island’ or ‘stepping stone’), or matrix of migrations between demes.

Type:

str | np.ndarray

mutation_rate

Probability of a mutation to occur during copying.

Type:

float

subpop_set_counts

Collects the number of unique set counts per subpopulation averaged over subpopulations.

Type:

pd.DataFrame

subpop_shannon

Collects the Shannon diversity index per subpopulation averaged over subpopulations.

Type:

pd.DataFrame

subpop_simpson

Collects the Simpson diversity index per subpopulation averaged over subpopulations.

Type:

pd.DataFrame

subpop_gini

Collects the Gini diversity index per subpopulation averaged over subpopulations.

Type:

pd.DataFrame

metapop_set_counts

Collects the number of unique set counts over the whole metapopulation.

Type:

pd.DataFrame

metapop_shannon

Collects the Shannon diversity index over the whole metapopulation.

Type:

pd.DataFrame

metapop_simpson

Collects the Simpson diversity index over the whole metapopulation.

Type:

pd.DataFrame

metapop_gini

Collects the Gini diversity index over the whole metapopulation.

Type:

pd.DataFrame

create_migration_table(type_of_model, migration_rate: float) → None

Create a migration table for the number of subpopulations in the case of Island or Stepping Stone model.

Parameters:

• type (str) – type of model. Either “island” or “stepping_stone”

• migration_rate (float) – float between 0 and 1 representing the migration rate for the table.

empty_lists()

run_simulation() → None

Run all the replicates and print some outputs.

run_single_replicate(replicate_id: int) → None

Run one replicate of the simulation.

Parameters:

replicate_id (int) – The number of the current replicate (for the output data columns).

save_output() → None

Save output to input folder.

Module contents