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 plotting.

The configuration can be accessed using scipp.config which provides dict-like access to configuration values. For example, the following reads the default resolution of figures.

[1]:

import scipp as sc

[2]:

sc.config['plot']['dpi']

[2]:

96

Programmatic Configuration#

It is possible to modify scipp.config directly. This changes the configuration for the currrent 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 width of figures.

[3]:

sc.config['plot']['width'] = 800  # 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

# Default style of plots produced by scipp.
plot:
  use_plopp: False
  # Aspect ratio for images.
  # - 'equal' conserves the aspect ratio of the image.
  # - 'auto' stretches the image to the size of the figure.
  # See https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html
  aspect: auto

  # The list of default line colors for one-dimensional plots. When multiple lines are
  # on the same plot, the first line will use the first color, the second line will
  # use the second color, and so on.
  color:
    - '#1f77b4'
    - '#ff7f0e'
    - '#2ca02c'
    - '#d62728'
    - '#9467bd'
    - '#8c564b'
    - '#e377c2'
    - '#7f7f7f'
    - '#bcbd22'
    - '#17becf'

  # Style of lines
  # Cycles through values given here when more than one line is drawn in a single call.
  # Use 'none' to disable lines.
  # See https://matplotlib.org/stable/api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D.set_linestyle
  linestyle:
    - none

  # Width of lines.
  # Cycles through these when more than one line is drawn in a single call.
  linewidth:
    - 1.5

  # List of matplotlib line markers. When multiple lines are on the same plot, the
  # first line will use the first marker, the second line will use the second marker, and so on.
  # See https://matplotlib.org/stable/api/markers_api.html
  marker:
    - 'o'
    - '^'
    - 's'
    - 'd'
    - '*'
    - '1'
    - 'P'
    - 'h'
    - 'X'
    - 'v'
    - '<'
    - '>'
    - '2'
    - '3'
    - '4'
    - '8'
    - 'p'
    - 'H'
    - '+'
    - 'x'
    - 'D'

  # Dots per inch (resolution) of figures
  dpi: 96

  # Monitor pixel ratio (see https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio).
  # This affects the size of the points in three-dimensional plots.
  # Set to > 1 for high density (e.g. retina) displays
  pixel_ratio: 1.0

  # Height and width of figures in pixels.
  height: 400
  width: 600

  # Rectangle into which figure content is drawn
  # in normalized figure coordinates.
  bounding_box:
    - 0.05  # distance from left edge
    - 0.02  # distance from bottom edge
    - 1  # width
    - 1  # height

  # Colorbar properties.
  params:
    # Choose whether to show a colorbar where applicable.
    cbar: true
    # Colormap for 2D and 3D plots.
    # See https://matplotlib.org/stable/gallery/color/colormap_reference.html
    cmap: viridis
    # Generate a colormap from this color if given.
    # Overrides cmap.
    color: null
    # Mark values of NaN with this color.
    nan_color: '#d3d3d3'
    # Normalization for y values (1D plots), colorbar (2D and 3D plots).
    # One of ['linear', 'log']
    norm: linear
    # Color of values above vmax.
    over_color: '#8c564b'
    # Color of values below vmin.
    under_color: '#9467bd'
    # Minimum value of y-axis (1D), of the colorbar (2D and 3D).
    vmax: null
    # Minimum value of y-axis (1D), of the colorbar (2D and 3D).
    vmin: null