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 downloaded 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
dask‑directories	[‘/home/docs/.climetlab/dask’]	List of directories where to search for dask cluster definitions. See dask for more information.
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.
use‑standalone‑mars‑client‑when‑available	True	Use the standalone mars client when available instead of using the web API.