synthpops.people.people module

Alternate representation of a population as a People object. Originally based on the corresponding Covasim classes and functions.

class FlexPretty[source]

Bases: sciris.sc_utils.prettyobj

A class that supports multiple different display options: namely obj.brief() for a one-line description and obj.disp() for a full description.

New in version 1.10.0.


Print or output verbose representation of the object


Print or output a brief representation of the object

class BasePeople[source]

Bases: synthpops.people.people.FlexPretty

A class to handle all the boilerplate for people – note that as with the BaseSim vs Sim classes, everything interesting happens in the People class, whereas this class exists to handle the less interesting implementation details.

New in version 1.10.0.


Get the keys that have been set


Lock the people object to prevent keys from being added


Unlock the people object to allow keys to be added


Print a summary of the people – same as brief

set(key, value, die=True)[source]

Ensure sizes and dtypes match


Convenience method – key can be string or list of strings


Return indices matching the condition


Return indices not matching the condition


Return indices of people who are not-nan


Return indices of people who are nan


Count the number of people for a given key


Count the number of people who do not have a property for a given key


Re-link the parameters stored in the people object to the sim containing it, and perform some basic validation.


Get the available contact keys – try contacts first, then beta_layer


The indices of each people array

validate(die=True, verbose=False)[source]

Convert to a Pandas dataframe


Return as numpy array


Method to create person from the people


Return all people as a list

from_people(people, resize=True)[source]

Convert a list of people back into a People object


Convert all people to a networkx MultiDiGraph, including all properties of the people (nodes) and contacts (edges).

Parameters:full_output (bool) – if true, return nodes and edges along with the graph object

Initialize the contacts dataframe with the correct columns and data types

add_contacts(contacts, lkey=None, beta=None)[source]

Add new contacts to the array. See also contacts.add_layer().


Parse a list of people with a list of contacts per person and turn it into an edge list.

static remove_duplicates(df)[source]

Sort the dataframe and remove duplicates – note, not extensively tested

class Person(pars=None, uid=None, age=-1, sex=-1, contacts=None)[source]

Bases: sciris.sc_utils.prettyobj

Class for a single person. Note: this is largely deprecated since People is now based on arrays rather than being a list of people.

New in version 1.10.0.

class FlexDict[source]

Bases: dict

A dict that allows more flexible element access: in addition to obj[‘a’], also allow obj[0]. Lightweight implementation of the Sciris odict class.

class Contacts(layer_keys=None)[source]

Bases: synthpops.people.people.FlexDict

A simple (for now) class for storing different contact layers.

New in version 1.10.0.


Small method to add one or more layers to the contacts. Layers should be provided as keyword arguments.


hospitals_layer = cv.Layer(label='hosp')

Remove the layer(s) from the contacts.



Note: while included here for convenience, this operation is equivalent to simply popping the key from the contacts dictionary.


Convert all layers to a networkx MultiDiGraph


import networkx as nx
sim = cv.Sim(pop_size=50, pop_type='hybrid').run()
G = sim.people.contacts.to_graph()
class Layer(label=None, **kwargs)[source]

Bases: synthpops.people.people.FlexDict

A small class holding a single layer of contact edges (connections) between people.

The input is typically three arrays: person 1 of the connection, person 2 of the connection, and the weight of the connection. Connections are undirected; each person is both a source and sink.

This class is usually not invoked directly by the user, but instead is called as part of the population creation.

  • p1 (array) – an array of N connections, representing people on one side of the connection
  • p2 (array) – an array of people on the other side of the connection
  • beta (array) – an array of weights for each connection
  • label (str) – the name of the layer (optional)
  • kwargs (dict) – other keys copied directly into the layer

Note that all arguments (except for label) must be arrays of the same length, although not all have to be supplied at the time of creation (they must all be the same at the time of initialization, though, or else validation will fail).


# Generate an average of 10 contacts for 1000 people
n = 10_000
n_people = 1000
p1 = np.random.randint(n_people, size=n)
p2 = np.random.randint(n_people, size=n)
beta = np.ones(n)
layer = cv.Layer(p1=p1, p2=p2, beta=beta, label='rand')

