Draw a map of an inventory#

This example draws a map of EDGAR’s methane emissions over Utah in 2022, adds state lines and tick labels, outlines the grid cells, and puts a locator map, a small map of where it is, in a corner. It ends with a field that is not an inventory. Three rules come out of it:

  • Inventory.plot averages every time step, and reads all of them. For EDGAR v8’s 53 years that takes about a minute. Pass time= to draw one (see Plot one year).

  • lair draws the field, and you add the map. plot returns a cartopy axes with only the field on it. State lines and coastlines are cartopy features, and add_latlon_ticks() writes the tick labels in degrees (see State lines and tick labels).

  • The map helpers take an extent, [west, east, south, north]. clip takes one too, or a bbox (the inventory example has its order). bbox2extent() converts.

Note

This page does not run when the docs build. It needs the geo and science extras (see Optional dependencies), EDGAR’s files, and the internet the first time cartopy draws a feature. The output and the figures below were recorded from one run of this code on 2026-10-29, with lair 2026.12.11.dev9+g55e932b18. The last figure, the made-up footprint with its locator map, was drawn again on 2026-10-30.

The data#

EDGAR v8’s methane files, laid out as in the inventory example, under LAIR_INVENTORY_DIR (see Data locations). Drawing a map needs no ESMF, which the inventory example needs to regrid.

Plot one year#

plot() draws total_emissions: the sum of the sectors in each cell, a flux in kg m-2 s-1. With no time it first takes the mean over every time step, so it reads every file. Here that is the 53 years of EDGAR v8’s methane, on the whole globe, and it takes about a minute:

In [1]: import time
   ...:
   ...: from lair.inventories import EDGARv8
   ...:
   ...: inv = EDGARv8("CH4")
   ...:
   ...: t0 = time.time()
   ...: ax = inv.plot()
   ...: print(f"mean of every year: {time.time() - t0:.0f} s")
mean of every year: 41 s

time picks one step instead: an integer position (-1 is the last), or a label such as "2022-01-01". EDGAR’s annual steps are labeled by the start of the year (see Total an inventory over a region). Reading one year is far quicker:

In [2]: t0 = time.time()
   ...: ax = inv.plot(time="2022-01-01")
   ...: print(f"2022 only: {time.time() - t0:.0f} s")
2022 only: 3 s

sector= draws one sector instead of the total. Use a name from inv.data.data_vars, spelled as it is there ("Power_Industry").

State lines and tick labels#

A whole-globe map is no use for Utah, so clip first. This extent, in degrees and in the order the map helpers want, holds 60 by 60 cells of 0.1 degrees:

In [3]: import cartopy.feature as cfeature
   ...:
   ...: from lair import geo
   ...:
   ...: extent = [-114.5, -108.5, 36.5, 42.5]  # west, east, south, north
   ...: utah = inv.clip(extent=extent)
   ...: utah.data.sizes
Out[3]: Frozen({'time': 53, 'lat': 60, 'lon': 60})

plot passes its other arguments to xarray’s plot. cmap picks the colors, and robust=True sets the color range from the 2nd to the 98th percentile of the values, so the few largest sources do not set it. xarray titles the plot with the scalar coordinates it finds (time = 2022-01-01, spatial_ref = 0), so set a title of your own. plot returns the axes, and add_feature and add_latlon_ticks() draw on it:

In [4]: ax = utah.plot(time="2022-01-01", robust=True, cmap="YlOrRd")
   ...: ax.set_title("EDGAR v8 methane, 2022")
   ...: ax.add_feature(cfeature.STATES, edgecolor="black", facecolor="none")
   ...: geo.add_latlon_ticks(ax, extent)
   ...: ax.figure.savefig("maps_inventory.png", dpi=100, bbox_inches="tight")
A map of Utah in 2022 in 0.1 degree cells, with state lines and tick labels in degrees. Methane is highest along the Wasatch Front and in the northeast, with a few isolated sources elsewhere.

cartopy downloads the state lines from Natural Earth the first time it draws them, and prints a DownloadWarning. That needs the internet once: cartopy keeps the file in its data folder and reads it from there afterward. The size of that folder, in megabytes, after the map above:

In [5]: from pathlib import Path
   ...:
   ...: import cartopy
   ...:
   ...: data_dir = Path(cartopy.config["data_dir"])
   ...: round(sum(f.stat().st_size for f in data_dir.rglob("*") if f.is_file()) / 1e6, 1)
Out[5]: 36.4

