Categorical gridded data

In this example, we will visualise “type of vegetation” data from the ERA5 reanalysis dataset in the C3S Climate Data Store.

import earthkit.data
import earthkit.plots

To retrieve data from the CDS, we use the "cds" source type with earthkit.data.from_source. For more information, see the earthkit-data documentation page on retrieving data from the CDS.

data = earthkit.data.from_source(
    "cds",
    "reanalysis-era5-single-levels-monthly-means",
    {
        "product_type": "monthly_averaged_reanalysis",
        "year": "2018",
        "month": "05",
        "time": "00:00",
        "data_format": "grib",
        "download_format": "unarchived",
        "variable": "type_of_high_vegetation",
    },
)

We can take a look at xarray’s representation of the data to quickly see that the categorical tvh variable (type of high vegetation) has numerical floating point values.

data.to_xarray()

<xarray.Dataset> Size: 4MB
Dimensions:     (number: 1, time: 1, step: 1, surface: 1, latitude: 721,
                 longitude: 1440)
Coordinates:
  * number      (number) int64 8B 0
  * time        (time) datetime64[ns] 8B 2018-05-01
  * step        (step) timedelta64[ns] 8B 00:00:00
  * surface     (surface) float64 8B 0.0
  * latitude    (latitude) float64 6kB 90.0 89.75 89.5 ... -89.5 -89.75 -90.0
  * longitude   (longitude) float64 12kB 0.0 0.25 0.5 0.75 ... 359.2 359.5 359.8
    valid_time  (time, step) datetime64[ns] 8B ...
Data variables:
    tvh         (number, time, step, surface, latitude, longitude) float32 4MB ...
Attributes:
    GRIB_edition:            1
    GRIB_centre:             ecmf
    GRIB_centreDescription:  European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             European Centre for Medium-Range Weather Forecasts
    history:                 2025-02-03T09:13 GRIB to CDM+CF via cfgrib-0.9.1...

xarray.Dataset

• Dimensions:
  • number: 1
  • time: 1
  • step: 1
  • surface: 1
  • latitude: 721
  • longitude: 1440
• Coordinates: (7)
  • number
    (number)
    int64
    0

    long_name :

    ensemble member numerical id

    units :

    1

    standard_name :

    realization

    array([0])

  • time
    (time)
    datetime64[ns]
    2018-05-01

    long_name :

    initial time of forecast

    standard_name :

    forecast_reference_time

    array(['2018-05-01T00:00:00.000000000'], dtype='datetime64[ns]')

  • step
    (step)
    timedelta64[ns]
    00:00:00

    long_name :

    time since forecast_reference_time

    standard_name :

    forecast_period

    array([0], dtype='timedelta64[ns]')

  • surface
    (surface)
    float64
    0.0

    long_name :

    original GRIB coordinate for key: level(surface)

    units :

    1

    array([0.])

  • latitude
    (latitude)
    float64
    90.0 89.75 89.5 ... -89.75 -90.0

    units :

    degrees_north

    standard_name :

    latitude

    long_name :

    latitude

    stored_direction :

    decreasing

    array([ 90.  ,  89.75,  89.5 , ..., -89.5 , -89.75, -90.  ])

  • longitude
    (longitude)
    float64
    0.0 0.25 0.5 ... 359.2 359.5 359.8

    units :

    degrees_east

    standard_name :

    longitude

    long_name :

    longitude

    array([0.0000e+00, 2.5000e-01, 5.0000e-01, ..., 3.5925e+02, 3.5950e+02,
           3.5975e+02])

  • valid_time
    (time, step)
    datetime64[ns]
    ...

    standard_name :

    time

    long_name :

    time

    [1 values with dtype=datetime64[ns]]

