Context
CliMetLab is a Python package developed by ECMWF (European Centre for Medium-Range Weather Forecasts) designed to simplify access to weather and climate data.
With the integration of the CliMetLab WEkEO Plugin, you have access now to a extended range of datasets provided by the Copernicus services, including Land, Marine, Climate Change, Emergency and Atmosphere data. The Plugin simplifies the access to the WEkEO datasets in the following ways:
automatic configuration of the WEkEO HDA, no need to monitor jobs and downloads anymore
CliMetLab stores and manages datasets in cache making the data management easier for the user
support of different data formats and direct conversion to xarray dataset
With CliMetLab you can access a variety of WEkEO datasets with only two lines of code: one for accessing the data and one for transforming the data to an xarray dataset!
In this article, we'll show how to use the Plugin to download WEkEO data. Let's go! 💪
📌 Note: please check you have installed the CliMetLab WEkEO Plugin before going further.
Running a first example with CliMetLab WEkEO Plugin
The function climetlab.load_dataset is a CliMetLab function that loads the dataset from the WEkEO HDA. When first downloading a dataset, you need to configure your WEkEO username and password asked when running the code cell.
The code below gives one example on how you can download and convert a dataset to xarray format using CliMetLab:
import climetlab as cml
dataset = cml.load_dataset(
"wekeo-ecmwf-reanalysis-era5-single-levels-monthly-means",
product_type = "monthly_averaged_reanalysis_by_hour_of_day",
month= "01",
year = "2019",
time=["00:00", "01:00", "02:00", "03:00", "04:00",
"05:00", "06:00", "07:00", "08:00", "09:00",
"10:00", "11:00", "12:00", "13:00", "14:00",
"15:00", "16:00", "17:00", "18:00", "19:00",
"20:00", "21:00", "22:00", "23:00"
],
variable = [
"2m_temperature"],
format_="netcdf",
)
xarray_dataset = dataset.to_xarray()
Building a CliMetLab query
Step 1. Retrieve CLiMetLab datasetID
Many datasets are supported by the CliMetLab WEkEO Plugin but not all yet. We invite you to go to the GitHub repository of the plugin and check if your dataset of interest is listed in the following folder.
A dataset can be accessed using CliMatLab with the load_dataset function. The minimum required argument for the function load_dataset is the datasetID.
The CliMetLab datasetID can be derived from the WEkEO datasetID of our catalogue.
For example:
WEkEO datasetID:
EO:ECMWF:DAT:REANALYSIS_ERA5_SINGLE_LEVELS_MONTHLY_MEANSCliMetLab datasetID:
wekeo-ecmwf-reanalysis-era5-single-levels-monthly-means
import climetlab as cml
dataset = cml.load_dataset("wekeo-ecmwf-reanalysis-era5-single-levels-monthly-means")
This code will download all available data in this dataset, which may correspond to a large volume of data. That's why we strongly advise you to subset the query by dataset attributes as we'll see below.
Step 2. Create a CliMetLab query to subset data
Many dataset attributes are subject to selection constraints and not all combinations of attributes are possible. It is advised to check the combination of the selection in the WEkEO Data Viewer before creating a CliMetLab query to avoid errors of empty queries.
There are two options to build up the CliMetLab query:
Method 1. Create an API request and use the hda2cml function
For any WEkEO dataset available through the HDA, the API request can be viewed and copied from the WEkEO Data Viewer.
You can follow this article to learn how to complete a WEkEO request, and click on Show API Request. The API request corresponds to the download parameters you chose in the download canvas:
The WEkEO CliMetLab Plugin offers a translation function that converts the WEkEO HDA API request to a CliMetLab query:
import climetlab as cml
from climetlab_wekeo_datasets import hda2cml
api_request = {
"datasetId": "EO:CLMS:DAT:CGLS_HOURLY_LST_GLOBAL_V2",
"dateRangeSelectValues": [
{
"name": "dtrange",
"start": "2021-07-01T00:00:00.000Z",
"end": "2021-07-02T00:00:00.000Z"
}
]
}
dataset_id, args = hda2cml(api_request)
dataset = cml.load_dataset(dataset_id, **args)
Method 2. Explore attributes in the Plugin source code
Each dataset is described with its attributes in a separate Python file from the plugin source code. For instance, the above-described Land Surface Temperature (LST) dataset can be found here.
Now, a CliMetLab query for WEkEO data can be created:
import climetlab as cml
dataset = cml.load_dataset(
"wekeo-clms-cgls-hourly-lst-global-v2",
start="2021-07-01T00:00:00Z",
end="2021-07-01T23:59:59Z",
)
The download result is stored in cache. Running again load_dataset for the same dataset with identical parameters will not trigger a new download, but will use the cached data instead.
After downloading, the dataset can be converted to an xarray dataset with to_xarray():
xarray_dataset = dataset.to_xarray()
Using the Python xarray module, the dataset can be analyzed and plotted.
Further resources
Template notebooks
Template notebooks are available in the Jupyter Catalogue to get you started on more advanced use cases with the CliMetLab WEkEO Plugin.
As a starting point, go to the CliMetLab Introduction Notebook and explore the possibilities of CliMetLab and WEkEO data.
Documentation
For further details on the installation process and usage of the dataset plugin, please go to the official documentation.
GitHub repositories
Find the repositories for the WEkEO Source Module and the three plugins on GitHub:
What's next?
If you encounter any issue by following the notebook, please contact the WEkEO Support.
Feel free to check these articles that might be of interest for you:
We are user-driven and implement users' suggestions, so feel free to contact us:
through a chat session available in the bottom right corner of the page
via our contact webpage
via e-mail to our support team (supportATwekeo.eu)