ax.coastlines() draws a coast in the same way. add_latlon_ticks needs a rectangular map such as the PlateCarree one plot makes; on a projected axes (Lambert, for example) it raises RuntimeError: Cannot handle non-rectangular coordinate systems.

To draw on axes of your own, such as a panel of a larger figure or a projected map, pass ax=. plot draws the inventory in longitude and latitude and cartopy transforms it, so any cartopy axes works.

The grid#

plot_grid() outlines the cells of a grid on the axes you give it. It draws with xarray’s plot, which adds a colorbar, and passes its other arguments on, so add_colorbar=False leaves the colorbar out. Here it outlines the Salt Lake Valley box of the inventory example over a map of its emissions. A small map has many close ticks, so x_rotation=45 tilts the longitude labels:

In [6]: slv_extent = [-112.3, -111.7, 40.4, 41.0]
   ...: slv = inv.clip(extent=slv_extent)
   ...: ax = slv.plot(time="2022-01-01", robust=True, cmap="YlOrRd")
   ...: ax.set_title("EDGAR v8 methane, 2022")
   ...: geo.plot_grid(slv.data, ax=ax, add_colorbar=False)
   ...: geo.add_latlon_ticks(ax, slv_extent, x_rotation=45)
   ...: ax.figure.savefig("maps_grid.png", dpi=100, bbox_inches="tight")
The Salt Lake Valley in 2022 in six by six cells, each outlined in black, with tick labels in degrees.

With no ax, plot_grid makes a map of its own. Give it extent= in longitude and latitude to set the view, and crs= (an EPSG code such as 5070, or a cartopy projection) to draw on a projected map; the extent is still in degrees.

Another field, and where it is#

Any DataArray with lat and lon coordinates can be drawn on the same kind of map, so a footprint or a model field gets state lines, tick labels and a grid in the same way. With xarray’s own plot, pass transform= to say that the coordinates are degrees, as Inventory.plot does for you. Here is a made-up footprint on a 0.01 degree grid from generate_regular_grid(), longer north to south than east to west, around a point in the Salt Lake Valley:

In [7]: import cartopy.crs as ccrs
   ...: import matplotlib.pyplot as plt
   ...: import numpy as np
   ...: from matplotlib.colors import LogNorm
   ...:
   ...: grid = geo.generate_regular_grid(-112.2, -111.5, 0.01, 40.4, 41.0, 0.01, x_label="lon", y_label="lat")
   ...: east = (grid.lon + 111.85) * np.cos(np.deg2rad(40.77))  # degrees from the point
   ...: north = grid.lat - 40.77
   ...: sx, sy = 0.04, 0.12  # widths of the plume, in degrees
   ...: footprint = 1e-3 * np.exp(-(east**2 / (2 * sx**2) + north**2 / (2 * sy**2)))
   ...: footprint.sizes
Out[7]: Frozen({'lon': 70, 'lat': 60})

add_locator_map() adds a locator map, a small map of where the main map is, inside the main map. It takes the main map’s axes, its extent and the CRS of that extent. The locator map shows the western United States (Natural Earth land, ocean and state lines) in the upper right corner, and outlines the main extent in red. locator_extent sets its view, in degrees; bounds its position, as fractions of the main axes (Axes.inset_axes’s rectangle, (left, bottom, width, height)); locator_crs its projection (an Albers equal-area map by default); color and linewidth the outline; fill=True fills the box with color; scale is the Natural Earth scale of the land, ocean and states ("50m" by default, "110m" is coarser and quicker to draw):

In [8]: fig, ax = plt.subplots(figsize=(6, 5), subplot_kw={"projection": ccrs.PlateCarree()})
   ...: footprint.plot(ax=ax, x="lon", y="lat", transform=ccrs.PlateCarree(), norm=LogNorm(vmin=1e-8, vmax=1e-3))
   ...: ax.set_title("A made-up footprint")
   ...: main_extent = [-112.2, -111.5, 40.4, 41.0]
   ...: geo.add_latlon_ticks(ax, main_extent)
   ...: geo.add_locator_map(ax, main_extent, ccrs.PlateCarree())
   ...: fig.savefig("maps_footprint.png", dpi=100, bbox_inches="tight")
A made-up footprint over the Salt Lake Valley, a bright oval that fades outward on a log color scale, with a small map of the western United States in the upper right corner and a red dot on it marking the main map.

Next#

lair.geo also has add_lat_ticks() and add_lon_ticks(), for a map that needs only one axis labeled.