Options#

class Options[source]#

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)[source]#

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

to_dict()[source]#

Pull out only the settings from the options object

disp()[source]#

Detailed representation

static get_orig_options()[source]#

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)[source]#

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)[source]#

Set a global option for Matplotlib – not for users

context(**kwargs)[source]#

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)[source]#

Helper function to get the original default options

changed(key)[source]#

Check if current setting has been changed from default

help(detailed=False, output=False)[source]#

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)[source]#

Load current settings from a JSON file.

Parameters:

  • filename (str) – file to load

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

save(filename, verbose=True, **kwargs)[source]#

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)[source]#

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)[source]#

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