sc_settings
Define options for Sciris, mostly plotting options.
All options should be set using set() or directly, e.g.:
sc.options(font_size=18)To reset default options, use:
sc.options.reset()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 |
|---|---|
| ScirisOptions | Set options for Sciris. |
ScirisOptions
sc_settings.ScirisOptions()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
interactiveandjupyter, plus styles - New in version 3.0.0: renamed from Options to ScirisOptions to avoid potential confusion with
sc.options - New in version 3.2.5: locked attributes to prevent accidental modification
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 Sciris – not to be called by the user, use |
| help | Print information about options. |
| load | Load current settings from a JSON file. |
| reset | Alias to sc.options.set(‘defaults’) |
| save | Save current settings as a JSON file. |
| set | Actually change the style. See sc.options.help() for more information. |
| set_jupyter | Handle Jupyter settings |
| set_matplotlib_global | Set a global option for Matplotlib – not for users |
| set_show_type | Set NumPy to show numbers as just e.g. 1.3 (Sciris default) or np.float64(1.3) (NumPy default) |
| to_dict | Pull out only the settings from the options object |
| use_style | Shortcut to set Sciris’s current style as the global default. |
| with_style | Combine all Matplotlib style information, and either apply it directly |
changed
sc_settings.ScirisOptions.changed(key)Check if current setting has been changed from default
context
sc_settings.ScirisOptions.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.
disp
sc_settings.ScirisOptions.disp()Detailed representation
get_default
sc_settings.ScirisOptions.get_default(key)Helper function to get the original default options
get_orig_options
sc_settings.ScirisOptions.get_orig_options()Set the default options for Sciris – not to be called by the user, use sc.options.set('defaults') instead.
help
sc_settings.ScirisOptions.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:
sc.options.help(detailed=True)load
sc_settings.ScirisOptions.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() |
{} |
reset
sc_settings.ScirisOptions.reset()Alias to sc.options.set(‘defaults’)
New in version 3.1.0.
save
sc_settings.ScirisOptions.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
sc_settings.ScirisOptions.set(key=None, value=None, use=True, **kwargs)Actually change the style. See sc.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) | True |
| kwargs | dict | if supplied, set multiple key-value pairs | {} |
Example:
sc.options.set(dpi=50) # Equivalent to sc.options(dpi=50)set_jupyter
sc_settings.ScirisOptions.set_jupyter(kwargs=None)Handle Jupyter settings
set_matplotlib_global
sc_settings.ScirisOptions.set_matplotlib_global(key, value)Set a global option for Matplotlib – not for users
set_show_type
sc_settings.ScirisOptions.set_show_type()Set NumPy to show numbers as just e.g. 1.3 (Sciris default) or np.float64(1.3) (NumPy default)
to_dict
sc_settings.ScirisOptions.to_dict()Pull out only the settings from the options object
use_style
sc_settings.ScirisOptions.use_style(style=None, **kwargs)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])with_style
sc_settings.ScirisOptions.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 plt.style.context().
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| style_args | dict | a dictionary of style arguments | required |
| 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 `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])Functions
| Name | Description |
|---|---|
| help | Get help on Sciris in general, or search for a word/expression. |
| parse_env | Simple function to parse environment variables |
help
sc_settings.help(
pattern=None,
source=False,
ignorecase=True,
flags=None,
context=False,
output=False,
debug=False,
)Get help on Sciris in general, or search for a word/expression.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pattern | str | the word, phrase, or regex to search for | None |
| source | bool | whether to search source code instead of docstrings for matches | False |
| ignorecase | bool | whether to ignore case (equivalent to flags=re.I) |
True |
| flags | list | additional flags to pass to re.findall() |
None |
| context | bool | whether to show the line(s) of matches | False |
| output | bool | whether to return the dictionary of matches | False |
Examples:
sc.help()
sc.help('smooth')
sc.help('JSON', ignorecase=False, context=True)
sc.help('pickle', source=True, context=True)- New in version 1.3.0.
- New in version 1.3.1: “source” argument
parse_env
sc_settings.parse_env(var, default=None, which='str')Simple function to parse environment variables
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| var | str | name of the environment variable to get | required |
| default | any | default value | None |
| which | str | what type to convert to (if None, don’t convert) | 'str' |
Example:
sc.parse_env('MY_FACTOR', default=3.5, which=float)- New in version 2.0.0.
- New in version 3.2.1: allow actual types