population

population

Defines functions for making the population.

Functions

Name	Description
make_hybrid_contacts	Create “hybrid” contacts – microstructured contacts for households and
make_microstructured_contacts	Create microstructured contacts – i.e. for households.
make_people	Make the actual people for the simulation.
make_random_contacts	Make random static contacts for a single layer as an edgelist.
make_randpop	Make a random population, with contacts.
make_synthpop	Make a population using SynthPops, including contacts.

make_hybrid_contacts

population.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_microstructured_contacts

population.make_microstructured_contacts(pop_size, cluster_size, mapping=None)

Create microstructured contacts – i.e. for households.

Parameters

Name	Type	Description	Default
pop_size	int	total number of people	required
cluster_size	int	the average size of each cluster (Poisson-sampled)	required

New in version 3.1.1: optimized updated arguments.

make_people

population.make_people(
    sim,
    popdict=None,
    die=True,
    reset=False,
    recreate=False,
    verbose=None,
    **kwargs,
)

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

Name	Type	Description	Default
sim (Sim)		the simulation object; population parameters are taken from the sim object	required
popdict (any)		if supplied, use this population dictionary instead of generating a new one; can be a dict, SynthPop, or People object	required
die (bool)		whether or not to fail if synthetic populations are requested but not available	required
reset (bool)		whether to force population creation even if self.popdict/self.people exists	required
recreate (bool)		whether to recreate (re-instantiate) the People object even if already supplied	required
verbose (bool)		level of detail to print	required
kwargs (dict)		passed to make_randpop() or make_synthpop()	required

Returns

Name	Type	Description
people	People	people

make_random_contacts

population.make_random_contacts(
    pop_size,
    n,
    overshoot=1.2,
    dispersion=None,
    mapping=None,
)

Make random static contacts for a single layer as an edgelist.

Parameters

Name	Type	Description	Default
pop_size (int)		number of agents to create contacts between (N)	required
n (int)		the average number of contacts per person for this layer	required
overshoot (float)		to avoid needing to take multiple Poisson draws	required
dispersion (float)		if not None, use a negative binomial distribution with this dispersion parameter instead of Poisson to make the contacts	required
mapping (array)		optionally map the generated indices onto new indices	required

Returns

Name	Type	Description
		Dictionary of two arrays defining UIDs of the edgelist (sources and targets)

New in 3.1.1: optimized and updated arguments.

make_randpop

population.make_randpop(
    pars,
    use_age_data=True,
    use_household_data=True,
    sex_ratio=0.5,
    microstructure='random',
    **kwargs,
)

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

Name	Type	Description	Default
pars	dict	the parameter dictionary or simulation object	required
use_age_data	bool	whether to use location-specific age data	True
use_household_data	bool	whether to use location-specific household size data	True
sex_ratio	float	proportion of the population that is male (not currently used)	0.5
microstructure	bool	whether or not to use the microstructuring algorithm to group contacts	'random'
kwargs	dict	passed to contact creation method (e.g., make_hybrid_contacts)	{}

Returns

Name	Type	Description
popdict	dict	a dictionary representing the population, with the following keys for a population of N agents with M contacts between them:

make_synthpop

population.make_synthpop(
    sim=None,
    popdict=None,
    layer_mapping=None,
    community_contacts=None,
    **kwargs,
)

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

Name	Type	Description	Default
sim	Sim	a Covasim simulation object	None
popdict	dict / Pop / People	a pre-generated SynthPops population (otherwise, create a new one)	None
layer_mapping	dict	a custom mapping from SynthPops layers to Covasim layers	None
community_contacts	int	if a simulation is not supplied, create this many community contacts on average	None
kwargs	dict	passed to sp.make_population()	{}

Example::

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