base

base

Base classes for Covasim. These classes handle a lot of the boilerplate of the People and Sim classes (e.g. loading, saving, key lookups, etc.), so those classes can be focused on the disease-specific functionality.

Classes

Name	Description
BasePeople	A class to handle all the boilerplate for people – note that as with the
BaseSim	The BaseSim class stores various methods useful for the Sim that are not directly
Contacts	A simple (for now) class for storing different contact layers.
FlexDict	A dict that allows more flexible element access: in addition to obj[‘a’],
Layer	A small class holding a single layer of contact edges (connections) between people.
ParsObj	A class based around performing operations on a self.pars dict.
Person	Class for a single person. Note: this is largely deprecated since sim.people
Result	Stores a single result – by default, acts like an array.

BasePeople

base.BasePeople()

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.

Methods

Name	Description
add_contacts	Add new contacts to the array. See also contacts.add_layer().
count	Count the number of people for a given key
count_by_variant	Count the number of people for a given key
count_not	Count the number of people who do not have a property for a given key
date_keys	Returns keys for different event dates (e.g., date a person became symptomatic)
defined	Return indices of people who are not-nan
dur_keys	Returns keys for different durations (e.g., the duration from exposed to infectious)
false	Return indices not matching the condition
from_list	Convert a list of people back into a People object
get	Convenience method – key can be string or list of strings
indices	The indices of each people array
init_contacts	Initialize the contacts dataframe with the correct columns and data types
keys	Returns keys for all properties of the people object
layer_keys	Get the available contact keys – try contacts first, then beta_layer
load	Load from disk from a gzipped pickle.
lock	Lock the people object to prevent keys from being added
make_edgelist	Parse a list of people with a list of contacts per person and turn it
person	Method to create person from the people
person_keys	Returns keys specific to a person (e.g., their age)
remove_duplicates	Sort the dataframe and remove duplicates – note, not extensively tested
save	Save to disk as a gzipped pickle.
set	Ensure sizes and dtypes match
set_pars	Re-link the parameters stored in the people object to the sim containing it,
state_keys	Returns keys for different states of a person (e.g., symptomatic)
summarize	Print a summary of the people – same as brief
to_arr	Return as numpy array
to_df	Convert to a Pandas dataframe
to_graph	Convert all people to a networkx MultiDiGraph, including all properties of
to_list	Return all people as a list
true	Return indices matching the condition
undefined	Return indices of people who are nan
unlock	Unlock the people object to allow keys to be added
validate	Perform validation on the People object.

add_contacts

base.BasePeople.add_contacts(contacts, lkey=None, beta=None)

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

count

base.BasePeople.count(key)

Count the number of people for a given key

count_by_variant

base.BasePeople.count_by_variant(key, variant)

Count the number of people for a given key

count_not

base.BasePeople.count_not(key)

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

date_keys

base.BasePeople.date_keys()

Returns keys for different event dates (e.g., date a person became symptomatic)

defined

base.BasePeople.defined(key)

Return indices of people who are not-nan

dur_keys

base.BasePeople.dur_keys()

Returns keys for different durations (e.g., the duration from exposed to infectious)

false

base.BasePeople.false(key)

Return indices not matching the condition

from_list

base.BasePeople.from_list(people, resize=True)

Convert a list of people back into a People object

get

base.BasePeople.get(key)

Convenience method – key can be string or list of strings

indices

base.BasePeople.indices()

The indices of each people array

init_contacts

base.BasePeople.init_contacts(reset=False)

Initialize the contacts dataframe with the correct columns and data types

keys

base.BasePeople.keys()

Returns keys for all properties of the people object

layer_keys

base.BasePeople.layer_keys()

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

load

base.BasePeople.load(filename, *args, **kwargs)

Load from disk from a gzipped pickle.

Parameters

Name	Type	Description	Default
filename	str	the name or path of the file to load from	required
args	list	passed to cv.load()	()
kwargs	dict	passed to cv.load()	{}

Returns

Name	Type	Description
people	People	the loaded people object

Example::

people = cv.people.load('my-people.ppl')

lock

base.BasePeople.lock()

Lock the people object to prevent keys from being added

make_edgelist

base.BasePeople.make_edgelist(contacts)

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

person

base.BasePeople.person(ind)

Method to create person from the people

person_keys

base.BasePeople.person_keys()

Returns keys specific to a person (e.g., their age)

remove_duplicates

base.BasePeople.remove_duplicates(df)

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

save

base.BasePeople.save(filename=None, force=False, **kwargs)

Save to disk as a gzipped pickle.

Note: by default this function raises an exception if trying to save a run or partially run People object, since the changes that happen during a run are usually irreversible.

Parameters

Name	Type	Description	Default
filename	str or None	the name or path of the file to save to; if None, uses stored	None
force	bool	whether to allow saving even of a run or partially-run People object	False
kwargs		passed to sc.makefilepath()	{}

Returns

Name	Type	Description
filename	str	the validated absolute path to the saved file

Example::

sim = cv.Sim()
sim.initialize()
sim.people.save() # Saves to a .ppl file

set

base.BasePeople.set(key, value, die=True)

Ensure sizes and dtypes match

set_pars

base.BasePeople.set_pars(pars=None)

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

state_keys

base.BasePeople.state_keys()

Returns keys for different states of a person (e.g., symptomatic)

summarize

base.BasePeople.summarize(output=False)

Print a summary of the people – same as brief

to_arr

base.BasePeople.to_arr()

Return as numpy array

to_df

base.BasePeople.to_df()

Convert to a Pandas dataframe

to_graph

base.BasePeople.to_graph()

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

Example::

import covasim as cv
import networkx as nx
sim = cv.Sim(pop_size=50, pop_type='hybrid', contacts=dict(h=3, s=10, w=10, c=5)).run()
G = sim.people.to_graph()
nodes = G.nodes(data=True)
edges = G.edges(keys=True)
node_colors = [n['age'] for i,n in nodes]
layer_map = dict(h='#37b', s='#e11', w='#4a4', c='#a49')
edge_colors = [layer_map[G[i][j][k]['layer']] for i,j,k in edges]
edge_weights = [G[i][j][k]['beta']*5 for i,j,k in edges]
nx.draw(G, node_color=node_colors, edge_color=edge_colors, width=edge_weights, alpha=0.5)

to_list

base.BasePeople.to_list()

Return all people as a list

true

base.BasePeople.true(key)

Return indices matching the condition

undefined

base.BasePeople.undefined(key)

Return indices of people who are nan

unlock

base.BasePeople.unlock()

Unlock the people object to allow keys to be added

validate

base.BasePeople.validate(sim_pars=None, die=True, verbose=False)

Perform validation on the People object.

Parameters

Name	Type	Description	Default
sim_pars	dict	dictionary of parameters from the sim to ensure they match the current People object	None
die	bool	whether to raise an exception if validation fails	True
verbose	bool	detail to print	False

BaseSim

base.BaseSim(*args, **kwargs)

The BaseSim class stores various methods useful for the Sim that are not directly related to simulating the epidemic. It is not used outside of the Sim object, so the separation of methods into the BaseSim and Sim classes is purely to keep each one of manageable size.

Attributes

Name	Description
datevec	Create a vector of dates
n	Count the number of people – if it fails, assume none
npts	Count the number of time points
scaled_pop_size	Get the total population size, i.e. the number of agents times the scale factor – if it fails, assume none
tvec	Create a time vector

Methods

Name	Description
copy	Returns a deep copy of the sim
date	Convert one or more integer days of simulation time to a date/list of dates –
day	Convert a string, date/datetime object, or int to a day (int).
export_pars	Return parameters for JSON export – see also to_json().
export_results	Convert results to dict – see also to_json().
get_analyzer	Same as get_intervention(), but for analyzers.
get_analyzers	Same as get_interventions(), but for analyzers.
get_intervention	Like get_interventions(), find the matching intervention(s) by label,
get_interventions	Find the matching intervention(s) by label, index, or type. If None, return
load	Load from disk from a gzipped pickle.
result_keys	Get the actual results objects, not other things stored in sim.results.
save	Save to disk as a gzipped pickle.
set_metadata	Set the metadata for the simulation – creation time and filename
set_seed	Set the seed for the random number stream from the stored or supplied value
shrink	“Shrinks” the simulation by removing the people and other memory-intensive
to_df	Export results to a pandas dataframe
to_excel	Export parameters and results as Excel format
to_json	Export results and parameters as JSON.
update_pars	Ensure that metaparameters get used properly before being updated

copy

base.BaseSim.copy()

Returns a deep copy of the sim

date

base.BaseSim.date(ind, *args, dateformat=None, as_date=False)

Convert one or more integer days of simulation time to a date/list of dates – by default returns a string, or returns a datetime Date object if as_date is True. See also cv.date(), which provides a partly overlapping set of date conversion features.

Parameters

Name	Type	Description	Default
ind	int, list, or array	the index day(s) in simulation time (NB: strings and date objects are accepted, and will be passed unchanged)	required
args	list	additional day(s)	()
dateformat	str	the format to return the date in	None
as_date	bool	whether to return as a datetime date instead of a string	False

Returns

Name	Type	Description
dates	str, Date, or list	the date(s) corresponding to the simulation day(s)

Examples::

sim = cv.Sim()
sim.date(34) # Returns '2020-04-04'
sim.date([34, 54]) # Returns ['2020-04-04', '2020-04-24']
sim.date([34, '2020-04-24']) # Returns ['2020-04-04', '2020-04-24']
sim.date(34, 54, as_date=True) # Returns [datetime.date(2020, 4, 4), datetime.date(2020, 4, 24)]

day

base.BaseSim.day(day, *args)

Convert a string, date/datetime object, or int to a day (int).

Parameters

Name	Type	Description	Default
day	str, date, int, or list	convert any of these objects to a day relative to the simulation’s start day	required

Returns

Name	Type	Description
days	int or str	the day(s) in simulation time

Example::

sim.day('2020-04-05') # Returns 35

export_pars

base.BaseSim.export_pars(filename=None, indent=2, *args, **kwargs)

Return parameters for JSON export – see also to_json().

This method is required so that interventions can specify their JSON-friendly representation.

Parameters

Name	Type	Description	Default
filename	str	filename to save to; if None, do not save	None
indent	int	indent (int): if writing to file, how many indents to use per nested level	2
args	list	passed to savejson()	()
kwargs	dict	passed to savejson()	{}

Returns

Name	Type	Description
pardict	dict	a dictionary containing all the parameter values

export_results

base.BaseSim.export_results(
    for_json=True,
    filename=None,
    indent=2,
    *args,
    **kwargs,
)

Convert results to dict – see also to_json().

The results written to Excel must have a regular table shape, whereas for the JSON output, arbitrary data shapes are supported.

Parameters

Name	Type	Description	Default
for_json	bool	if False, only data associated with Result objects will be included in the converted output	True
filename	str	filename to save to; if None, do not save	None
indent	int	indent (int): if writing to file, how many indents to use per nested level	2
args	list	passed to savejson()	()
kwargs	dict	passed to savejson()	{}

Returns

Name	Type	Description
resdict	dict	dictionary representation of the results

get_analyzer

base.BaseSim.get_analyzer(label=None, partial=False, first=False, die=True)

Same as get_intervention(), but for analyzers.

get_analyzers

base.BaseSim.get_analyzers(label=None, partial=False, as_inds=False)

Same as get_interventions(), but for analyzers.

get_intervention

base.BaseSim.get_intervention(label=None, partial=False, first=False, die=True)

Like get_interventions(), find the matching intervention(s) by label, index, or type. If more than one intervention matches, return the last by default. If no label is provided, return the last intervention in the list.

Parameters

Name	Type	Description	Default
label	(str, int, Intervention, list)	the label, index, or type of intervention to get; if a list, iterate over one of those types	None
partial	bool	if true, return partial matches (e.g. ‘beta’ will match all beta interventions)	False
first	bool	if true, return first matching intervention (otherwise, return last)	False
die	bool	whether to raise an exception if no intervention is found	True

Examples::

tp = cv.test_prob(symp_prob=0.1)
cb = cv.change_beta(days=5, changes=0.3, label='NPI')
sim = cv.Sim(interventions=[tp, cb])
cb = sim.get_intervention('NPI')
cb = sim.get_intervention('NP', partial=True)
cb = sim.get_intervention(cv.change_beta)
cb = sim.get_intervention(1)
cb = sim.get_intervention()
tp = sim.get_intervention(first=True)

get_interventions

base.BaseSim.get_interventions(label=None, partial=False, as_inds=False)

Find the matching intervention(s) by label, index, or type. If None, return all interventions. If the label provided is “summary”, then print a summary of the interventions (index, label, type).

Parameters

Name	Type	Description	Default
label	(str, int, Intervention, list)	the label, index, or type of intervention to get; if a list, iterate over one of those types	None
partial	bool	if true, return partial matches (e.g. ‘beta’ will match all beta interventions)	False
as_inds	bool	if true, return matching indices instead of the actual interventions	False

Examples::

