Configuration

The 3ML configuration sets up defaults that are read in at runtime and is a session wide state that the user can modify at any point during an analysis to alter behavior throughout 3ML.

The configuration is a hierarchical you can import and modify.

[1]:

import warnings

warnings.simplefilter("ignore")
import numpy as np

np.seterr(all="ignore")

[1]:

{'divide': 'warn', 'over': 'warn', 'under': 'ignore', 'invalid': 'warn'}

[2]:

%%capture
from threeML import threeML_config, show_configuration

show_configuration()

Local configuration

You can store a local configuration read in at the beginning of every session. By default, 3ML looking in ~/.config/threeml/*.yml for configuration files.

You can set your own location with the environment variable THREEML_CONFIG
All YAML files in this directiory are considered to be configuration files.

Multiple configuration files can be added allowing you to have readable seperation between different topics.

E.g, here are two configuration files that modify some plotting defaults and logging defaults in separate files.

```yaml
plugins:
  ogip:
    fit_plot:
      model_cmap: Spectral
      data_color: grey
      background_color: k
      background_mpl_kwargs:
        lw: .8
        ls: "-"

```yaml
logging:
  developer: on
  startup_warnings: off

[3]:

show_configuration("plugins")

[3]:

config
┣━━ ogip
┃   ┣━━ fit_plot
┃   ┃   ┣━━ data_cmap: MPLCmap.Set1
┃   ┃   ┣━━ model_cmap: MPLCmap.Set1
┃   ┃   ┣━━ background_cmap: MPLCmap.Set1
┃   ┃   ┣━━ n_colors: 5
┃   ┃   ┣━━ step: False
┃   ┃   ┣━━ show_legend: True
┃   ┃   ┣━━ show_residuals: True
┃   ┃   ┣━━ data_color: None
┃   ┃   ┣━━ model_color: None
┃   ┃   ┣━━ background_color: None
┃   ┃   ┣━━ show_background: False
┃   ┃   ┣━━ data_mpl_kwargs: None
┃   ┃   ┣━━ model_mpl_kwargs: None
┃   ┃   ┗━━ background_mpl_kwargs: None
┃   ┣━━ data_plot
┃   ┃   ┣━━ counts_color: #500472
┃   ┃   ┣━━ background_color: #79cbb8
┃   ┃   ┣━━ warn_channels_color: #C79BFE
┃   ┃   ┣━━ bad_channels_color: #FE3131
┃   ┃   ┗━━ masked_channels_color: #566573
┃   ┣━━ response_cmap: MPLCmap.viridis
┃   ┗━━ response_zero_color: k
┣━━ photo
┃   ┗━━ fit_plot
┃       ┣━━ data_cmap: MPLCmap.Set1
┃       ┣━━ model_cmap: MPLCmap.Set1
┃       ┣━━ background_cmap: MPLCmap.Set1
┃       ┣━━ n_colors: 5
┃       ┣━━ step: False
┃       ┣━━ show_legend: True
┃       ┣━━ show_residuals: True
┃       ┣━━ data_color: None
┃       ┣━━ model_color: None
┃       ┣━━ background_color: None
┃       ┣━━ show_background: False
┃       ┣━━ data_mpl_kwargs: None
┃       ┣━━ model_mpl_kwargs: None
┃       ┗━━ background_mpl_kwargs: None
┗━━ fermipy
    ┗━━ fit_plot
        ┣━━ total_model_color: k
        ┣━━ show_background_sources: True
        ┣━━ shade_fixed_sources: True
        ┣━━ shade_secondary_sources: False
        ┣━━ fixed_sources_color: grey
        ┣━━ secondary_sources_color: k
        ┣━━ data_cmap: MPLCmap.Set1
        ┣━━ model_cmap: MPLCmap.Set1
        ┣━━ background_cmap: MPLCmap.Set1
        ┣━━ step: False
        ┣━━ show_legend: True
        ┣━━ show_residuals: True
        ┣━━ data_color: None
        ┣━━ model_color: None
        ┣━━ background_color: None
        ┣━━ data_mpl_kwargs: None
        ┣━━ model_mpl_kwargs: None
        ┗━━ background_mpl_kwargs: None

The configuration now includes the values from the files.

Environment variables

It is possible to set configuration values from environment variables. For example, if you are working in a HPC cluster environment and need to log to w write-safe directory:

```yaml
logging:
  path: ${env:USER_LOG_DIR}
  developer: off
  console: off
  startup_warnings: off

where USER_LOG_DIR could be a directory where you are allowed to write to disk. At run time, we convert this variable to a path. However, any value can be set. Thus, you can make an adaptable configuration that mutates based on your local workstation.

Run-time configuration changes

But perhaps you want to change a parameter in the middle of a session? The configuration behaves like a nested dictionary but it has both dot and key access. Let’s take a look at what we can configure:

Perhaps we want the default colors for light curves to be altered for this session:

[4]:

threeML_config.time_series.background_color

[4]:

'#C0392B'

[5]:

threeML_config["time_series"]["background_color"]

[5]:

'#C0392B'

[6]:

threeML_config.time_series.background_color = "green"
show_configuration("time_series")

[6]:

config
┣━━ light_curve_color: #05716c
┣━━ selection_color: #1fbfb8
┣━━ background_color: green
┣━━ background_selection_color: #E74C3C
┗━━ fit
    ┣━━ fit_poly: True
    ┣━━ unbinned: False
    ┗━━ bayes: False

From this point on in this session, fitting LLE backgrounds will be unbinned. When we close python, the next time we start 3ML, the values set in the configuration file be loaded.

Do not worry about entering incorrect values in the file as 3ML checks both the structure and types of the parameters.

If you modify your configuration at run time and want to save it to a file (in your configration directory) try this:

[7]:

from threeML import get_current_configuration_copy

get_current_configuration_copy("my_config.yml", overwrite=True)

If you have a default configuration you would like to add, consider opening a pull request. We would love to hear your ideas.