settings

settings

Define options for Covasim, mostly plotting and Numba options. All options should be set using set() or directly, e.g.::

cv.options(font_size=18)

To reset default options, use::

cv.options('default')

Note: “options” is used to refer to the choices available (e.g., DPI), while “settings” is used to refer to the choices made (e.g., DPI=150).

Classes

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

Options

settings.Options()

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

Name Description
changed Check if current setting has been changed from default
context Alias to set() for non-plotting options, for use in a “with” block.
disp Detailed representation
get_default Helper function to get the original default options
get_orig_options Set the default options for Covasim – not to be called by the user, use
help Print information about options.
load Load current settings from a JSON file.
save Save current settings as a JSON file.
set Actually change the style. See cv.options.help() for more information.
set_matplotlib_global Set a global option for Matplotlib – not for users
to_dict Pull out only the settings from the options object
use_style Shortcut to set Covasim’s current style as the global default.
with_style Combine all Matplotlib style information, and either apply it directly
changed
settings.Options.changed(key)

Check if current setting has been changed from default

context
settings.Options.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.

disp
settings.Options.disp()

Detailed representation

get_default
settings.Options.get_default(key)

Helper function to get the original default options

get_orig_options
settings.Options.get_orig_options()

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

help
settings.Options.help(detailed=False, output=False)

Print information about options.

Parameters
Name Type Description Default
detailed bool whether to print out full help False
output bool whether to return a list of the options False

Example::

cv.options.help(detailed=True)
load
settings.Options.load(filename, verbose=True, **kwargs)

Load current settings from a JSON file.

Parameters
Name Type Description Default
filename str file to load required
kwargs dict passed to sc.loadjson() {}
save
settings.Options.save(filename, verbose=True, **kwargs)

Save current settings as a JSON file.

Parameters
Name Type Description Default
filename str file to save to required
kwargs dict passed to sc.savejson() {}
set
settings.Options.set(key=None, value=None, use=False, **kwargs)

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

Parameters
Name Type Description Default
key str the parameter to modify, or ‘defaults’ to reset everything to default values None
value varies the value to specify; use None or ‘default’ to reset to default None
use bool whether to immediately apply the change (to Matplotlib) False
kwargs dict if supplied, set multiple key-value pairs {}

Example::

cv.options.set(dpi=50) # Equivalent to cv.options(dpi=50)
set_matplotlib_global
settings.Options.set_matplotlib_global(key, value)

Set a global option for Matplotlib – not for users

to_dict
settings.Options.to_dict()

Pull out only the settings from the options object

use_style
settings.Options.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])
with_style
settings.Options.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
Name Type Description Default
style_args dict a dictionary of style arguments None
use bool whether to set as the global style; else, treat as context for use with “with” (default) False
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])