Polygon coverage explorer

In this notebook you will see how to:

• use Polytope to retrieve a country cut-out of Portugal

• create a point cloud plot of the retrieved fields

Components of earthkit

This tutorial uses the following earthkit components - click any logo to open the package documentation:

1. Data extraction

We generate the country polygon for Portugal using earthkit-geo, then retrieve data within that polygon with Polytope and convert to xarray.

import earthkit.data as ekd
from earthkit.geo.cartography import country_polygons

coords = country_polygons("Portugal")

request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : -1,
    "time" : "1200",
    "levtype" : "sfc",
    "expver" : 1,
    "domain" : "g",
    "param" : "167/169",
    "number" : "1",
    "step": "0",
    "feature": {
        "type": "polygon",
        "shape": coords
    },
}

ds = ekd.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int').to_xarray()
ds

<xarray.Dataset> Size: 54kB
Dimensions:    (datetimes: 1, number: 1, steps: 1, points: 1118)
Coordinates:
  * datetimes  (datetimes) <U20 80B '2026-04-14T12:00:00Z'
  * number     (number) int64 8B 1
  * steps      (steps) int64 8B 0
  * points     (points) int64 9kB 0 1 2 3 4 5 ... 1112 1113 1114 1115 1116 1117
    latitude   (points) float64 9kB 36.87 36.87 36.94 ... 42.14 42.21 42.21
    longitude  (points) float64 9kB 352.1 352.2 351.2 ... 351.7 351.6 351.7
    levelist   (points) float64 9kB 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0
Data variables:
    2t         (datetimes, number, steps, points) float64 9kB 288.4 ... 284.7
    ssrd       (datetimes, number, steps, points) float64 9kB 0.0 0.0 ... 0.0
Attributes:
    class:          od
    Forecast date:  2026-04-14T12:00:00Z
    domain:         g
    expver:         0001
    levtype:        sfc
    number:         1
    step:           0
    stream:         enfo
    type:           pf
    date:           2026-04-14T12:00:00Z

xarray.Dataset

• Dimensions:
  • datetimes: 1
  • number: 1
  • steps: 1
  • points: 1118
• Coordinates: (7)
  • datetimes
    (datetimes)
    <U20
    '2026-04-14T12:00:00Z'

    array(['2026-04-14T12:00:00Z'], dtype='<U20')

  • number
    (number)
    int64
    1

    array([1])

  • steps
    (steps)
    int64
    0

    array([0])

  • points
    (points)
    int64
    0 1 2 3 4 ... 1114 1115 1116 1117

    array([   0,    1,    2, ..., 1115, 1116, 1117], shape=(1118,))

  • latitude
    (points)
    float64
    36.87 36.87 36.94 ... 42.21 42.21

    array([36.87170393, 36.87170393, 36.94200269, ..., 42.14411149,
           42.21441026, 42.21441026], shape=(1118,))

  • longitude
    (points)
    float64
    352.1 352.2 351.2 ... 351.6 351.7

    array([352.06578947, 352.18421053, 351.22529644, ..., 351.72262774,
           351.57894737, 351.71052632], shape=(1118,))

  • levelist
    (points)
    float64
    0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0

    array([0., 0., 0., ..., 0., 0., 0.], shape=(1118,))

• Data variables: (2)
  • 2t
    (datetimes, number, steps, points)
    float64
    288.4 288.2 289.6 ... 285.7 284.7

    type :

    Parameter

    units :

    K

    long_name :

    2t

    array([[[[288.35171509, 288.15054321, 289.61734009, ..., 284.48257446,
              285.71694946, 284.69351196]]]], shape=(1, 1, 1, 1118))

  • ssrd
    (datetimes, number, steps, points)
    float64
    0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0

    type :

    Parameter

    units :

    J m**-2

    long_name :

    ssrd

    array([[[[0., 0., 0., ..., 0., 0., 0.]]]], shape=(1, 1, 1, 1118))

• Indexes: (4)
  • datetimes
    PandasIndex

    PandasIndex(Index(['2026-04-14T12:00:00Z'], dtype='object', name='datetimes'))

  • number
    PandasIndex

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

  • steps
    PandasIndex

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

  • points
    PandasIndex

    PandasIndex(Index([   0,    1,    2,    3,    4,    5,    6,    7,    8,    9,
           ...
           1108, 1109, 1110, 1111, 1112, 1113, 1114, 1115, 1116, 1117],
          dtype='int64', name='points', length=1118))

• Attributes: (10)

  class :

  od

  Forecast date :

  2026-04-14T12:00:00Z

  domain :

  g

  expver :

  0001

  levtype :

  sfc

  number :

  1

  step :

  0

  stream :

  enfo

  type :

  pf

  date :

  2026-04-14T12:00:00Z

2. Plot the extracted data

The data can then be easily plotted as a point cloud using earthkit-plots.

import earthkit.plots as ekp

chart = ekp.Map(domain="Portugal")
chart.point_cloud(ds['2t'])

chart.coastlines()
chart.borders()
chart.gridlines()

chart.title("{variable_name} (number={number})")

chart.legend()

chart.show()

WARNING:earthkit.data.readers.xarray.flavour:Coordinate points not supported
axis='', name='points', long_name='', standard_name='', units

<xarray.DataArray 'points' (points: 1118)> Size: 9kB
array([   0,    1,    2, ..., 1115, 1116, 1117], shape=(1118,))
Coordinates:
    datetimes  <U20 80B '2026-04-14T12:00:00Z'
    number     int64 8B 1
    steps      int64 8B 0
  * points     (points) int64 9kB 0 1 2 3 4 5 ... 1112 1113 1114 1115 1116 1117
    latitude   (points) float64 9kB 36.87 36.87 36.94 ... 42.14 42.21 42.21
    longitude  (points) float64 9kB 352.1 352.2 351.2 ... 351.7 351.6 351.7
    levelist   (points) float64 9kB 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0

<class 'numpy.ndarray'> (1118,)
WARNING:earthkit.data.readers.xarray.flavour:Coordinate points not supported
axis='', name='points', long_name='', standard_name='', units

<xarray.DataArray 'points' (points: 1118)> Size: 9kB
array([   0,    1,    2, ..., 1115, 1116, 1117], shape=(1118,))
Coordinates:
    datetimes  <U20 80B '2026-04-14T12:00:00Z'
    number     int64 8B 1
    steps      int64 8B 0
  * points     (points) int64 9kB 0 1 2 3 4 5 ... 1112 1113 1114 1115 1116 1117
    latitude   (points) float64 9kB 36.87 36.87 36.94 ... 42.14 42.21 42.21
    longitude  (points) float64 9kB 352.1 352.2 351.2 ... 351.7 351.6 351.7
    levelist   (points) float64 9kB 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0

<class 'numpy.ndarray'> (1118,)