Options

class Options

Bases: objdict

Set options for Covasim. Note: use the class instance cv.options to set options, not the class itself (cv.Options).

Use cv.options.set('defaults') to reset all values to default, or cv.options.set(dpi='default') to reset one parameter to default. See cv.options.help(detailed=True) for more information.

Options can also be saved and loaded using cv.options.save() and cv.options.load(). See cv.options.context() and cv.options.with_style() to set options temporarily.

Common options are (see also cv.options.help(detailed=True)):

• verbose: default verbosity for simulations to use

• style: the plotting style to use

• dpi: the overall DPI (i.e. size) of the figures

• font: the font family/face used for the plots

• fontsize: the font size used for the plots

• interactive: convenience method to set show, close, and backend

• jupyter: defaults for Jupyter (change backend and figure return)

• show: whether to show figures

• close: whether to close the figures

• backend: which Matplotlib backend to use

• warnings: how to handle warnings (e.g. print, raise as errors, ignore)

Examples:

cv.options(dpi=150) # Larger size
cv.options(style='simple', font='Rosario') # Change to the "simple" Covasim style with a custom font
cv.options.set(fontsize=18, show=False, backend='agg', precision=64) # Multiple changes
cv.options(interactive=False) # Turn off interactive plots
cv.options(jupyter=True) # Defaults for Jupyter
cv.options('defaults') # Reset to default options

New in version 3.1.1: Jupyter defaults

New in version 3.1.2: Updated plotting styles; refactored options as a class

Methods

__call__(*args, **kwargs)

Allow cv.options(dpi=150) instead of cv.options.set(dpi=150)

to_dict()

Pull out only the settings from the options object

disp()

Detailed representation

static get_orig_options()

Set the default options for Covasim – not to be called by the user, use cv.options.set('defaults') instead.

set(key=None, value=None, use=False, **kwargs)

Actually change the style. See cv.options.help() for more information.

Parameters:

• key (str) – the parameter to modify, or ‘defaults’ to reset everything to default values

• value (varies) – the value to specify; use None or ‘default’ to reset to default

• use (bool) – whether to immediately apply the change (to Matplotlib)

• kwargs (dict) – if supplied, set multiple key-value pairs

Example:

cv.options.set(dpi=50) # Equivalent to cv.options(dpi=50)

set_matplotlib_global(key, value)

Set a global option for Matplotlib – not for users

context(**kwargs)

Alias to set() for non-plotting options, for use in a “with” block.

Note: for plotting options, use cv.options.with_style(), which is linked to Matplotlib’s context manager. If you set plotting options with this, they won’t have any effect.

Examples:

# Silence all output
with cv.options.context(verbose=0):
    cv.Sim().run()

# Convert warnings to errors
with cv.options.context(warnings='error'):
    cv.Sim(location='not a location').initialize()

# Use with_style(), not context(), for plotting options
with cv.options.with_style(dpi=50):
    cv.Sim().run().plot()

New in version 3.1.2.

get_default(key)

Helper function to get the original default options

changed(key)

Check if current setting has been changed from default

help(detailed=False, output=False)

Print information about options.

Parameters:

• detailed (bool) – whether to print out full help

• output (bool) – whether to return a list of the options

Example:

cv.options.help(detailed=True)

load(filename, verbose=True, **kwargs)

Load current settings from a JSON file.

Parameters:

• filename (str) – file to load

• kwargs (dict) – passed to sc.loadjson()

save(filename, verbose=True, **kwargs)

Save current settings as a JSON file.

Parameters:

• filename (str) – file to save to

• kwargs (dict) – passed to sc.savejson()

with_style(style_args=None, use=False, **kwargs)

Combine all Matplotlib style information, and either apply it directly or create a style context.

To set globally, use cv.options.use_style(). Otherwise, use cv.options.with_style() as part of a with block to set the style just for that block (using this function outsde of a with block and with use=False has no effect, so don’t do that!). To set non-style options (e.g. warnings, verbosity) as a context, see cv.options.context().

Parameters:

• style_args (dict) – a dictionary of style arguments

• use (bool) – whether to set as the global style; else, treat as context for use with “with” (default)

• kwargs (dict) – additional style arguments

Valid style arguments are:

• dpi: the figure DPI

• font: font (typeface)

• fontsize: font size

• grid: whether or not to plot gridlines

• facecolor: color of the axes behind the plot

• any of the entries in pl.rParams

Examples:

with cv.options.with_style(dpi=300): # Use default options, but higher DPI
    pl.plot([1,3,6])

use_style(**kwargs)

Shortcut to set Covasim’s current style as the global default.

Example:

cv.options.use_style() # Set Covasim options as default
pl.figure()
pl.plot([1,3,7])

pl.style.use('seaborn-whitegrid') # to something else
pl.figure()
pl.plot([3,1,4])