Xarray engine: vertical dimensions

We can convert a GRIB fieldlist to Xarray with to_xarray(). This notebook discusses the level options used by this method.

The level dimension is based on the dim_roles and level_dim_mode options. The dim_roles are a mapping between predefined dimension roles and metadata keys used to build the given dimensions. With regards to the levels the “level” and “level_type” roles are the ones we need to consider. When profile is None or “earthkit” we have the following mappings:

  • level role: “vertical.level”

  • level_type role: “vertical.level_type”

When profile is “grib” the roles are defined as follows:

  • level role: “metadata.level”

  • level_type role: “metadata.typeOfLevel”

When profile is “mars” the roles are defined as follows:

  • level role: “metadata.levelist”

  • level_type role: “metadata.levtype”

Please, note that when the source is GRIB data the keys prefixed with “metadata.” are the ecCodes GRIB keys.

level_dim_mode=”level”

When level_dim_mode="level" the “level” role defines the level dimension. Since the default profile is “earthkit”, in the example below the level dimension will be derived from the “vertical.level” key.

[1]:

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "pl.grib").to_fieldlist()
ds_xr = ds_fl.to_xarray()
ds_xr



[1]:

<xarray.Dataset> Size: 176kB
Dimensions:                  (forecast_reference_time: 4, step: 2, level: 2,
                              latitude: 19, longitude: 36)
Coordinates:
  * forecast_reference_time  (forecast_reference_time) datetime64[ns] 32B 202...
  * step                     (step) timedelta64[ns] 16B 00:00:00 06:00:00
  * level                    (level) int64 16B 500 700
  * latitude                 (latitude) float64 152B 90.0 80.0 ... -80.0 -90.0
  * longitude                (longitude) float64 288B 0.0 10.0 ... 340.0 350.0
Data variables:
    r                        (forecast_reference_time, step, level, latitude, longitude) float64 88kB ...
    t                        (forecast_reference_time, step, level, latitude, longitude) float64 88kB ...
Attributes:
    Conventions:  CF-1.8
    institution:  ECMWF

If we switch to the “mars” to profile, the key defining the level dimension will be “metadata.levelist”.

By default, the dimensions related to dimension roles are named after the roles. So, although the level dimension was generated from the “metadata.levelist” GRIB key, the dimension name is still “level”.

[2]:

ds_xr = ds_fl.to_xarray(profile="mars")
ds_xr

[2]:

<xarray.Dataset> Size: 176kB
Dimensions:                  (forecast_reference_time: 4, step: 2, level: 2,
                              latitude: 19, longitude: 36)
Coordinates:
  * forecast_reference_time  (forecast_reference_time) datetime64[ns] 32B 202...
  * step                     (step) timedelta64[ns] 16B 00:00:00 06:00:00
  * level                    (level) int64 16B 500 700
  * latitude                 (latitude) float64 152B 90.0 80.0 ... -80.0 -90.0
  * longitude                (longitude) float64 288B 0.0 10.0 ... 340.0 350.0
Data variables:
    r                        (forecast_reference_time, step, level, latitude, longitude) float64 88kB ...
    t                        (forecast_reference_time, step, level, latitude, longitude) float64 88kB ...
Attributes:
    class:        od
    stream:       oper
    levtype:      pl
    type:         fc
    expver:       0001
    date:         20240603
    time:         0
    domain:       g
    number:       0
    levelist:     500
    Conventions:  CF-1.8
    institution:  ECMWF

level_dim_mode=”level_and_type”

When level_dim_mode="level_and_type" a single dimension called “level_and_type” will be formed by combining the keys assigned to the “level” and “level_type” roles. This option can be used to handle variables available on mutiple level types. The GRIB data in the next example contains both pressure and hybrid (model) level data for the same parameters.

[3]:

ds_fl = ekd.from_source("sample", "mixed_pl_ml.grib").to_fieldlist()
ds_xr = ds_fl.to_xarray(level_dim_mode="level_and_type")
ds_xr



[3]:

<xarray.Dataset> Size: 351kB
Dimensions:                  (forecast_reference_time: 4, step: 2,
                              level_and_type: 4, latitude: 19, longitude: 36)
Coordinates:
  * forecast_reference_time  (forecast_reference_time) datetime64[ns] 32B 202...
  * step                     (step) timedelta64[ns] 16B 00:00:00 06:00:00
  * level_and_type           (level_and_type) <U11 176B '137hybrid' ... '90hy...
  * latitude                 (latitude) float64 152B 90.0 80.0 ... -80.0 -90.0
  * longitude                (longitude) float64 288B 0.0 10.0 ... 340.0 350.0
Data variables:
    t                        (forecast_reference_time, step, level_and_type, latitude, longitude) float64 175kB ...
    u                        (forecast_reference_time, step, level_and_type, latitude, longitude) float64 175kB ...
Attributes:
    Conventions:  CF-1.8
    institution:  ECMWF

level_dim_mode=”level_per_type”

When level_dim_mode="level_per_type" a separate dimensions is added for each level type based on the “level” and “level_type” dimension roles. This option can be used to handle data with variables available on different level types. The GRIB data in the next example contains both surface and an pressure level variables.

[4]:

ds_fl = ekd.from_source("sample", "mixed_pl_sfc.grib").to_fieldlist()
ds_xr = ds_fl.to_xarray(level_dim_mode="level_per_type", squeeze=False)
ds_xr



[4]:

<xarray.Dataset> Size: 1MB
Dimensions:                  (member: 1, forecast_reference_time: 4, step: 2,
                              surface: 1, latitude: 19, longitude: 36,
                              pressure: 6)
Coordinates:
  * member                   (member) <U1 4B '0'
  * forecast_reference_time  (forecast_reference_time) datetime64[ns] 32B 202...
  * step                     (step) timedelta64[ns] 16B 00:00:00 06:00:00
  * surface                  (surface) int64 8B 0
  * latitude                 (latitude) float64 152B 90.0 80.0 ... -80.0 -90.0
  * longitude                (longitude) float64 288B 0.0 10.0 ... 340.0 350.0
  * pressure                 (pressure) int64 48B 300 400 500 700 850 1000
Data variables:
    2t                       (member, forecast_reference_time, step, surface, latitude, longitude) float64 44kB ...
    msl                      (member, forecast_reference_time, step, surface, latitude, longitude) float64 44kB ...
    r                        (member, forecast_reference_time, step, pressure, latitude, longitude) float64 263kB ...
    t                        (member, forecast_reference_time, step, pressure, latitude, longitude) float64 263kB ...
    u                        (member, forecast_reference_time, step, pressure, latitude, longitude) float64 263kB ...
    v                        (member, forecast_reference_time, step, pressure, latitude, longitude) float64 263kB ...
    z                        (member, forecast_reference_time, step, pressure, latitude, longitude) float64 263kB ...
Attributes:
    Conventions:  CF-1.8
    institution:  ECMWF
[ ]: