Xarray engine: level options

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 “grib” we have the following mappings:

  • level role: “level”

  • level_type role: “typeOfLevel”

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

  • level role: “levelist”

  • level_type role: “levtype”

level_dim_mode=level

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

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

[1]:

import earthkit.data as ekd
ds_fl = ekd.from_source("sample", "pl.grib")
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:
    class:        od
    stream:       oper
    levtype:      pl
    type:         fc
    expver:       0001
    date:         20240603
    time:         0
    domain:       g
    number:       0
    Conventions:  CF-1.8
    institution:  ECMWF

If we switch to the “grib” to profile the key defining the level dimension will be “level”.

[2]:

ds_xr = ds_fl.to_xarray(profile="grib")
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:
    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")
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) <U5 80B '137ml' '500pl' ... '90ml'
  * 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:
    class:        od
    stream:       oper
    levtype:      ml
    type:         fc
    expver:       0001
    date:         20240603
    time:         0
    domain:       g
    levelist:     137
    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")
ds_xr = ds_fl.to_xarray(profile="grib", level_dim_mode="level_per_type", squeeze=False)
ds_xr

[4]:

<xarray.Dataset> Size: 1MB
Dimensions:                  (number: 1, forecast_reference_time: 4, step: 2,
                              surface: 1, latitude: 19, longitude: 36,
                              isobaricInhPa: 6)
Coordinates:
  * number                   (number) int64 8B 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
  * isobaricInhPa            (isobaricInhPa) int64 48B 300 400 500 700 850 1000
  * 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:
    2t                       (number, forecast_reference_time, step, surface, latitude, longitude) float64 44kB ...
    msl                      (number, forecast_reference_time, step, surface, latitude, longitude) float64 44kB ...
    r                        (number, forecast_reference_time, step, isobaricInhPa, latitude, longitude) float64 263kB ...
    t                        (number, forecast_reference_time, step, isobaricInhPa, latitude, longitude) float64 263kB ...
    u                        (number, forecast_reference_time, step, isobaricInhPa, latitude, longitude) float64 263kB ...
    v                        (number, forecast_reference_time, step, isobaricInhPa, latitude, longitude) float64 263kB ...
    z                        (number, forecast_reference_time, step, isobaricInhPa, latitude, longitude) float64 263kB ...
Attributes:
    Conventions:  CF-1.8
    institution:  ECMWF
[ ]: