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)

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

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 = None, carrying_capacities: List[int] | int = 100, number_of_features: int = 5, number_of_traits: 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

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

make_interact() → None

Make one interaction in each subpopulation.

metapopulation_shannon_diversity() → float

Calculates Shannon diversity trait over the whole metapopulation.

Returns:

Shannon diversity index of the metapopulation.

Return type:

float

metapopulation_test_sets() → int

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

Returns:

number of unique sets in the metapopulation.

Return type:

int

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]

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]

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_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

incorporate_migrants_in_population() → None

Merges incoming migrants into the local population.

is_trait_in_subpopulation(trait: int, feature: int | None = 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]

return_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

shannon_diversity() → float

Calculate the Shannon diversity index in the subpopulation.

Returns:

The current Shannon diversity index in 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, 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.

Type:

str | np.ndarray

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

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

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