Xarray engine: extra dimensions¶

[1]:

import earthkit.data as ekd

2D wave spectra example¶

We analyse a 2D wave spectra product at 2025-12-15 00 UTC and 03 UTC. A specific feature of this dataset is that the fields are additionally indexed by wavelength and frequency, on top of the standard temporal dimension.

[2]:

ds_fl = ekd.from_source("sample", "2d-wave-spectra_an.grib").to_fieldlist()

[3]:

ds_fl.ls(keys=["metadata.directionNumber", "metadata.frequencyNumber"])

[3]:

	metadata.directionNumber	metadata.frequencyNumber
0	1	1
1	2	1
2	3	1
3	4	1
4	5	1
...	...	...
2083	32	29
2084	33	29
2085	34	29
2086	35	29
2087	36	29

2088 rows × 2 columns

To represent this structure in Xarray, the predefined dimensions of the Xarray engine must therefore be complemented with dimensions derived from the metadata keys "directionNumber" and "frequencyNumber" when calling to_xarray()

[4]:

ds = ds_fl.to_xarray(
    extra_dims=["metadata.directionNumber", "metadata.frequencyNumber"],
    add_earthkit_attrs=False,
)
ds

The extra_dims option also supports defining an explicit mapping between the name of an extra dimension and the corresponding metadata key, in a way that is conceptually similar to dimension roles.

[5]:

ds2 = ds_fl.to_xarray(
    extra_dims=[{"d": "metadata.directionNumber"}, {"f": "metadata.frequencyNumber"}],
    add_earthkit_attrs=False,
)
ds2

Quantiles in a probabilistic forecast¶

Let us now consider a probabilistic forecast of 2-metre temperature.

[6]:

ds_fl2 = ekd.from_source("sample", "quantiles_pd.grib").to_fieldlist()

In this dataset, the fields are indexed by the GRIB metadata key "quantile".

[7]:

ds_fl2.ls(
    keys=[
        "parameter.variable",
        "time.base_datetime",
        "time.step",
        "ensemble.member",
        "metadata.number",
        "metadata.numberOfForecastsInEnsemble",
        "metadata.quantile",
    ]
)

[7]:

	parameter.variable	time.base_datetime	time.step	ensemble.member	metadata.number	metadata.numberOfForecastsInEnsemble	metadata.quantile
0	2tp	2025-12-09	7 days	1	1	3	1:3
1	2tp	2025-12-09	7 days	1	1	5	1:5
2	2tp	2025-12-09	7 days	1	1	10	1:10
3	2tp	2025-12-09	7 days	2	2	3	2:3
4	2tp	2025-12-09	7 days	2	2	5	2:5
5	2tp	2025-12-09	7 days	2	2	10	2:10
6	2tp	2025-12-09	7 days	3	3	3	3:3
7	2tp	2025-12-09	7 days	3	3	5	3:5
8	2tp	2025-12-09	7 days	3	3	10	3:10
9	2tp	2025-12-09	7 days	4	4	5	4:5
10	2tp	2025-12-09	7 days	4	4	10	4:10
11	2tp	2025-12-09	7 days	5	5	5	5:5
12	2tp	2025-12-09	7 days	5	5	10	5:10
13	2tp	2025-12-09	7 days	6	6	10	6:10
14	2tp	2025-12-09	7 days	7	7	10	7:10
15	2tp	2025-12-09	7 days	8	8	10	8:10
16	2tp	2025-12-09	7 days	9	9	10	9:10
17	2tp	2025-12-09	7 days	10	10	10	10:10

By default, the ensemble dimension "member" is derived from the "ensemble.member" key. This key itself is extracted from the "number" GRIB key.

In the GRIB listing above we can see the usual meaning of the GRIB metadata key "number" (and the related "numberOfForecastsInEnsemble") is overridden by "quantile". As a result, the ensemble dimension "member" is no longer applicable.

For this reason, we must:

declare "quantile" as an extra dimension, and
remove the predefined ensemble dimension "member", since it would otherwise conflict with the "quantile" dimension.

[8]:

ds3 = ds_fl2.to_xarray(
    squeeze=False,
    extra_dims="metadata.quantile",
    drop_dims="member",
    add_earthkit_attrs=False,
)
ds3

Xarray engine: extra dimensions¶

2D wave spectra example¶

Quantiles in a probabilistic forecast¶

The option ensure_dims vs extra_dims¶

The option `ensure_dims` vs `extra_dims`¶