tp = cv.test_prob(symp_prob=0.1)
cb1 = cv.change_beta(days=5, changes=0.3, label='NPI')
cb2 = cv.change_beta(days=10, changes=0.3, label='Masks')
sim = cv.Sim(interventions=[tp, cb1, cb2])
cb1, cb2 = sim.get_interventions(cv.change_beta)
tp, cb2 = sim.get_interventions([0,2])
ind = sim.get_interventions(cv.change_beta, as_inds=True) # Returns [1,2]
sim.get_interventions('summary') # Prints a summary

load

base.BaseSim.load(filename, *args, **kwargs)

Load from disk from a gzipped pickle.

Parameters

Name	Type	Description	Default
filename	str	the name or path of the file to load from	required
kwargs		passed to cv.load()	{}

Returns

Name	Type	Description
sim	Sim	the loaded simulation object

Example::

sim = cv.Sim.load('my-simulation.sim')

result_keys

base.BaseSim.result_keys(which='main')

Get the actual results objects, not other things stored in sim.results.

If which is ‘main’, return only the main results keys. If ‘variant’, return only variant keys. If ‘all’, return all keys.

save

base.BaseSim.save(filename=None, keep_people=None, skip_attrs=None, **kwargs)

Save to disk as a gzipped pickle.

Parameters

Name	Type	Description	Default
filename	str or None	the name or path of the file to save to; if None, uses stored	None
kwargs		passed to sc.makefilepath()	{}

Returns

Name	Type	Description
filename	str	the validated absolute path to the saved file

Example::

sim.save() # Saves to a .sim file

set_metadata

base.BaseSim.set_metadata(simfile)

Set the metadata for the simulation – creation time and filename

set_seed

base.BaseSim.set_seed(seed=-1)

Set the seed for the random number stream from the stored or supplied value

Parameters

Name	Type	Description	Default
seed	None or int	if no argument, use current seed; if None, randomize; otherwise, use and store supplied seed	-1

shrink

base.BaseSim.shrink(skip_attrs=None, in_place=True)

“Shrinks” the simulation by removing the people and other memory-intensive attributes (e.g., some interventions and analyzers), and returns a copy of the “shrunken” simulation. Used to reduce the memory required for RAM or for saved files.

Parameters

Name	Type	Description	Default
skip_attrs	list	a list of attributes to skip (remove) in order to perform the shrinking; default “people”	None
in_palce	bool	whether to perform the shrinking in place (default), or return a shrunken copy instead	required

Returns

Name	Type	Description
shrunken	Sim	a Sim object with the listed attributes removed

to_df

base.BaseSim.to_df(date_index=False)

Export results to a pandas dataframe

Parameters

Name	Type	Description	Default
date_index	bool	if True, use the date as the index	False

to_excel

base.BaseSim.to_excel(filename=None, skip_pars=None)

Export parameters and results as Excel format

Parameters

Name	Type	Description	Default
filename	str	if None, return string; else, write to file	None
skip_pars	list	if provided, a custom list parameters to exclude	None

Returns

Name	Type	Description
		An sc.Spreadsheet with an Excel file, or writes the file to disk

to_json

base.BaseSim.to_json(
    filename=None,
    keys=None,
    tostring=False,
    indent=2,
    verbose=False,
    *args,
    **kwargs,
)

Export results and parameters as JSON.

Parameters

Name	Type	Description	Default
filename	str	if None, return string; else, write to file	None
keys	str or list	attributes to write to json (default: results, parameters, and summary)	None
tostring	bool	if not writing to file, whether to write to string (alternative is sanitized dictionary)	False
indent	int	if writing to file, how many indents to use per nested level	2
verbose	bool	detail to print	False
args	list	passed to savejson()	()
kwargs	dict	passed to savejson()	{}

Returns

Name	Type	Description
		A unicode string containing a JSON representation of the results,
		or writes the JSON file to disk

Examples::

json = sim.to_json()
sim.to_json('results.json')
sim.to_json('summary.json', keys='summary')

update_pars

base.BaseSim.update_pars(pars=None, create=False, **kwargs)

Ensure that metaparameters get used properly before being updated

Contacts

base.Contacts(data=None, layer_keys=None, **kwargs)

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

Parameters

Name	Type	Description	Default
data	dict	a dictionary that looks like a Contacts object	None
layer_keys	list	if provided, create an empty Contacts object with these layers	None
kwargs	dict	additional layer(s), merged with data	{}

New in version 3.1.2: swapped order of arguments

Methods

