misc

misc

Miscellaneous functions that do not belong anywhere else

Functions

Name	Description
check_save_version	A convenience function that bundles check_version with git_info and saves
check_version	Check the installed version of Covasim against an expected version. The expected
compute_gof	Calculate the goodness of fit. By default use normalized absolute error, but
diff_sims	Compute the difference of the summaries of two simulations, and print any
get_doubling_time	Alternate method to calculate doubling time (one is already implemented in
get_png_metadata	Read metadata from a PNG file. For use with images saved with cv.savefig().
get_version_pars	Function for loading parameters from the specified version.
git_info	Get current git information and optionally write it to disk. Simplest usage
help	Get help on Covasim in general, or search for a word/expression.
load	Convenience method for sc.loadobj() and equivalent to cv.Sim.load() or
load_data	Load data for comparing to the model output, either from file or from a dataframe.
save	Convenience method for sc.saveobj() and equivalent to cv.Sim.save() or
savefig	Wrapper for Matplotlib’s pl.savefig() function which automatically stores

check_save_version

misc.check_save_version(
    expected=None,
    filename=None,
    die=False,
    verbose=True,
    **kwargs,
)

A convenience function that bundles check_version with git_info and saves automatically to disk from the calling file. The idea is to put this at the top of an analysis script, and commit the resulting file, to keep track of which version of Covasim was used.

Parameters

Name	Type	Description	Default
expected	str	expected version information	None
filename	str	file to save to; if None, guess based on current file name	None
kwargs	dict	passed to git_info(), and thence to sc.savejson()	{}

Examples::

cv.check_save_version()
cv.check_save_version('1.3.2', filename='script.gitinfo', comments='This is the main analysis script')
cv.check_save_version('1.7.2', folder='gitinfo', comments={'SynthPops':sc.gitinfo(sp.__file__)})

check_version

misc.check_version(expected, die=False, verbose=True)

Check the installed version of Covasim against an expected version. The expected version string may optionally start with ‘>=’ or ‘<=’ (== is implied otherwise), but other operators (e.g. ~=) are not supported. Note that e.g. ‘>’ is interpreted to mean ‘>=’.

Parameters

Name	Type	Description	Default
expected	str	expected version information	required
die	bool	whether or not to raise an exception if the check fails	False
verbose	bool	whether to print a note if the versions differ	True

Returns

Name	Type	Description
		-1 if the installed version is older than expected, 0 if it is the same, and 1 if it is newer

Example::

cv.check_version('>=1.7.0', die=True) # Will raise an exception if an older version is used

compute_gof

misc.compute_gof(
    actual,
    predicted,
    normalize=True,
    use_frac=False,
    use_squared=False,
    as_scalar='none',
    eps=1e-09,
    skestimator=None,
    estimator=None,
    **kwargs,
)

Calculate the goodness of fit. By default use normalized absolute error, but highly customizable. For example, mean squared error is equivalent to setting normalize=False, use_squared=True, as_scalar=‘mean’.

Parameters

Name	Type	Description	Default
actual	arr	array of actual (data) points	required
predicted	arr	corresponding array of predicted (model) points	required
normalize	bool	whether to divide the values by the largest value in either series	True
use_frac	bool	convert to fractional mismatches rather than absolute	False
use_squared	bool	square the mismatches	False
as_scalar	str	return as a scalar instead of a time series: choices are sum, mean, median	'none'
eps	float	to avoid divide-by-zero	1e-09
skestimator	str	if provided, use this scikit-learn estimator instead	None
estimator	func	if provided, use this custom estimator instead	None
kwargs	dict	passed to the scikit-learn or custom estimator	{}

Returns

Name	Type	Description
gofs	arr	array of goodness-of-fit values, or a single value if as_scalar is ‘sum’, ‘mean’, or ‘median’

Examples::

x1 = np.cumsum(np.random.random(100))
x2 = np.cumsum(np.random.random(100))

e1 = compute_gof(x1, x2) # Default, normalized absolute error
e2 = compute_gof(x1, x2, normalize=False, use_frac=True) # Fractional error
e3 = compute_gof(x1, x2, normalize=False, use_squared=True, as_scalar='mean') # Mean squared error
e4 = compute_gof(x1, x2, skestimator='mean_squared_error') # Scikit-learn's MSE method
e5 = compute_gof(x1, x2, as_scalar='median') # Normalized median absolute error -- highly robust

diff_sims

misc.diff_sims(
    sim1,
    sim2,
    skip_key_diffs=False,
    skip=None,
    output=False,
    die=False,
    verbose=True,
    atol=1e-09,
    rtol=0,
)

Compute the difference of the summaries of two simulations, and print any values which differ, as a table with the difference, the ratio, and the direction of the change (↑, ↓, or ≈ for a change of less than 0.1%).

Parameters

Name	Type	Description	Default
sim1	Sim / dict	either a run simulation or its sim.summary dictionary	required
sim2	Sim / dict	ditto	required
skip_key_diffs	bool	whether to skip keys that don’t match between sims	False
skip	list	a list of keys to skip	None
output	bool	whether to return the differences as a string (otherwise print)	False
die	bool	whether to raise an exception if the sims don’t match	False
verbose	bool	whether to print “Sims match” if they do (and output=False)	True
atol	float	the absolute tolerance for values to count as equal (default 1e-9)	1e-09
rtol	float	the relative tolerance for values to count as equal (default 0)	0

Returns

Name	Type	Description
		If output=True, a string describing the differences (empty if the sims match)

Example::

s1 = cv.Sim(beta=0.01)
s2 = cv.Sim(beta=0.02)
s1.run()
s2.run()
cv.diff_sims(s1, s2)

get_doubling_time

misc.get_doubling_time(
    sim,
    series=None,
    interval=None,
    start_day=None,
    end_day=None,
    moving_window=None,
    exp_approx=False,
    max_doubling_time=100,
    eps=0.001,
    verbose=None,
)

Alternate method to calculate doubling time (one is already implemented in the sim object). By default, the doubling time is calculated over the whole series.

Examples::

cv.get_doubling_time(sim, interval=[3,30]) # returns the doubling time over the given interval (single float)
cv.get_doubling_time(sim, interval=[3,30], moving_window=3) # returns doubling times calculated over moving windows (array)

get_png_metadata

misc.get_png_metadata(filename, output=False)

Read metadata from a PNG file. For use with images saved with cv.savefig(). Requires pillow, an optional dependency. Metadata retrieval for PDF and SVG is not currently supported.

Parameters

Name	Type	Description	Default
filename	str	the name of the file to load the data from	required

Example::

cv.Sim().run(do_plot=True)
cv.savefig('covasim.png')
cv.get_png_metadata('covasim.png')

get_version_pars

misc.get_version_pars(version, verbose=True)

Function for loading parameters from the specified version.

Parameters will be loaded for Covasim ‘as at’ the requested version i.e. the most recent set of parameters that is <= the requested version. Available parameter values are stored in the regression folder. If parameters are available for versions 1.3, and 1.4, then this function will return the following

• If parameters for version ‘1.3’ are requested, parameters will be returned from ‘1.3’
• If parameters for version ‘1.3.5’ are requested, parameters will be returned from ‘1.3’, since Covasim at version 1.3.5 would have been using the parameters defined at version 1.3.
• If parameters for version ‘1.4’ are requested, parameters will be returned from ‘1.4’

Parameters

Name	Type	Description	Default
version	str	the version to load parameters from	required

Returns

Name	Type	Description
		Dictionary of parameters from that version

git_info

misc.git_info(
    filename=None,
    check=False,
    comments=None,
    old_info=None,
    die=False,
    indent=2,
    verbose=True,
    frame=2,
    **kwargs,
)

Get current git information and optionally write it to disk. Simplest usage is cv.git_info(file)

Parameters

Name	Type	Description	Default
filename	str	name of the file to write to or read from	None
check	bool	whether or not to compare two git versions	False
comments	dict	additional comments to include in the file	None
old_info	dict	dictionary of information to check against	None
die	bool	whether or not to raise an exception if the check fails	False
indent	int	how many indents to use when writing the file to disk	2
verbose	bool	detail to print	True
frame	int	how many frames back to look for caller info	2
kwargs	dict	passed to sc.loadjson() (if check=True) or sc.savejson() (if check=False)	{}

Examples::

cv.git_info() # Return information
cv.git_info(__file__) # Writes to disk
cv.git_info('covasim_version.gitinfo') # Writes to disk
cv.git_info('covasim_version.gitinfo', check=True) # Checks that current version matches saved file

help

misc.help(
    pattern=None,
    source=False,
    ignorecase=True,
    flags=None,
    context=False,
    output=False,
)

Get help on Covasim in general, or search for a word/expression.

Parameters

Name	Type	Description	Default
pattern	str	the word, phrase, or regex to search for	None
source	bool	whether to search source code instead of docstrings for matches	False
ignorecase	bool	whether to ignore case (equivalent to flags=re.I)	True
flags	list	additional flags to pass to re.findall()	None
context	bool	whether to show the line(s) of matches	False
output	bool	whether to return the dictionary of matches	False

Examples::

cv.help()
cv.help('vaccine')
cv.help('contact', ignorecase=False, context=True)
cv.help('lognormal', source=True, context=True)

New in version 3.1.2.

load

misc.load(*args, do_migrate=True, update=True, verbose=True, **kwargs)

Convenience method for sc.loadobj() and equivalent to cv.Sim.load() or cv.Scenarios.load().

Parameters

Name	Type	Description	Default
do_migrate	bool	ignored (v3 objects cannot be migrated to v4); kept for backwards compatibility	True
update	bool	ignored; kept for backwards compatibility	True
verbose	bool	whether to print a note when loading an object from an older version	True
args	list	passed to sc.loadobj(), e.g. the filename	()
kwargs	dict	passed to sc.loadobj(), e.g. filename and folder	{}

Returns

Name	Type	Description
		Loaded object

Examples::

sim = cv.load('calib.sim') # Equivalent to cv.Sim.load('calib.sim')
scens = cv.load(filename='school-closures.scens', folder='schools')

load_data

misc.load_data(
    datafile,
    calculate=True,
    check_date=True,
    verbose=True,
    start_day=None,
    **kwargs,
)

Load data for comparing to the model output, either from file or from a dataframe.

Parameters

Name	Type	Description	Default
datafile	str or df	if a string, the name of the file to load (either Excel or CSV); if a dataframe, use directly	required
calculate	bool	whether to calculate cumulative values from daily counts	True
check_date	bool	whether to check that a ‘date’ column is present	True
verbose	bool	whether to print the cumulative columns that are added	True
start_day	date	if the ‘date’ column is provided as integer number of days, consider them relative to this	None
kwargs	dict	passed to the pandas reader (pd.read_csv(), pd.read_excel(), or pd.read_json())	{}

Returns

Name	Type	Description
data	dataframe	pandas dataframe of the loaded data

save

misc.save(*args, **kwargs)

Convenience method for sc.saveobj() and equivalent to cv.Sim.save() or cv.Scenarios.save().

Parameters

Name	Type	Description	Default
filename	str	file to save to	required
obj	object	object to save	required
args	list	passed to sc.saveobj()	()
kwargs	dict	passed to sc.saveobj()	{}

Returns

Name	Type	Description
		Filename the object is saved to

Examples::

cv.save('calib.sim', sim) # Equivalent to sim.save('calib.sim')
cv.save(filename='school-closures.scens', folder='schools', obj=scens)

savefig

misc.savefig(filename=None, comments=None, fig=None, **kwargs)

Wrapper for Matplotlib’s pl.savefig() function which automatically stores Covasim metadata in the figure.

By default, saves (git) information from both the Covasim version and the calling function. Additional comments can be added to the saved file as well. These can be retrieved via cv.get_png_metadata() (or sc.loadmetadata). Metadata can also be stored for PDF, but cannot be automatically retrieved.

Parameters

Name	Type	Description	Default
filename	str / list	name of the file to save to (default, timestamp); can also be a list of names	None
comments	str / dict	additional metadata to save to the figure	None
fig	fig / list	figure to save (by default, current one); can also be a list of figures	None
kwargs	dict	passed to fig.savefig(); a metadata dict is stored along with the Covasim metadata	{}

Example::

cv.Sim().run().plot()
cv.savefig()