ScirisOptions#

class ScirisOptions[source]#

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

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

set(key=None, value=None, use=True, **kwargs)[source]#

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

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

New in version 3.1.0.

context(**kwargs)[source]#

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

Set a global option for Matplotlib – not for users

set_jupyter(kwargs=None)[source]#

Handle Jupyter settings

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:

sc.options.help(detailed=True)
load(filename, verbose=True, **kwargs)[source]#

Load current settings from a JSON file.

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

Save current settings as a JSON file.

Parameters:
with_style(style=None, use=False, **kwargs)[source]#

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 plt.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 plt.rcParams

Examples:

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

with sc.options.with_style(style='fancy'): # Use the "fancy" style
    plt.figure()
    plt.plot([6,1,3])
use_style(style=None, **kwargs)[source]#

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

Example:

sc.options.use_style() # Set Sciris options as default
plt.figure()
plt.plot([1,3,7])

plt.style.use('ggplot') # to something else
plt.figure()
plt.plot([3,1,4])
On this page