Name	Description
add_layer	Small method to add one or more layers to the contacts. Layers should
pop_layer	Remove the layer(s) from the contacts.
to_graph	Convert all layers to a networkx MultiDiGraph

add_layer

base.Contacts.add_layer(**kwargs)

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

Example::

hospitals_layer = cv.Layer(label='hosp')
sim.people.contacts.add_layer(hospitals=hospitals_layer)

pop_layer

base.Contacts.pop_layer(*args)

Remove the layer(s) from the contacts.

Example::

sim.people.contacts.pop_layer('hospitals')

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

to_graph

base.Contacts.to_graph()

Convert all layers to a networkx MultiDiGraph

Example::

import networkx as nx
sim = cv.Sim(pop_size=50, pop_type='hybrid').run()
G = sim.people.contacts.to_graph()
nx.draw(G)

FlexDict

base.FlexDict()

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

Layer

base.Layer(*args, label=None, **kwargs)

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.

Parameters

Name	Type	Description	Default
p1	array	an array of N connections, representing people on one side of the connection	required
p2	array	an array of people on the other side of the connection	required
beta	array	an array of weights for each connection	required
label	str	the name of the layer (optional)	None
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).

Examples::

# 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')
layer = cv.Layer(dict(p1=p1, p2=p2, beta=beta), label='rand') # Alternate method

# 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 3.1.2: allow a single dictionary input

Attributes

Name	Description
members	Return sorted array of all members

Methods

Name	Description
append	Append contacts to the current layer.
find_contacts	Find all contacts of the specified people
from_df	Convert from a dataframe
meta_keys	Return the keys for the layer’s meta information – i.e., p1, p2, beta
pop_inds	“Pop” the specified indices from the edgelist and return them as a dict.
to_df	Convert to dataframe
to_graph	Convert to a networkx DiGraph
update	Regenerate contacts on each timestep.
validate	Check the integrity of the layer: right types, right lengths.

append

base.Layer.append(contacts)

Append contacts to the current layer.

Parameters

Name	Type	Description	Default
contacts	dict	a dictionary of arrays with keys p1,p2,beta, as returned from layer.pop_inds()	required

find_contacts

base.Layer.find_contacts(inds, as_array=True)

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.

Parameters

Name	Type	Description	Default
inds	array	indices of people whose contacts to return	required
as_array	bool	if true, return as sorted array (otherwise, return as unsorted set)	True

Returns

Name	Type	Description
contact_inds	array	a set of indices for pairing partners

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}

from_df

base.Layer.from_df(df, keys=None)

Convert from a dataframe

meta_keys

base.Layer.meta_keys()

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

pop_inds

base.Layer.pop_inds(inds)

“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

Name	Type	Description	Default
inds	(int, array, slice)	the indices to be removed	required

to_df

base.Layer.to_df()

Convert to dataframe

to_graph

base.Layer.to_graph()

Convert to a networkx DiGraph

Example::

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

update

base.Layer.update(people, frac=1.0)

Regenerate contacts on each timestep.

This method gets called if the layer appears in sim.pars['dynam_layer']. 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

Name	Type	Description	Default
people	People	the Covasim People object, which is usually used to make new contacts	required
frac	float	the fraction of contacts to update on each timestep	1.0

validate

base.Layer.validate(force=True)

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

If dtype is incorrect, try to convert automatically; if length is incorrect, do not.

ParsObj

base.ParsObj(pars)

A class based around performing operations on a self.pars dict.

Methods

Name	Description
update_pars	Update internal dict with new pars.

update_pars

base.ParsObj.update_pars(pars=None, create=False)

Update internal dict with new pars.

Parameters

Name	Type	Description	Default
pars	dict	the parameters to update (if None, do nothing)	None
create	bool	if create is False, then raise a KeyNotFoundError if the key does not already exist	False

Person

base.Person(pars=None, uid=None, age=-1, sex=-1, contacts=None)

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

Result

base.Result(name=None, npts=None, scale=True, color=None, n_variants=0)

Stores a single result – by default, acts like an array.

Parameters

Name	Type	Description	Default
name	str	name of this result, e.g. new_infections	None
npts	int	if values is None, precreate it to be of this length	None
scale	bool	whether or not the value scales by population scale factor	True
color	str / arr	default color for plotting (hex or RGB notation)	None
n_variants	int	the number of variants the result is for (0 for results not by variant)	0

Example::

import covasim as cv
r1 = cv.Result(name='test1', npts=10)
r1[:5] = 20
print(r1.values)