3. Domains and coordinate reference systems

earthkit-plots makes it simple and convenient to produce maps over any geospatial extent, using whichever map projection works best for your data.

This section covers some of the convenience features provided by earthkit-plots for quickly plotting maps over specific domains, including: - Built-in named domains - Combining multiple domains - Automatic projection selection based on domain extents - Creating new, custom, named domains.

Named domains

The most strightforward way of specifying a map domain is through passing a named domain via the domain argument to the Map class, or to the Figure.add_map() method. The valid named domains that can be used with earthkit-plots include: - Named countries which exist in Natural Earth’s Admin 0 countries dataset, e.g. "France" - Continents, e.g. "Africa" - A named domain packaged up with your style library of choice (see builtin domain for a list of named domains included in the default earthkit-plots distribution) - None (default), which will make your map use the domain and projection of the first data that you plot on it (or global equirectangular if no data is plotted).

NOTE: The domain argument is also a valid argument to all quickmap functions, so you can still specify domains in exactly the same way as in these examples if you are using the quickmap module - e.g. qmap.plot(data, domain=”Europe”).

Named domains will also come with their own default coordinate reference system, designed to optimise the map projection of the given domain. In the following examples, we have included in each plot title both the name of the domain and its coordinate refence system to help demonstrate this more clearly. Note that you can use the magic format strings {domain} and {crs} in plot titles to automatic extract this information!

This first example demonstrates producing a plot over Europe:

import earthkit.plots

chart = earthkit.plots.Map(domain="Europe")

# Convenient way to add land, coastlines, borders & gridlines
chart.standard_layers()

# Domains & CRSs can be included in title templates
chart.title("{domain} on a {crs} projection")

chart.show()

You can also combine different named domains by passing a list of names as the domain argument.

chart = earthkit.plots.Map(domain=["Spain", "France"])
chart.standard_layers()
chart.title("{domain} on a {crs} projection")
chart.show()

User-specified domains

You can of course also specify your own custom domains. The easiest way to do this is by passing a list of latitude-longitude extents as the domain argument, in the order [longitude_min, longitude_max, latitude_min, latitude_max]. Notice that by default, earthkit-plots will attempt to find the best projection for your custom domain - we’ll explore how to specify your own projections in the next part of this tutorial.

By default, a custom domain specified as a list of extents will format to a list of latitud and longitude extremes in a plot title.

chart = earthkit.plots.Map(domain=[30, 70, 0, 40])
chart.standard_layers()
chart.title("{domain} on a {crs} projection")
chart.show()

Coordinate reference systems

In all of the previous examples in this notebook, we have used the default coordinate reference system provided by earthkit plots, for both named domains and custom domains. We can make use of cartopy to provide configurable coordinate reference system if we would like to customise our plots further.

Let’s reproduce the Europe example above, but use a NorthPolarStereo CRS from cartopy instead of the default LambertAzimuthalEqualArea:

import cartopy.crs as ccrs

crs = ccrs.NorthPolarStereo(central_longitude=10)

chart = earthkit.plots.Map(domain="Europe", crs=crs)

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

chart.title("{domain} on a {crs} projection")
chart.show()

You can combine the crs argument with any domain argument - even when using quickmap!

More complex domains

Sometimes you might find that you need to do something a bit more complex with domains, like specifying the extents in CRS coordinates rather than latitudes and longitudes. Under-the-hood, earthkit-plots makes use of a Domain class, which can be built manually and used as another option for the domain argument to the map constructor.

Here’s an example of creating a custom, named domain for Antarctica, with the extents defined in the coordinates of the South Polar Stereographic coordinate reference system.

from earthkit.plots.geo import domains

antarctic_domain = domains.Domain(
    [-4000000, 4000000, -4000000, 4000000],
    crs=ccrs.SouthPolarStereo(),
    name="Antarctica",
)

chart = earthkit.plots.Map(domain=antarctic_domain)
chart.land()
chart.coastlines()
chart.gridlines()

chart.title("{domain} on a {crs} projection")
chart.show()