covasim.population module¶
Defines functions for making the population.
-
make_people
(sim, popdict=None, die=True, reset=False, recreate=False, verbose=None, **kwargs)[source]¶ Make the actual people for the simulation.
Usually called via
sim.initialize()
. While in theory this function can be called directly by the user, usually it’s better to callcv.People()
directly.Parameters: - sim (Sim) – the simulation object; population parameters are taken from the sim object
- popdict (any) – if supplied, use this population dictionary instead of generating a new one; can be a dict, SynthPop, or People object
- 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
- recreate (bool) – whether to recreate (re-instantiate) the People object even if already supplied
- verbose (bool) – level of detail to print
- kwargs (dict) – passed to make_randpop() or make_synthpop()
Returns: people
Return type: people (People)
-
make_randpop
(pars, use_age_data=True, use_household_data=True, sex_ratio=0.5, microstructure='random', **kwargs)[source]¶ 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: - pars (dict) – the parameter dictionary or 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
- kwargs (dict) – passed to contact creation method (e.g., make_hybrid_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, n, overshoot=1.2, dispersion=None, mapping=None)[source]¶ Make random static contacts for a single layer as an edgelist.
Parameters: - pop_size (int) – number of agents to create contacts between (N)
- n (int) – the average number of contacts per person for this 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
- mapping (array) – optionally map the generated indices onto new indices
Returns: Dictionary of two arrays defining UIDs of the edgelist (sources and targets)
New in 3.1.1: optimized and updated arguments.
-
make_microstructured_contacts
(pop_size, cluster_size, mapping=None)[source]¶ Create microstructured contacts – i.e. for households.
Parameters: - pop_size (int) – total number of people
- cluster_size (int) – the average size of each cluster (Poisson-sampled)
New in version 3.1.1: optimized updated arguments.
-
make_hybrid_contacts
(pop_size, ages, contacts, school_ages=None, work_ages=None)[source]¶ 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_synthpop
(sim=None, popdict=None, layer_mapping=None, community_contacts=None, **kwargs)[source]¶ Make a population using SynthPops, including contacts.
Usually called automatically, but can also be called manually. Either a simulation object or a population must be supplied; if a population is supplied, transform it into the correct format; otherwise, create the population and then transform it.
Parameters: - sim (Sim) – a Covasim simulation object
- popdict (dict/Pop/People) – a pre-generated SynthPops population (otherwise, create a new one)
- layer_mapping (dict) – a custom mapping from SynthPops layers to Covasim layers
- community_contacts (int) – if a simulation is not supplied, create this many community contacts on average
- kwargs (dict) – passed to sp.make_population()
Example:
sim = cv.Sim(pop_type='synthpops') sim.popdict = cv.make_synthpop(sim) sim.run()