# Convert one layer to another with extra columns
index = np.arange(n)
self_conn = p1 == p2
layer2 = cv.Layer(**layer, index=index, self_conn=self_conn, label=layer.label)

New in version 1.10.0.


Return sorted array of all members


Return the keys for the layer’s meta information – i.e., p1, p2, beta


Check the integrity of the layer: right types, right lengths


“Pop” the specified indices from the edgelist and return them as a dict. Returns in the right format to be used with layer.append().

Parameters:inds (int, array, slice) – the indices to be removed

Append contacts to the current layer.

Parameters:contacts (dict) – a dictionary of arrays with keys p1,p2,beta, as returned from layer.pop_inds()

Convert to dataframe

from_df(df, keys=None)[source]

Convert from a dataframe


Convert to a networkx DiGraph


import networkx as nx
sim = cv.Sim(pop_size=20, pop_type='hybrid').run()
G = sim.people.contacts['h'].to_graph()
find_contacts(inds, as_array=True)[source]

Find all contacts of the specified people

For some purposes (e.g. contact tracing) it’s necessary to find all of the contacts associated with a subset of the people in this layer. Since contacts are bidirectional it’s necessary to check both P1 and P2 for the target indices. The return type is a Set so that there is no duplication of indices (otherwise if the Layer has explicit symmetric interactions, they could appear multiple times). This is also for performance so that the calling code doesn’t need to perform its own unique() operation. Note that this cannot be used for cases where multiple connections count differently than a single infection, e.g. exposure risk.

  • inds (array) – indices of people whose contacts to return
  • as_array (bool) – if true, return as sorted array (otherwise, return as unsorted set)

a set of indices for pairing partners

Return type:

contact_inds (array)

Example: If there were a layer with - P1 = [1,2,3,4] - P2 = [2,3,1,4] Then find_contacts([1,3]) would return {1,2,3}

update(people, frac=1.0)[source]

Regenerate contacts on each timestep.

This method gets called if the layer appears in['dynam_lkeys']. The Layer implements the update procedure so that derived classes can customize the update e.g. implementing over-dispersion/other distributions, random clusters, etc.

Typically, this method also takes in the people object so that the update can depend on person attributes that may change over time (e.g. changing contacts for people that are severe/critical).

Parameters:frac (float) – the fraction of contacts to update on each timestep
class People(pars, strict=False, **kwargs)[source]

Bases: synthpops.people.people.BasePeople

A class to perform all the operations on the people. This class is usually not invoked directly, but instead is created automatically by the sim. The only required input argument is the population size, but typically the full parameters dictionary will get passed instead since it will be needed before the People object is initialized.

Note that this class handles the mechanics of updating the actual people, while BasePeople takes care of housekeeping (saving, loading, exporting, etc.). Please see the BasePeople class for additional methods.

  • pars (dict) – the sim parameters, e.g. – alternatively, if a number, interpreted as pop_size
  • strict (bool) – whether or not to only create keys that are already in self.meta.person; otherwise, let any key be set
  • kwargs (dict) – the actual data, e.g. from a popdict, being specified


ppl1 = cv.People(2000)

sim = cv.Sim()
ppl2 = cv.People(

New in version 1.10.0.

plot(bins=None, width=1.0, alpha=0.6, fig_args=None, axis_args=None, plot_args=None, do_show=None, fig=None)[source]

Plot statistics of the population – age distribution, numbers of contacts, and overall weight of contacts (number of contacts multiplied by beta per layer).

  • bins (arr) – age bins to use (default, 0-100 in one-year bins)
  • width (float) – bar width
  • font_size (float) – size of font
  • alpha (float) – transparency of the plots
  • fig_args (dict) – passed to pl.figure()
  • axis_args (dict) – passed to pl.subplots_adjust()
  • plot_args (dict) – passed to pl.plot()
  • do_show (bool) – whether to show the plot
  • fig (fig) – handle of existing figure to plot into

Convert to networkx and draw. WARNING: extremely slow for more than ~100 people!


pop = sp.Pop(n=50)
story(uid, *args)[source]

Print out a short history of events in the life of the specified individual.

  • uid (int/list) – the person or people whose story is being regaled
  • args (list) – these people will tell their stories too


sim = cv.Sim(pop_type='hybrid', verbose=0)