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 call cv.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()