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 or using the climetlab command line.

Accessing settings

CliMetLab settings can be accessed using the python API:

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

Or through the command line interface.

$ climetlab settings cache-directory

Or using the climetlab interactive prompt:

$ climetlab
(climetlab) settings cache-directory

Changing settings

Note

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

CliMetLab settings can be modified using the python API:

import climetlab as cml

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

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

Or through the command line interface (CLI). Note that changing settings containing dictionary values is not possible with the CLI.

$ climetlab settings cache-directory /big-disk/climetlab-cache

Or using the climetlab interactive prompt:

$ climetlab
(climetlab) settings cache-directory /big-disk/climetlab-cache

Resetting settings

Note

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

CliMetLab settings can be reset using the python API:

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()

Or through the command line interface (CLI):

$ climetlab settings_reset cache-directory
$ climetlab settings_reset --all

Or using the climetlab interactive prompt:

$ climetlab
(climetlab) settings_reset
To wipe the cache completely, please use the --all flag. Use --help for more information.
(climetlab) settings_reset --all
(climetlab) Ctrl^D

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	True	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
graph‑plotting‑backend	‘matplotlib’	Default backend for plotting graphs.
layers‑directories	[‘/home/docs/.climetlab/layers’]	List of directories where to search for layers definitions. See Layers for more information.
map‑plotting‑backend	‘magics’	Default backend for plotting maps.
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.