ewatercycle.esmvaltool.search

Search ESGF for datasets with ESMValTool.

Module Contents

ewatercycle.esmvaltool.search.logger
ewatercycle.esmvaltool.search.search_esgf(experiment: str, frequency: Literal['hr', '3hr', 'day'], variables: list[str], project: str = 'CMIP6', extended_mip_tables: bool = False, verbose: bool = False) → dict[str, set[str]]

Search through ESGF using ESMValTool to find datasets fitting your requirements.

As different models require different inputs for their forcing generation, this module helps you find which CMIP models (and their ensembles) have the required variables stored on the Earth System Grid Federation (ESGF).

Do note that although a dataset might be in the MIP tables, the actual node hosting the data could be offline. Node status can be found here.

More informations on ESMValTool’s search functionality can be found at the ESMValCore api docs

For more information on what valid experiments, frequencies, variables are, see the CMIP6 controlled vocabulary (CV).

You can also use the ESGF REST API to ask for currently available values, e.g.: https://esgf-node.llnl.gov/esg-search/search?format=application%2Fsolr%2Bjson&project=CMIP6&facets=experiment_id&limit=0

Examples

To find all model ensembles which have the “pr”, “tas”, “rsdt” and “orog” variables (the ones required for wflow), for the ssp585 scenario.

from ewatercycle.esmvaltool.search import search_esgf

search_esgf(
    experiment="ssp585",
    frequency="day",
    variables=["pr", "tas", "rsdt", "orog"],
)

Gives something like:

{
    'MPI-ESM1-2-HR': {'r1i1p1f1', 'r2i1p1f1'},
    'MPI-ESM1-2-LR': {'r10i1p1f1', 'r11i1p1f1', ...  'r9i1p1f1'},
    'INM-CM4-8': {'r1i1p1f1'},
    'MRI-ESM2-0': {'r1i1p1f1', 'r2i1p1f1', 'r3i1p1f1', 'r4i1p1f1',
        'r5i1p1f1'},
    'IPSL-CM6A-LR': {'r1i1p1f1'},
    'GFDL-CM4': {'r1i1p1f1'},
}
Parameters:

  • experiment – The experiment of interest. E.g.: ‘ssp585’

  • frequency – Which frequency of data are you interested in. Valid inputs are ‘hr’, ‘3hr’, and ‘day.

  • variables – Which variables are you searching for. Use the short_name definition. For example: [‘pr’, ‘tas’].

  • project – Which project to search in. Defaults to ‘CMIP6’.

  • extended_mip_tables – Optional. If you want to use extended MIP tables. These tables are probably not relevant for most hydrology usecases and can make the search slower. Defaults to False.

  • verbose – Optional. If the results should be printed in a verbose way, to aid in your search experience. Defaults to False.

Returns:

A dictionary with the dataset name as key, and the valid ensemble member names in a set as items.