Utils

This section describes the utils submodule of the API (esmvalcore.experimental).

Finding recipes

One of the first thing we may want to do, is to simply get one of the recipes available in ESMValTool

If you already know which recipe you want to load, call get_recipe().

from esmvalcore.experimental import get_recipe
>>> get_recipe('examples/recipe_python')
Recipe('Recipe python')

Call the get_all_recipes() function to get a list of all available recipes.

>>> from esmvalcore.experimental import get_all_recipes
>>> recipes = get_all_recipes()
>>> recipes
[Recipe('Recipe perfmetrics cmip5 4cds'),
 Recipe('Recipe martin18grl'),
 ...
 Recipe('Recipe wflow'),
 Recipe('Recipe pcrglobwb')]

To search for a specific recipe, you can use the find() method. This takes a search query that looks through the recipe metadata and returns any matches. The query can be a regex pattern, so you can make it as complex as you like.

>>> results = recipes.find('climwip')
[Recipe('Recipe climwip')]

The recipes are loaded in a Recipe object, which knows about the documentation, authors, project, and related references of the recipe. It resolves all the tags, so that it knows which institute an author belongs to and which references are associated with the recipe.

This means you can search for something like this:

>>> recipes.find('Geophysical Research Letters')
[Recipe('Recipe martin18grl'),
 Recipe('Recipe climwip'),
 Recipe('Recipe ecs constraints'),
 Recipe('Recipe ecs scatter'),
 Recipe('Recipe ecs'),
 Recipe('Recipe seaice')]

API reference

ESMValCore utilities.

Classes:

RecipeList([iterable])

Container for recipes.

Functions:

get_all_recipes([subdir])	Return a list of all available recipes.
get_recipe(name)	Get a recipe by its name.

class esmvalcore.experimental.utils.RecipeList(iterable=(), /)

Container for recipes.

Methods:

find(query)

Search for recipes matching the search query or pattern.

find(query: Pattern[str])

Search for recipes matching the search query or pattern.

Searches in the description, authors and project information fields. All matches are returned.

Parameters:

query (str, Pattern) – String to search for, e.g. find_recipes('righi') will return all matching that author. Can be a regex pattern.

Returns:

List of recipes matching the search query.

Return type:

RecipeList

esmvalcore.experimental.utils.get_all_recipes(subdir: str | None = None) → list

Return a list of all available recipes.

Parameters:

subdir (str) – Sub-directory of the DIAGNOSTICS.path to look for recipes, e.g. get_all_recipes(subdir='examples').

Returns:

List of available recipes

Return type:

RecipeList

esmvalcore.experimental.utils.get_recipe(name: PathLike | str) → Recipe

Get a recipe by its name.

The function looks first in the local directory, and second in the repository defined by the diagnostic path. The recipe name can be specified with or without extension. The first match will be returned.

Parameters:

name (str, pathlike) – Name of the recipe file, i.e. examples/recipe_python.yml

Returns:

Instance of Recipe which can be used to inspect and run the recipe.

Return type:

Recipe

Raises:

FileNotFoundError – If the name cannot be resolved to a recipe file.