egttools.numerical.numerical_.calculate_hypergeometric_expected_value

calculate_hypergeometric_expected_value()

Compute E[f | state] = sum_g P(g | state) * f(g) for a single population state.

Calculates the expected value of a function f over all group configurations g, weighted by the multivariate hypergeometric probability P(g | state) that a randomly sampled group of group_size individuals from a population in state has composition g.

This is the inner loop used by fitness calculations in N-player games. Exposing it here lets users write custom game fitness functions in Python without reimplementing the hypergeometric weighting.

Parameters:

  • pop_size (int) – Total number of individuals in the population.

  • group_size (int) – Number of individuals sampled per group interaction.

  • nb_strategies (int) – Number of distinct strategies.

  • state (numpy.ndarray) – Integer array of length nb_strategies with counts of each strategy in the population. Must sum to pop_size.

  • f_values (numpy.ndarray) – Float array of length calculate_nb_states(group_size, nb_strategies) where f_values[g] is the value of f for the group configuration sample_simplex(g, group_size, nb_strategies).

Returns:

Expected value of f given the population state.

Return type:

float

Examples

>>> import numpy as np
>>> import egttools as egt
>>> pop_size, group_size, nb_strategies = 10, 3, 2
>>> state = np.array([6, 4], dtype=np.uint64)
>>> nb_configs = egt.calculate_nb_states(group_size, nb_strategies)
>>> # Cooperation level: fraction of cooperators (strategy 0) in the group
>>> f_values = np.array([
...     egt.sample_simplex(g, group_size, nb_strategies)[0] / group_size
...     for g in range(nb_configs)
... ])
>>> egt.calculate_hypergeometric_expected_value(pop_size, group_size, nb_strategies, state, f_values)