Recipes

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

Recipe metadata

Recipe is a class that holds metadata from a recipe.

>>> Recipe('path/to/recipe_python.yml')
recipe = Recipe('Recipe Python')

Printing the recipe will give a nice overview of the recipe:

>>> print(recipe)
## Recipe python

Example recipe that plots a map and timeseries of temperature.

### Authors
 - Bouwe Andela (NLeSC, Netherlands; https://orcid.org/0000-0001-9005-8940)
 - Mattia Righi (DLR, Germany; https://orcid.org/0000-0003-3827-5950)

### Maintainers
 - Manuel Schlund (DLR, Germany; https://orcid.org/0000-0001-5251-0158)

### Projects
 - DLR project ESMVal
 - Copernicus Climate Change Service 34a Lot 2 (MAGIC) project

### References
 - Please acknowledge the project(s).

Running a recipe

To run the recipe, call the run() method.

>>> output = recipe.run()
<log messages>

By default, a new Session is automatically created, so that data are never overwritten. Data are stored in the esmvaltool_output directory specified in the config. Sessions can also be explicitly specified.

>>> from esmvalcore.experimental import CFG
>>> session = CFG.start_session('my_session')
>>> output = recipe.run(session)
<log messages>

run() returns an dictionary of objects that can be used to inspect the output of the recipe. The output is an instance of ImageFile or DataFile depending on its type.

For working with recipe output, see: Recipe output.

Running a single diagnostic or preprocessor task

The python example recipe contains 5 tasks:

Preprocessors:

  • timeseries/tas_amsterdam

  • timeseries/script1

  • map/tas

Diagnostics:

  • timeseries/tas_global

  • map/script1

To run a single diagnostic or preprocessor, the name of the task can be passed as an argument to run(). If a diagnostic is passed, all ancestors will automatically be run too.

>>> output = recipe.run('map/script1')
>>> output
map/script1:
  DataFile('CMIP5_CanESM2_Amon_historical_r1i1p1_tas_2000-2000.nc')
  DataFile('CMIP6_BCC-ESM1_Amon_historical_r1i1p1f1_tas_2000-2000.nc')
  ImageFile('CMIP5_CanESM2_Amon_historical_r1i1p1_tas_2000-2000.png')
  ImageFile('CMIP6_BCC-ESM1_Amon_historical_r1i1p1f1_tas_2000-2000.png')

It is also possible to run a single preprocessor task:

>>> output = recipe.run('map/tas')
>>> output
map/tas:
  DataFile('CMIP5_CanESM2_Amon_historical_r1i1p1_tas_2000-2000.nc')
  DataFile('CMIP6_BCC-ESM1_Amon_historical_r1i1p1f1_tas_2000-2000.nc')

API reference

Recipe metadata.

Classes:

Recipe(path)

API wrapper for the esmvalcore Recipe object.
class esmvalcore.experimental.recipe.Recipe(path: os.PathLike)[source]

Bases: object

API wrapper for the esmvalcore Recipe object.

This class can be used to inspect and run the recipe.

Parameters

path (pathlike) – Path to the recipe.

Attributes:

data

Return dictionary representation of the recipe.

name

Return the name of the recipe.

Methods:

get_output()

Get output from recipe.

render([template])

Render output as html.

run([task, session])

Run the recipe.
property data: dict

Return dictionary representation of the recipe.

get_output() → esmvalcore.experimental.recipe_output.RecipeOutput[source]

Get output from recipe.

Returns

output – Returns output of the recipe as instances of OutputFile grouped by diagnostic task.

Return type

dict

property name

Return the name of the recipe.

render(template=None)[source]

Render output as html.

templateTemplate

An instance of jinja2.Template can be passed to customize the output.

run(task: Optional[str] = None, session: Optional[esmvalcore.experimental.config._config_object.Session] = None)[source]

Run the recipe.

This function loads the recipe into the ESMValCore recipe format and runs it.

Parameters

  • task (str) – Specify the name of the diagnostic or preprocessor to run a single task.

  • session (Session, optional) – Defines the config parameters and location where the recipe output will be stored. If None, a new session will be started automatically.

Returns

output – Returns output of the recipe as instances of OutputItem grouped by diagnostic task.

Return type

dict