Runtime Configuration#

The Scipp package supports several configuration options which may be set based on preference. Most of these are related to layout of items in Jupyter Notebooks and visualizations.

The configuration can be accessed using scipp.config which provides dict-like access to configuration values.

For example, the following reads the default maximum size for table representations of a dataset.

[1]:

import scipp as sc

[2]:

sc.config['table_max_size']

[2]:

50

Programmatic Configuration#

It is possible to modify scipp.config directly. This changes the configuration for the current process only. So all changes are lost when Python is restarted. In order to make persistent changes, use a configuration file.

As an example, the following changes the default maximum table size.

[3]:

sc.config['table_max_size'] = 100  # for the current process only

Configuration File#

Scipp can also be configured using YAML files. See below for the default file.

The configuration is read from two files (if they exist).

User Configuration#

A file called config.yaml in an operating-system-dependent location, specifically

  • MacOS: ~/.config/scipp or ~/Library/Application Support/scipp

  • Other Unix: ~/.config/scipp or /etc/scipp

  • Windows: %APPDATA%\scipp where the APPDATA environment variable falls back to %HOME%\AppData\Roaming if undefined

Use

sc.config.config_dir()

to find the folder on your system. Or use

sc.config.config_path()

to get the full path to the configuration file.

These functions create the folder if it does not already exist. But they do not create the file, you have to do that yourself.

NOTE:

Depending on your setup, your user profile might not have permissions to create the folder. If this is the case, sc.config.config_dir() and sc.config.config_path() raise a PermissionError and Scipp falls back to using the default configuration. This can be avoided by creating the configuration directory and file manually with elevated permissions, if possible.

Working Directory#

A file called scipp.config.yaml in the current working directory. That is, the directory of the Jupyter notebook or from where you started the Python interpreter.

If this file exists in the working directory, it takes precedence over the user configuration.

Creating a Configuration File#

In order to use configuration files, copy the default configuration at the bottom of this page to the location of your choice (See User Configuration and Working Directory) and modify any values you like.

Alternatively, you can provide only those values that you want to change and leave out everything else. This way, Scipp falls back to the default values. Or, in the case of a file in the working directory, it falls back to the user configuration.

WARNING:

The fields in the configuration file are not strictly defined and may vary between Scipp versions. For this reason it is advised to browse the defaults below to determine what options are available.

Default Configuration#

The following is the default configuration expressed in the syntax of configuration YAML files. (default_config is a helper defined in a hidden cell.)

[5]:

default_config

[5]:

## Configuration file for scipp
## See https://scipp.github.io/reference/runtime-configuration.html
##
## COLORS
## All colors are given as one of
##     - a hex string, such as #ff00ff
##     - a scalar grayscale intensity such as 0.75 (as a string)
##     - a legal html color name, e.g., red, blue, darkslategray
##

# Colors used by output to Jupyter notebooks by, e.g. show, table, plot
colors:
  attrs: '#ff5555'
  coords: '#c6e590'
  data: '#f6d028'
  masks: '#c8c8c8'

  # Color for plot control button.
  button: '#bdbdbd49'
  # Color for selected plot control button.
  button_selected: '#bdbdbdbb'
  # Color for table header text.
  header_text: '#111111'
  # Color for hovering on table rows.
  hover: '#d6eaf8'

# Maximum number of rows in a table to display at the same time.
table_max_size: 50