Total an inventory over a region#
This example totals EDGAR’s methane emissions over the Salt Lake Valley, moves them to a finer grid, and checks that the total did not change. Three rules come out of it:
The regional total is
integrate(): the mass emitted over the region in each time step, in kilograms per year here.total_emissionsis not a total over the region: it sums the sectors in each grid cell, and is still a flux per area and time.absolute_emissionsis the mass in each cell, sector by sector (see Three sums).The unit does not matter.
integrate()gives the inventory’s own mass unit (here kg). Divide the result, or convert the flux first withconvert_units: the total is the same (see Other units).To change the grid of an inventory, use its own
regridorresample. They are conservative by default, so the total stays the same.
Note
This page does not run when the docs build. It needs EDGAR’s files, which are
too large for the docs build, and, for resample and regrid, ESMF,
which the conda route of Installation installs (integrate() works
without it). The output below was recorded from one run of this code, with
ESMF, on 2026-10-29, with lair 2026.12.11.dev9+g55e932b18.
The data#
EDGAR v8.0 publishes global
maps of methane emissions at 0.1 degrees, one file per sector and year, from
1970 to 2022. Download the annual flux files (flx_nc, in kg m-2 s-1) of
every CH4 sector, and unzip each sector into a folder of its own:
$LAIR_INVENTORY_DIR/
EDGAR/v8/CH4/
AGS/v8.0_FT2022_GHG_CH4_1970_AGS_flx.nc
v8.0_FT2022_GHG_CH4_1971_AGS_flx.nc
...
ENF/...
...
lair reads every .nc file under CH4/ except those in TOTALS/. Set
LAIR_INVENTORY_DIR to the folder that holds EDGAR/ (see
Data locations), or pass it to the class as inventory_dir=.
Load#
EDGARv8 opens every year of every sector. Each sector
is a variable, and each time step is labeled by the start of its year (January
1). Opening is lazy: lair reads the values only when a result needs them. Opening
all 53 years takes 20 to 50 seconds: when a calculation needs only some, pass
them, as in EDGARv8("CH4", start=2015, end=2022), and lair opens only the
files of those years (both included). This page reads every year.
In [1]: from lair.inventories import EDGARv8
...:
...: inv = EDGARv8("CH4")
...: inv.data.sizes
Out[1]: Frozen({'time': 53, 'lat': 1800, 'lon': 3600})
In [2]: list(inv.data.data_vars)[:4]
Out[2]: ['Solid_waste_landfills', 'Agricultural_soils', 'Agricultural_waste_burning', 'Chemical_processes']
Clip#
clip takes a bounding box as (west, south, east, north), in degrees. “The
Salt Lake Valley” on this page, and on Draw a map of an inventory, is the box in the code
below, 112.3 to 111.7 W and 40.4 to 41.0 N: four numbers, not a boundary read
from a file. Its edges fall on the edges of EDGAR’s cells, so it holds 6 by 6
cells of 0.1 degrees.
In [3]: slv = inv.clip(bbox=(-112.3, 40.4, -111.7, 41.0)) # west, south, east, north
...: slv.data.sizes
Out[3]: Frozen({'time': 53, 'lat': 6, 'lon': 6})
For a region that is not a rectangle, clip(geom=) takes a shapely polygon, with its corners as (lon, lat). This
triangle inside the box gives a smaller grid, 3 by 4 cells. Its cells outside the
triangle stay in the grid, empty (NaN), so they add nothing to a total
(clip() says how a polygon and a box differ at the
edges). The rest of this page uses the box.
In [4]: from shapely.geometry import Polygon
...:
...: triangle = Polygon([(-112.2, 40.5), (-111.8, 40.5), (-112.0, 40.9)])
...: inv.clip(geom=triangle).data.sizes
Out[4]: Frozen({'time': 53, 'lat': 3, 'lon': 4})
Three sums#
An inventory adds up in three ways, and only one of them is the total over the region:
Name |
What it is |
Units here |
Use it for |
|---|---|---|---|
|
the sectors added in each cell: a flux, on |
kg m-2 s-1 |
a map; the flux at a place |
|
each cell’s flux times its area and the length of the time step: a mass,
one variable per sector, on |
kg per cell per year |
the mass in a cell; one sector’s total |
|
|
kg per year |
the total over the region |
The kilograms are the mass unit of the inventory’s flux: the area and the time
cancel. “Per year” is because EDGARv8 loads annual data, one value per year;
with monthly data each value is one month’s mass. The length of a year follows
the calendar (366 days in a leap year).
A flux in each cell: total_emissions#
total_emissions sums the sectors in each cell. Its units attribute shows
that it is still a flux, in kilograms per square meter per second (a spelling
pint reads the same as kg m-2 s-1: unit spellings):
In [5]: slv.total_emissions.attrs["units"]
Out[5]: 'kg/m**2/s'
Do not add it up over the cells: the cells differ in area, so a sum of fluxes is not a mass.
The total: integrate()#
integrate() multiplies each cell’s flux by the
cell’s area and by the length of the time step, then sums the cells and the
sectors. The units attribute of the result is just kg: the mass emitted
over the whole region in one time step, here one year.
integrate() returns a lazy (dask) array: compute() reads the files and
does the work. That took a minute or two here.
In [6]: total = slv.integrate().compute()
...: total.attrs
Out[6]: {'long_name': 'Total Emissions', 'units': 'kg'}
In [7]: total.sel(time=slice("2020", "2022")).to_series() / 1e6 # kg to kt
Out[7]:
time
2020-01-01 22.129474
2021-01-01 22.404489
2022-01-01 22.629266
Freq: YS-JAN, Name: emissions, dtype: float64
So EDGAR puts 22.6 kt of methane in this box in 2022. (kt is only a label
here: do not write it as a unit in code; see Convert a methane flux from moles to mass.)
The mass in each cell: absolute_emissions#
absolute_emissions is the step before the
sum: the mass each cell emitted in each year, one variable per sector. To check
it by hand, take one cell in 2022 (not a leap year): its flux, summed over the
sectors, times its area (gridcell_area, in
km2) times the seconds in the year:
In [8]: from lair.inventories import sum_sectors
...:
...: cell = dict(lat=40.75, lon=-111.95, method="nearest") # one 0.1 degree cell
...:
...: flux = float(slv.total_emissions.sel(time="2022-01-01").sel(**cell)) # kg m-2 s-1
...: area = float(slv.gridcell_area.sel(**cell)) * 1e6 # km2 to m2
...: seconds = 365 * 24 * 3600
...: mass = slv.absolute_emissions.sel(time="2022-01-01").sel(**cell).compute()
...:
...: print(f"by hand: {flux * area * seconds:,.0f} kg")
...: print(f"absolute_emissions: {float(sum_sectors(mass)):,.0f} kg")
by hand: 8,582,388 kg
absolute_emissions: 8,582,388 kg
EDGAR leaves a sector’s cell empty (NaN) where that sector emits nothing.
sum_sectors(), which total_emissions and
integrate() use, skips those, as xarray’s sum does; adding the sectors
with Python’s + or sum gives NaN.
Summed over the cells, each sector gives its own total over the region. Added
together, they are integrate()’s total:
In [9]: by_sector = slv.absolute_emissions.sel(time="2022-01-01").sum(["lat", "lon"]).compute()
...: kt = by_sector.to_pandas() / 1e6 # kg to kt
...: print(kt.sort_values(ascending=False).head().round(3).to_string())
...: print(f"all sectors: {kt.sum():.3f} kt")
Solid_waste_landfills 12.429
Waste_water_handling 5.204
Energy_for_buildings 1.604
Fuel_exploitation_GAS 1.271
Solid_waste_incineration 0.650
all sectors: 22.629 kt
To leave a sector out of a total, pass it to
sum_sectors() as exclude=.
A total adds the sectors as numbers, so they must be in the same unit. EDGAR’s
are. An inventory built from sectors in different units (a dataset whose
variables carry their own units) raises a ValueError from
total_emissions and integrate() that names each sector’s units; convert
them first with convert_units.
Other units#
integrate() keeps the inventory’s mass unit, so divide the result: kg /
1e6 is kt, as above. Converting the flux
first gives the same total. An inventory’s convert_units gives a flux per
year (Gg/km**2/yr) the length of each year, 366 days in 2020 and 365 in
2022, and integrate() takes each value as that year’s worth (the details
are under convert_units()):
In [10]: kg = total.sel(time=["2020-01-01", "2022-01-01"])
...: gg = slv.convert_units("Gg/km**2/yr").integrate().sel(time=["2020-01-01", "2022-01-01"]).compute()
...:
...: (100 * (gg / (kg / 1e6) - 1)).to_series().round(6) # percent
Out[10]:
time
2020-01-01 0.0
2022-01-01 0.0
Name: emissions, dtype: float64
The plain-array convert_units() has no years to go by,
so it uses pint’s year of 365.25 days.
Regrid, and check the total#
resample(0.01) moves the region to a grid of 0.01 degrees (60 by 60 cells).
An inventory’s resample and regrid are conservative by default: each new
cell gets the area-weighted flux of the old cells it overlaps, so flux times
area, and with it the total, stays the same.
In [11]: fine = slv.resample(0.01) # conservative by default
...: fine.data.sizes
Out[11]: Frozen({'time': 53, 'lat': 60, 'lon': 60})
Now compare the 2022 total before and after:
In [12]: fine_total = fine.integrate().compute()
...:
...: before = float(total.sel(time="2022-01-01"))
...: after = float(fine_total.sel(time="2022-01-01"))
...: print(f"before: {before / 1e6:.3f} kt")
...: print(f"after: {after / 1e6:.3f} kt")
...: print(f"change: {100 * (after - before) / before:+.4f} %")
before: 22.629 kt
after: 22.629 kt
change: -0.0005 %
The total changed by 0.0005% (5 parts per million): the mass is kept.
A resolution that does not divide the box still keeps the total. The new grid
covers the whole box: resample(0.25) gives 3 by 3 cells, 0.75 degrees wide,
and the last row and column reach past the box’s edge. They hold only the
emissions that were inside it, so the total is still kept.
Why not lair.geo.resample?#
lair.geo.resample() and lair.geo.regrid() are for any field: a
temperature, a wind speed, a mole fraction. Their default is bilinear
interpolation, which suits a field you read at a point. It reads each value as a
point at its cell’s center and interpolates linearly between those points, so
it does not keep the sum of flux times area.
A flux is different: its total must not change when the grid does. On the box
above, lair.geo.resample with its default lost 6.6% of the 2022 total at
0.01 degrees. The 1,100 new cells along the edges of the box, outside the
outermost cell centers, came out NaN: bilinear interpolation does not reach them.
So send a flux through the inventory’s own regrid or resample, or pass
the method yourself: method="conservative" to lair.geo.regrid, and
regrid_method="conservative" to lair.geo.resample. The two defaults
differ on purpose: lair.geo handles any field, and not every field is
conserved, while an inventory always holds fluxes.
Next#
lair.inventories lists the other inventories (EPA, GFEI, Vulcan,
WetCHARTs) and what each one’s total includes.