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	Get current git information and optionally write it to disk. The expected
compute_gof	Calculate the goodness of fit. By default use normalized absolute error, but
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 hpv.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 HPVsim in general, or search for a word/expression.
load	Convenience method for sc.loadobj() and equivalent to hpv.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 hpv.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 HPVsim 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::

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

check_version

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

Get current git information and optionally write it to disk. 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

Example::

hpv.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 True

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=False) # 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

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).

Examples::

hpv.get_doubling_time(sim, interval=[3,30]) # returns the doubling time over the given interval (single float)
hpv.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 hpv.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::

hpv.Sim().run(do_plot=True)
hpv.savefig('hpvsim.png')
hpv.get_png_metadata('hpvsim.png')

get_version_pars

misc.get_version_pars(version, verbose=True)

Function for loading parameters from the specified version.

Parameters will be loaded for HPVsim ‘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 HPVsim 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 hpv.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::

hpv.git_info() # Return information
hpv.git_info(__file__) # Writes to disk
hpv.git_info('hpvsim_version.gitinfo') # Writes to disk
hpv.git_info('hpvsim_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 HPVsim 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::

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

New in version 3.1.2.

load

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

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

Parameters

Name	Type	Description	Default
filename	str	file to load	required
do_migrate	bool	whether to migrate if loading an old object	required
update	bool	whether to modify the object to reflect the new version	True
verbose	bool	whether to print migration information	True
args	list	passed to sc.loadobj()	()
kwargs	dict	passed to sc.loadobj()	{}

Returns

Name	Type	Description
		Loaded object

Examples::

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

load_data

misc.load_data(
    datafile,
    check_date=False,
    header='infer',
    calculate=True,
    **kwargs,
)

Load data for comparing to the model output, either from file or from a dataframe. Data is expected to be in wide format, with each row representing a year and columns for each variable by genotype/age/sex.

Parameters

Name	Type	Description	Default
datafile	str / df	if a string, the name of the file to load (either Excel or CSV); if a dataframe, use directly	required
start_year	int	first year with data available	required
kwargs	dict	passed to pd.read_excel()	{}

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 hpv.Sim.save() or hpv.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::

hpv.save('calib.sim', sim) # Equivalent to sim.save('calib.sim')
hpv.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 HPVsim metadata in the figure.

By default, saves (git) information from both the HPVsim version and the calling function. Additional comments can be added to the saved file as well. These can be retrieved via hpv.get_png_metadata() (or sciris.sc_plotting.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()	{}

Example::

hpv.Sim().run().plot()
hpv.savefig()