• Data variables: (1)
  • tvh
    (number, time, step, surface, latitude, longitude)
    float32
    ...

    GRIB_paramId :

    30

    GRIB_dataType :

    an

    GRIB_numberOfPoints :

    1038240

    GRIB_typeOfLevel :

    surface

    GRIB_stepUnits :

    1

    GRIB_stepType :

    avgua

    GRIB_gridType :

    regular_ll

    GRIB_NV :

    0

    GRIB_Nx :

    1440

    GRIB_Ny :

    721

    GRIB_cfName :

    unknown

    GRIB_cfVarName :

    tvh

    GRIB_gridDefinitionDescription :

    Latitude/Longitude Grid

    GRIB_iDirectionIncrementInDegrees :

    0.25

    GRIB_iScansNegatively :

    0

    GRIB_jDirectionIncrementInDegrees :

    0.25

    GRIB_jPointsAreConsecutive :

    0

    GRIB_jScansPositively :

    0

    GRIB_latitudeOfFirstGridPointInDegrees :

    90.0

    GRIB_latitudeOfLastGridPointInDegrees :

    -90.0

    GRIB_longitudeOfFirstGridPointInDegrees :

    0.0

    GRIB_longitudeOfLastGridPointInDegrees :

    359.75

    GRIB_missingValue :

    9999

    GRIB_name :

    Type of high vegetation

    GRIB_shortName :

    tvh

    GRIB_totalNumber :

    0

    GRIB_units :

    (Code table 4.234)

    long_name :

    Type of high vegetation

    units :

    (Code table 4.234)

    standard_name :

    unknown

    [1038240 values with dtype=float32]

• Indexes: (6)
  • number
    PandasIndex

    PandasIndex(Index([0], dtype='int64', name='number'))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['2018-05-01'], dtype='datetime64[ns]', name='time', freq=None))

  • step
    PandasIndex

    PandasIndex(TimedeltaIndex(['0 days'], dtype='timedelta64[ns]', name='step', freq=None))

  • surface
    PandasIndex

    PandasIndex(Index([0.0], dtype='float64', name='surface'))

  • latitude
    PandasIndex

    PandasIndex(Index([  90.0,  89.75,   89.5,  89.25,   89.0,  88.75,   88.5,  88.25,   88.0,
            87.75,
           ...
           -87.75,  -88.0, -88.25,  -88.5, -88.75,  -89.0, -89.25,  -89.5, -89.75,
            -90.0],
          dtype='float64', name='latitude', length=721))

  • longitude
    PandasIndex

    PandasIndex(Index([   0.0,   0.25,    0.5,   0.75,    1.0,   1.25,    1.5,   1.75,    2.0,
             2.25,
           ...
            357.5, 357.75,  358.0, 358.25,  358.5, 358.75,  359.0, 359.25,  359.5,
           359.75],
          dtype='float64', name='longitude', length=1440))

• Attributes: (7)

  GRIB_edition :

  1

  GRIB_centre :

  ecmf

  GRIB_centreDescription :

  European Centre for Medium-Range Weather Forecasts

  GRIB_subCentre :

  0

  Conventions :

  CF-1.7

  institution :

  European Centre for Medium-Range Weather Forecasts

  history :

  2025-02-03T09:13 GRIB to CDM+CF via cfgrib-0.9.10.4/ecCodes-2.38.3 with {"source": "N/A", "filter_by_keys": {}, "encode_cf": ["parameter", "time", "geography", "vertical"]}

From the ERA5 documentation, we know that the types of high vegetation are categorised with the following values:

• 0: No vegetation

• 3: Evergreen needle

• 4: Deciduous needle

• 5: Deciduous broad

• 6: Evergreen broad

• 18: Mixed forest/wood

• 19: Interrupted forest

Using a special Categorical style from earthkit plots, we can easily associate each value in the data with its category by passing the levels argument as a dictionary.

style = earthkit.plots.styles.Categorical(
    levels={
        3: "Evergreen needle",
        4: "Deciduous needle",
        5: "Deciduous broad",
        6: "Evergreen broad",
        18: "Mixed forest/wood",
        19: "Interrupted forest",
    },
    colors=[
        "#33cc33",
        "#ffd700",
        "#ff9900",
        "#009933",
        "#0066cc",
        "#cc6600",
    ],
)

Now we can plot our data with this style:

chart = earthkit.plots.Map()

chart.grid_cells(data, style=style)

chart.title("ERA5 {variable_name!l} - {time:%B %Y}")

chart.coastlines(resolution="low")
chart.gridlines()

chart.legend(location="bottom", label="{variable_name}", ncols=3)

chart.show()