<a id="api-recipe"></a>

# Recipes

This section describes the [`recipe`](#module-esmvalcore.experimental.recipe) submodule of the API (`esmvalcore.experimental`).

## Recipe metadata

[`Recipe`](#esmvalcore.experimental.recipe.Recipe) is a class that holds metadata from a recipe.

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

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

```python
>>> 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()`](#esmvalcore.experimental.recipe.Recipe.run) method.

```python
>>> 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.

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

[`run()`](#esmvalcore.experimental.recipe.Recipe.run) returns an dictionary of objects that can be used to inspect
the output of the recipe. The output is an instance of [`ImageFile`](esmvalcore.experimental.recipe_output.html.md#esmvalcore.experimental.recipe_output.ImageFile) or
[`DataFile`](esmvalcore.experimental.recipe_output.html.md#esmvalcore.experimental.recipe_output.DataFile) depending on its type.

For working with recipe output, see: [Recipe output](esmvalcore.experimental.recipe_output.html.md#api-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()`](#esmvalcore.experimental.recipe.Recipe.run). If a diagnostic
is passed, all ancestors will automatically be run too.

```python
>>> 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:

```python
>>> 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`](#esmvalcore.experimental.recipe.Recipe)(path)   | API wrapper for the esmvalcore Recipe object.   |
|-----------------------------------------------------------------|-------------------------------------------------|

### *class* esmvalcore.experimental.recipe.Recipe(path: [os.PathLike](https://docs.python.org/3/library/os.html#os.PathLike))

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#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`](#esmvalcore.experimental.recipe.Recipe.data)   | Return dictionary representation of the recipe.   |
|---------------------------------------------------------|---------------------------------------------------|
| [`name`](#esmvalcore.experimental.recipe.Recipe.name)   | Return the name of the recipe.                    |

**Methods:**

| [`get_output`](#esmvalcore.experimental.recipe.Recipe.get_output)()         | Get output from recipe.      |
|-----------------------------------------------------------------------|------------------------------|
| [`render`](#esmvalcore.experimental.recipe.Recipe.render)([template])   | Render output as html.       |
| [`run`](#esmvalcore.experimental.recipe.Recipe.run)([task, session]) | Run the recipe.              |
| [`to_yaml`](#esmvalcore.experimental.recipe.Recipe.to_yaml)([file])      | Write recipe to a YAML file. |

#### *property* data *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)*

Return dictionary representation of the recipe.

#### get_output() → [RecipeOutput](esmvalcore.experimental.recipe_output.html.md#esmvalcore.experimental.recipe_output.RecipeOutput)

Get output from recipe.

* **Returns:**
  Returns output of the recipe as instances of `OutputFile`
  grouped by diagnostic task.
* **Return type:**
  output

#### *property* name

Return the name of the recipe.

#### render(template=None)

Render output as html.

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

#### run(task: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None) = None, session: [Session](esmvalcore.config.html.md#esmvalcore.config.Session) | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [RecipeOutput](esmvalcore.experimental.recipe_output.html.md#esmvalcore.experimental.recipe_output.RecipeOutput)

Run the recipe.

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

* **Parameters:**
  * **task** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *None*) – Specify the name of the diagnostic or preprocessor to run a
    single task.
  * **session** ([*Session*](esmvalcore.config.html.md#esmvalcore.config.Session) *|* *None*) – Defines the config parameters and location where the recipe
    output will be stored. If `None`, a new session will be
    started automatically.
* **Returns:**
  Returns output of the recipe as instances of `OutputItem`
  grouped by diagnostic task.
* **Return type:**
  [RecipeOutput](esmvalcore.experimental.recipe_output.html.md#esmvalcore.experimental.recipe_output.RecipeOutput)

#### to_yaml(file: [os.PathLike](https://docs.python.org/3/library/os.html#os.PathLike) | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [str](https://docs.python.org/3/builtins/stdtypes.html#str)

Write recipe to a YAML file.

* **Parameters:**
  **file** ([*os.PathLike*](https://docs.python.org/3/library/os.html#os.PathLike) *|* *None*) – If provided, the recipe will be written to this file too.
* **Returns:**
  The YAML representation of the recipe as a string.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)