ScirisOptions

class ScirisOptions

Bases: objdict

Set options for Sciris.

Note: this class should not be invoked directly. An instance is created automatically, which is the accessible via sc.options.

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

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

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

• 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

• backend: which Matplotlib backend to use

• interactive: convenience method to set backend

• jupyter: True or False; set defaults for Jupyter (change backend)

• style: the plotting style to use (choices are ‘simple’ or ‘fancy’)

Each setting can also be set with an environment variable, e.g. SCIRIS_DPI. Note also the environment variable SCIRIS_LAZY, which imports Sciris lazily (i.e. does not import submodules).

Examples:

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

New in version 1.3.0.

New in version 2.0.0: revamped with additional options interactive and jupyter, plus styles

New in version 3.0.0: renamed from Options to ScirisOptions to avoid potential confusion with sc.options

Methods

__call__(*args, **kwargs)

Allow sc.options(dpi=150) instead of sc.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 Sciris – not to be called by the user, use sc.options.set('defaults') instead.

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

Actually change the style. See sc.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:

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

reset()

Alias to sc.options.set(‘defaults’)

New in version 3.1.0.

context(**kwargs)

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

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

set_matplotlib_global(key, value)

Set a global option for Matplotlib – not for users

set_jupyter(kwargs=None)

Handle Jupyter settings

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:

sc.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=None, use=False, **kwargs)

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

To set globally, use sc.options.use_style(). Otherwise, use sc.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!).

Note: you can also just use pl.style.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.rcParams

Examples:

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

with sc.options.with_style(style='fancy'): # Use the "fancy" style
    pl.figure()
    pl.plot([6,1,3])

use_style(**kwargs)

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

Example:

sc.options.use_style() # Set Sciris 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])