Generate C3S CDS cubes

xcube Data Store Framework – Climate Data Store¶

This notebook demonstrates how to access Climate Data Store (CDS) data via the dedicated xcube store, which provides dynamic data cube views into each gridded data set.

Please, also refer to the DeepESDL documentation and visit the platform's website for further information!

Brockmann Consult, 2025

This notebook runs with the python environment deepesdl-xcube-1.9.1, please checkout the documentation for help on changing the environment.

Please note:

To access data from the Climate Data Store, you need a CDS API key.

Obtain a CDS Personal Access Token¶

You can obtain a CDS Personal Access Token as follows:

Create a user account on the CDS Website.
Log in to the website with your username and password.
Navigate to your user page, where you can find your Personal Access Token.

Configure CDS API access¶

Your CDS Personal Access Token must be made available to the CDS API library. You can do this by creating a file named .cdsapirc in your home directory, with the following format:

url: https://cds.climate.copernicus.eu/api
key: <PERSONAL-ACCESS-TOKEN>

Replace <PERSONAL-ACCESS-TOKEN> with your Personal Access Token.

Then export the CDSAPI_URL and CDSAPI_KEY environment variables:

export CDSAPI_URL=https://cds.climate.copernicus.eu/api
export CDSAPI_KEY=[PERSONAL-ACCESS-TOKEN]

Agree to the terms of use for the datasets you require¶

The datasets available through CDS have associated terms of use. Before accessing a dataset via the API, you must agree to its terms of use, which can only be done via the CDS website, as follows:

Log in to the CDS website, and go to 'Datasets' to find the dataset you require.
On the dataset's web page, select the ‘Download’ tab.
Scroll to the bottom of the page, and you will see a section titled ‘Terms of use’, which will contain either an ‘Accept terms’ button to allow you to accept the terms, or a confirmation that you have already accepted the terms.

Once you have accepted the terms on the website, the dataset will also be made available to you through the API.

In [1]:

Copied!

import os
os.environ['CDSAPI_URL'] = 'https://cds.climate.copernicus.eu/api'
os.environ['CDSAPI_KEY'] = '[PERSONAL-ACCESS-TOKEN]'
import os
os.environ['CDSAPI_URL'] = 'https://cds.climate.copernicus.eu/api'
os.environ['CDSAPI_KEY'] = '[PERSONAL-ACCESS-TOKEN]'

In [3]:

Copied!





# mandatory imports
from xcube.core.store import find_data_store_extensions
from xcube.core.store import get_data_store_params_schema
from xcube.core.store import new_data_store

# Utilities for notebook visualization
from IPython.display import JSON
import matplotlib as mpl
import matplotlib.pyplot as plt
# mandatory imports
from xcube.core.store import find_data_store_extensions
from xcube.core.store import get_data_store_params_schema
from xcube.core.store import new_data_store

# Utilities for notebook visualization
from IPython.display import JSON
import matplotlib as mpl
import matplotlib.pyplot as plt

Configure matplotlib to display graphs inline directly in the notebook and set a sensible default figure size.

In [4]:

Copied!

%matplotlib inline
plt.rcParams["figure.figsize"] = 16,12
%matplotlib inline
plt.rcParams["figure.figsize"] = 16,12

Check whether the cds store is among the available stores, if not please follow the installation information from the top of this notebook.

In [5]:

Copied!

JSON({e.name: e.metadata for e in find_data_store_extensions()})
JSON({e.name: e.metadata for e in find_data_store_extensions()})

Out[5]:

<IPython.core.display.JSON object>

Usually we need more information to get the actual data store object. Which data store parameters are available for cds?

In [6]:

Copied!

get_data_store_params_schema('cds')
get_data_store_params_schema('cds')

Out[6]:

<xcube.util.jsonschema.JsonObjectSchema at 0x7f8ea1d37070>

Provide mandatory parameters to instantiate the store class:

In [7]:

Copied!

store = new_data_store('cds')
store
store = new_data_store('cds')
store

Out[7]:

<xcube_cds.store.CDSDataStore at 0x7f8ea1d21be0>

Which datasets are provided? (the list may contain both gridded and vector datasets):

In [9]:

Copied!

list(store.get_data_ids())
list(store.get_data_ids())

Out[9]:

['reanalysis-era5-single-levels:ensemble_mean',
 'reanalysis-era5-single-levels:ensemble_members',
 'reanalysis-era5-single-levels:ensemble_spread',
 'reanalysis-era5-single-levels:reanalysis',
 'reanalysis-era5-land',
 'reanalysis-era5-single-levels-monthly-means:monthly_averaged_ensemble_members',
 'reanalysis-era5-single-levels-monthly-means:monthly_averaged_reanalysis',
 'reanalysis-era5-land-monthly-means:monthly_averaged_reanalysis',
 'satellite-soil-moisture:saturation:daily',
 'satellite-soil-moisture:saturation:10-day',
 'satellite-soil-moisture:saturation:monthly',
 'satellite-soil-moisture:volumetric:daily',
 'satellite-soil-moisture:volumetric:10-day',
 'satellite-soil-moisture:volumetric:monthly',
 'satellite-sea-ice-thickness:envisat',
 'satellite-sea-ice-thickness:cryosat-2']

Get more info about a specific dataset. This includes a description of the possible open formats:

In [10]:

Copied!

store.describe_data('reanalysis-era5-single-levels-monthly-means:monthly_averaged_reanalysis')
store.describe_data('reanalysis-era5-single-levels-monthly-means:monthly_averaged_reanalysis')

Out[10]:

<xcube.core.store.descriptor.DatasetDescriptor at 0x7f8ea1bf9940>

There are 4 required parameters, so we need to provide them to open a dataset:

Plot the differences between successive time points in the dataset. We can see that the times are monotonically increasing (all the difference values are positive), but not equally spaced, since months are not all of the same length. The lowest values correspond to February; the four-year leap year cycle can also be discerned.

In [12]:

Copied!

dataset.time.diff(dim='time').plot.line(figsize=(20, 4))
dataset.time.diff(dim='time').plot.line(figsize=(20, 4))

Out[12]:

[<matplotlib.lines.Line2D at 0x7f8ea1637250>]

No description has been provided for this image

We can explore these data by plotting a temperature map for selected time points. First, we select January 2001. Land areas – and mountain ranges in particular – show up on the map as colder regions.

In [13]:

Copied!

t2m_2001_jan = dataset.t2m.sel(time='2001-01-01 00:00:00', method='nearest')
t2m_2001_jan.plot.imshow(vmin=260, vmax=285, figsize=(14, 8), cmap='plasma')
t2m_2001_jan = dataset.t2m.sel(time='2001-01-01 00:00:00', method='nearest')
t2m_2001_jan.plot.imshow(vmin=260, vmax=285, figsize=(14, 8), cmap='plasma')

Out[13]:

<matplotlib.image.AxesImage at 0x7f8ea1673380>

For a more elegant and informative map, we define a function to plot a customized orthographic projection with overlaid coastlines and a grid.

In [ ]: