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 for more information.

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

Common options are (see also

  • 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).


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


__call__(*args, **kwargs)[source]#

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


Pull out only the settings from the options object


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 for more information.

  • 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


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

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

New in version 3.1.0.


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


Handle Jupyter settings


Helper function to get the original default options


Check if current setting has been changed from default

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

Print information about options.

  • detailed (bool) – whether to print out full help

  • output (bool) – whether to return a list of the options

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

Load current settings from a JSON file.

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

Save current settings as a JSON file.

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

  • 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


with sc.options.with_style(dpi=300): # Use default options, but higher DPI

with sc.options.with_style(style='fancy'): # Use the "fancy" style

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


sc.options.use_style() # Set Sciris options as default
pl.plot([1,3,7])'seaborn-whitegrid') # to something else