Settings

CliMetLab is maintaining a set of global settings which control its behaviour.

The settings are saved in ~/.climetlab/settings.yaml. They can be accessed from Python as shown below:

Accessing settings

import climetlab as cml

# Access one of the settings
cache_path = cml.settings.get("cache-directory")
print(cache_path)

# If this is the last line of a Notebook cell, this
# will display a table with all the current settings
cml.settings

Changing settings

import climetlab as cml

# Change the location of the cache:
cml.settings.set("cache-directory", "/big-disk")

# Set some default plotting options (e.g. all maps will
# be 400 pixels wide by default):
cml.settings.set("plotting-options", width=400)

Resetting settings

import climetlab as cml

# Reset a named setting to its default value
cml.settings.reset("cache-directory")

# Reset all settings to their default values
cml.settings.reset()

Note

It is recommended to restart your Jupyter kernels after changing or resetting settings.

Default values

Name	Default	Description
cache‑directory	‘/tmp/climetlab‑docs’	Directory of where the dowloaded files are cached, with ${USER} is the user id. See Caching for more information.
check‑out‑of‑date‑urls	False	Perform a HTTP request to check if the remote version of a cache file has changed
datasets‑catalogs‑urls	[’https://github.com/ecmwf‑lab/climetlab‑datasets/raw/main/datasets’]	List of url where to search for catalogues of datasets definitions. See Datasets for more information.
datasets‑directories	[‘/home/docs/.climetlab/datasets’]	List of directories where to search for datasets definitions. See Datasets for more information.
download‑out‑of‑date‑urls	False	Re-download URLs when the remote version of a cached file as been changed
layers‑directories	[‘/home/docs/.climetlab/layers’]	List of directories where to search for layers definitions. See Layers for more information.
maximum‑cache‑disk‑usage	‘90%’	Disk usage threshold after which CliMetLab expires older cached entries (% of the full disk capacity). See Caching for more information.
maximum‑cache‑size	None	Maximum disk space used by the CliMetLab cache (ex: 100G or 2T).
number‑of‑download‑threads	5	Number of threads used to download data.
plotting‑options	{}	Dictionary of default plotting options. See Plotting for more information.
projections‑directories	[‘/home/docs/.climetlab/projections’]	List of directories where to search for projections definitions. See Projections for more information.
styles‑directories	[‘/home/docs/.climetlab/styles’]	List of directories where to search for styles definitions. See Styles for more information.
url‑download‑timeout	’30s’	Timeout when downloading from an url.