ewatercycle.esmvaltool.builder

Builder and runner for ESMValTool recipes.

The recipes can be used to generate forcings.

Module Contents

ewatercycle.esmvaltool.builder.DIAGNOSTIC_NAME = 'diagnostic'
ewatercycle.esmvaltool.builder.SPATIAL_PREPROCESSOR_NAME = 'spatial'
ewatercycle.esmvaltool.builder.SCRIPT_NAME = 'script'
ewatercycle.esmvaltool.builder.DEFAULT_DIAGNOSTIC_SCRIPT
ewatercycle.esmvaltool.builder.logger
class ewatercycle.esmvaltool.builder.RecipeBuilder

Builder for ESMValTool recipes tailored to generate forcings.

Example

To create a recipe from ERA5 dataset and the Rhine basin:

>>> from ewatercycle.testing.fixtures import rhine_shape
>>> from ewatercycle.forcing import RecipeBuilder
>>> recipe = (
...     RecipeBuilder()
...     .title("Generic distributed forcing recipe")
...     .dataset("ERA5")
...     .start(2000)
...     .end(2001)
...     .shape(rhine_shape())
...     .add_variable("pr")
...     .build()
... )
>>> recipe.save("recipe.yml")

To run the recipe:

esmvaltool recipe.yml

Order in which methods are called matters in the following cases:

  • regrid before adding variables

  • lump after spatial selection and before adding variables

  • temporal selection before adding variables

  • spatial selection before adding variables

Initialize the recipe builder.

build() → ewatercycle.esmvaltool.schema.Recipe

Build the recipe.

Should be called after all other methods.

description(description: str) → RecipeBuilder

Set the description of the recipe.

Parameters:

description – Description of the recipe.

title(title: str) → RecipeBuilder

Set the title of the recipe.

Parameters:

title – Title of the recipe.

dataset(dataset: ewatercycle.esmvaltool.schema.Dataset | str | dict) → RecipeBuilder

Set the dataset of the recipe.

Parameters:

dataset – Dataset to use for the recipe. When string is given a predefined dataset is looked up in ewatercycle.esmvaltool.datasets.DATASETS. When dict given it is passed to ewatercycle.esmvaltool.schema.Dataset constructor.

Only one dataset is allowed when generating eWaterCycle forcings. Calling this method again will overwrite the previous dataset.

mip(value: str) → RecipeBuilder

Set the default time frequency for all later added variables.

Parameters:

value – time frequency, e.g. ‘day’, ‘Eday’, ‘CFday’, ‘fx’. Defaults to ‘day’.

start(value: int) → RecipeBuilder

Set the start year of the recipe.

Parameters:

value – Start year of the recipe.

end(value: int) → RecipeBuilder

Set the end year of the recipe.

Parameters:

value – End year of the recipe.

regrid(scheme: str, target_grid: ewatercycle.esmvaltool.schema.TargetGrid) → RecipeBuilder

Regrid the data from the dataset to a different grid.

Parameters:
shape(file: pathlib.Path | str, crop: bool = True, decomposed: bool = False) → RecipeBuilder

Select data within a shapefile.

Parameters:

  • file – Path to shapefile.

  • crop – Crop data to shapefile extent. Otherwise data outside shapefile extent is set to NaN.

  • decomposed – Decompose shapefile into separate polygons.

region(start_longitude: float, end_longitude: float, start_latitude: float, end_latitude: float) → RecipeBuilder

Select data within a region.

Parameters:

  • start_longitude – Start longitude of the region.

  • end_longitude – End longitude of the region.

  • start_latitude – Start latitude of the region.

  • end_latitude – End latitude of the region.

region_by_shape(shape: pathlib.Path, pad=0) → RecipeBuilder

Select data within a region defined by extents of a shapefile.

Parameters:

  • shape – Path to shapefile.

  • pad – Pad the region with this many degrees.

lump(operator: Literal['mean', 'median', 'std_dev', 'sum', 'variance', 'min', 'max', 'rms'] = 'mean') → RecipeBuilder

Lump gridded data into a single value spatially.

See https://docs.esmvaltool.org/projects/ESMValCore/en/latest/api/esmvalcore.preprocessor.html#esmvalcore.preprocessor.area_statistics

Parameters:

operator – The operator to use for lumping.

add_variables(variables: collections.abc.Sequence[str]) → RecipeBuilder

Add variables to the recipe.

Parameters:

variables – Names of variables to add to the recipe.

add_variable(variable: str, mip: str | None = None, units: str | None = None, stats: ewatercycle.esmvaltool.schema.ClimateStatistics | None = None, short_name: str | None = None, start_year: int | None | Literal[False] = None, end_year: int | None | Literal[False] = None)

Add a variable to the recipe.

Parameters:

  • variable – The name of the variable to add.

  • mip – The MIP table to use for the variable. If not given then defaults to what was set with self.mip(value).

  • units – The unit to convert the variable to. Default no conversion. See https://docs.esmvaltool.org/projects/ESMValCore/en/latest/recipes/recipe_file.html#convert-units

  • stats – The climate statistics to apply to the variable. Defaults to not applying any statistics.

  • short_name – A short name for the variable. Defaults to variable name.

  • start_year – The start year of the variable. Defaults to start year of dataset. Use False to disable temporal selection.

  • end_year – The end year of the variable. Defaults to end year of dataset. Use False to disable temporal selection.

script(script: str, arguments: dict[str, str] | None = None) → RecipeBuilder

Set script of recipe.

When script has not been set will default to copying the ESMValTool preprocessed files to the output directory using the ewatercycle.esmvaltool.diagnostic.copier script.

Parameters:

  • script – Path to script to run.

  • arguments – Arguments to pass to the script.

ewatercycle.esmvaltool.builder.build_generic_distributed_forcing_recipe(start_year: int, end_year: int, shape: pathlib.Path, dataset: ewatercycle.esmvaltool.schema.Dataset | str | dict = 'ERA5', variables: collections.abc.Sequence[str] = ('pr', 'tas', 'tasmin', 'tasmax'))

Build a generic distributed forcing recipe.

Parameters:

  • start_year – Start year of the data to retrieve.

  • end_year – End year of the data to retrieve.

  • shape – Path to shapefile. Used for spatial selection.

  • dataset – Dataset to use for the recipe.

  • variables – Names of variables to add to the recipe.

Recipe will return a NetCDF file for each variable.

ewatercycle.esmvaltool.builder.build_generic_lumped_forcing_recipe(start_year: int, end_year: int, shape: pathlib.Path, dataset: ewatercycle.esmvaltool.schema.Dataset | str | dict = 'ERA5', variables: collections.abc.Sequence[str] = ('pr', 'tas', 'tasmin', 'tasmax'))

Build a generic lumped forcing recipe.

Parameters:

  • start_year – Start year of the data to retrieve.

  • end_year – End year of the data to retrieve.

  • shape – Path to shapefile. Used for spatial selection.

  • dataset – Dataset to use for the recipe.

  • variables – Names of variables to add to the recipe.

Recipe will return a NetCDF file for each variable.