poliosim.population module

Defines functions for making the population.

make_people(sim, save_pop=False, popfile=None, die=True, reset=False, verbose=None, **kwargs)

Make the actual people for the simulation. Usually called via sim.initialize(), not directly by the user.

Parameters

• sim (Sim) – the simulation object

• save_pop (bool) – whether to save the population to disk

• popfile (bool) – if so, the filename to save to

• die (bool) – whether or not to fail if synthetic populations are requested but not available

• reset (bool) – whether to force population creation even if self.popdict/self.people exists

• verbose (bool) – level of detail to print

• kwargs (dict) – passed to make_randpop() or make_synthpop()

Returns

people

Return type

people (People)

make_randpop(sim, use_age_data=True, use_household_data=True, sex_ratio=0.5, microstructure=False)

Make a random population, with contacts.

This function returns a “popdict” dictionary, which has the following (required) keys:

• uid: an array of (usually consecutive) integers of length N, uniquely identifying each agent

• age: an array of floats of length N, the age in years of each agent

• sex: an array of integers of length N (not currently used, so does not have to be binary)

• contacts: list of length N listing the contacts; see make_random_contacts() for details

• layer_keys: a list of strings representing the different contact layers in the population; see make_random_contacts() for details

Parameters

• sim (Sim) – the simulation object

• use_age_data (bool) – whether to use location-specific age data

• use_household_data (bool) – whether to use location-specific household size data

• sex_ratio (float) – proportion of the population that is male (not currently used)

• microstructure (bool) – whether or not to use the microstructuring algorithm to group contacts

Returns

a dictionary representing the population, with the following keys for a population of N agents with M contacts between them:

Return type

popdict (dict)

make_random_contacts(pop_size, contacts, overshoot=1.2, dispersion=None)

Make random static contacts.

Parameters

• pop_size (int) – number of agents to create contacts between (N)

• contacts (dict) – a dictionary with one entry per layer describing the average number of contacts per person for that layer

• overshoot (float) – to avoid needing to take multiple Poisson draws

• dispersion (float) – if not None, use a negative binomial distribution with this dispersion parameter instead of Poisson to make the contacts

Returns

a list of length N, where each entry is a dictionary by layer, and each dictionary entry is the UIDs of the agent’s contacts layer_keys (list): a list of layer keys, which is the same as the keys of the input “contacts” dictionary

Return type

contacts_list (list)

make_microstructured_contacts(pop_size, contacts)

Create microstructured contacts – i.e. for households

make_hybrid_contacts(pop_size, ages, contacts, school_ages=None, work_ages=None)

Create “hybrid” contacts – microstructured contacts for households and random contacts for schools and workplaces, both of which have extremely basic age structure. A combination of both make_random_contacts() and make_microstructured_contacts().

make_hybrid_contacts_mixed_community(pop_size, ages, contacts, school_ages=None, work_ages=None, mix_matrix=None, selectors=None)

Same as make_hybrid_contacts, but the community layer is replaced.

The contacts in the community layer are determined by the mix_matrix and the list of selectors. The mix matrix is an M rows x N columns matrix. Only the upper right triangle of the mix matrix is used, including the diagonal.

For each used entry (i,j) in the mix matrix, the i’th entry in selectors is used to determine the pool of source individuals for each contact, while the j’th entry in selectors is used to determine the pool of target individuals for each contact. Then each source individual is assigned on average mix_matrix(i,j) number of contacts from the target pool.

make_synthpop(sim, generate=True, layer_mapping=None, **kwargs)

Make a population using SynthPops, including contacts. Usually called automatically, but can also be called manually.

Parameters

• sim (Sim) – a Poliosim simulation object

• generate (bool) – whether or not to generate a new population (otherwise, tries to load a pre-generated one)

• layer_mapping (dict) – a custom mapping from SynthPops layers to Poliosim layers

• kwars (dict) – passed to sp.make_population()

Example:

sim = ps.Sim(pop_type='synthpops')
sim.popdict = ps.make_synthpop(sim)
sim.run()