settings

settings

Define options for Starsim. All options should be set using set() or directly, e.g.:

ss.options(verbose=False)

Classes

Name	Description
Options	Set options for Starsim.

Options

settings.Options()

Set options for Starsim.

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

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

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

- verbose:        default verbosity for simulations to use
- warnings:       how to handle warnings (e.g. print, raise as errors, ignore)

Examples:

ss.options(verbose=True) # Set more verbosity
ss.options(warnings='error') # Be more strict about warnings

Attributes

Name	Description
is_jupyter	Check if we’re in an Jupyter environment

Methods

Name	Description
changed	Check if current setting has been changed from default
context	Alias to set(), 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 Starsim – not to be called by the user, use
help	Print information about options.
refresh_references	Many modules copy settings into them for speed; here we refresh those
set	Actually change the style. See ss.options.help() for more information.
set_jupyter	Set Sciris’ Jupyter settings as well
set_precision	Change the arithmetic precision used by Starsim/NumPy
set_style	Change the plotting style
to_dict	Pull out only the settings from the options object

changed

settings.Options.changed(key)

Check if current setting has been changed from default

context

settings.Options.context(**kwargs)

Alias to set(), for use in a “with” block.

Examples:

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

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

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

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 Starsim – not to be called by the user, use ss.options.set('defaults') instead.

help

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

Print information about options.

Parameters

Name	Type	Description	Default
*args	list	if provided, print out detailed help on one or more specific options	()
detailed	bool	whether to print out full help	False
output	bool	whether to return a list of the options	False

Example:

ss.options.help(detailed=True)

refresh_references

settings.Options.refresh_references()

Many modules copy settings into them for speed; here we refresh those

set

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

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

Parameters

Name	Type	Description	Default
key	str	the parameter to modify, or ‘defaults’ to reset everything to default	None
value	varies	the value to specify; use None or ‘default’ to reset to default	None
use	bool	whether to use the chosen style	False
kwargs	dict	if supplied, set multiple key-value pairs	{}

Example: ss.options.set(dpi=50) # Equivalent to ss.options(dpi=50)

set_jupyter

settings.Options.set_jupyter()

Set Sciris’ Jupyter settings as well

set_precision

settings.Options.set_precision()

Change the arithmetic precision used by Starsim/NumPy

set_style

settings.Options.set_style()

Change the plotting style

to_dict

settings.Options.to_dict()

Pull out only the settings from the options object

Functions

Name	Description
load_fonts	Helper function to load custom fonts for plotting – (usually) not for the user.
style	Set the style in a with block.

load_fonts

settings.load_fonts(
    folder=None,
    name='Mulish',
    rebuild=False,
    verbose=False,
    **kwargs,
)

Helper function to load custom fonts for plotting – (usually) not for the user.

Note: if fonts don’t load, try running ss.settings.load_fonts(rebuild=True), and/or rebooting the system.

Parameters

Name	Type	Description	Default
folder	str	the folder to add fonts from	None
name	str	the name of the font to load	'Mulish'
rebuild	bool	whether to rebuild the font cache	False
verbose	bool	whether to print out progress/errors	False

style

settings.style(style=None, **kwargs)

Set the style in a with block.

Note: Starsim comes bundled with three fonts: Mulish (default), Raleway, and Rosario. Use font='sans-serif' to use the Matplotlib default font.

Parameters

Name	Type	Description	Default
style	str	the style to use; if None, use current; otherwise, ‘starsim’, ‘simple’, ‘fancy’, plus all of the Matplotlib styles are options	None
**kwargs	dict	passed to sc.options.with_style()	{}

Examples::

# Create a plot using default Starsim styling
with ss.style():
    plt.plot()

# Create a plot using a built-in Matplotlib style
with ss.style('seaborn-v0_8-whitegrid'):
    plt.plot()

# Customize the current style
with ss.style(font='Rosario'):
    plt.plot()