Sample CarbonTracker at points#
This example downloads one day of NOAA’s CarbonTracker-CH4, samples it at four points west of Salt Lake City, and averages them into a background. Two rules come out of it:
LAIR_CARBONTRACKER_DIR is the folder that holds
ch4/andco2/, not one of them. lair adds the gas and the version.background()is the mean mole fraction at a set of points, in ppm, such as the ends of STILT back trajectories.
Note
This page does not run when the docs build. It downloads a 35 MB file from NOAA’s FTP server. The output below was recorded from one run of this code on 2026-10-29, with lair 2026.12.11.dev9+g55e932b18.
The data#
CarbonTracker-CH4 and CarbonTracker (CO2) are NOAA’s global models of methane and carbon dioxide. Their mole fraction files hold one day each: the gas, and the height of each model level, on a 3 by 2 degree global grid (CO2 also on a 1 by 1 degree grid over North America). lair reads them in the folders of NOAA’s FTP server:
$LAIR_CARBONTRACKER_DIR/
ch4/
CT-CH4-2025/
molefractions/2020/01/CTCH4_2025.molefrac_glb3x2_2020-01-15.nc
co2/
CT2019B/
molefractions/co2_total/CT2019B.molefrac_nam1x1_2015-06-01.nc
The folder of a version needs one file for each day. If two files cover one day,
for example the same day from two releases (CTCH4_2024.molefrac_... and
CTCH4_2025.molefrac_...), the molefractions attribute raises a
ValueError that names the day and both files: it reads every file of
the folder, and would read the day twice. Move one release’s files out of the
folder. sample and background take the file that comes last in name
order for a day, and so do not stop.
Download#
CarbonTrackerCH4 takes the version (CT-CH4-2025 by
default) and the folder, as carbon_tracker_directory or
$LAIR_CARBONTRACKER_DIR (see Data locations):
In [1]: from lair.noaa import CarbonTrackerCH4
...:
...: ct = CarbonTrackerCH4(carbon_tracker_directory="carbontracker")
...: ct
Out[1]: CarbonTrackerCH4(version=CT-CH4-2025, directory=carbontracker/ch4/CT-CH4-2025)
download() copies files from NOAA’s FTP server
into that folder. With no arguments it downloads every flux and mole fraction
file of the version (the CT-CH4-2025 mole fractions of 2015 to 2023 alone are
127 GB), so give a pattern:
In [2]: ct.download(sub_dirs=["molefractions"], pattern="*2020-01-15*")
...: [p.as_posix() for p in sorted(ct.directory.rglob("*.nc"))]
Out[2]: ['carbontracker/ch4/CT-CH4-2025/molefractions/2020/01/CTCH4_2025.molefrac_glb3x2_2020-01-15.nc']
That took about five minutes, most of it spent listing the folders on the server.
Sample at points#
The points are a DataFrame with the columns datetime (UTC),
lati and long (degrees), and zagl (meters above ground): the names
of a PYSTILT particle table. Here, four made-up points west of Salt Lake City:
In [3]: import pandas as pd
...:
...: points = pd.DataFrame(
...: {
...: "datetime": pd.to_datetime(["2020-01-15 17:00"] * 4), # UTC
...: "lati": [41.5, 41.5, 39.5, 39.5],
...: "long": [-114.5, -114.5, -114.5, -114.5],
...: "zagl": [100.0, 2000.0, 100.0, 2000.0],
...: }
...: )
...: sampled = ct.sample(points)
...: sampled[["lati", "zagl", "ct_ch4_ppb", "ct_time", "ct_latitude", "ct_level"]]
Out[3]:
lati zagl ct_ch4_ppb ct_time ct_latitude ct_level
0 41.5 100.0 1953.038326 2020-01-15 16:30:00 41.0 2.0
1 41.5 2000.0 1925.469503 2020-01-15 16:30:00 41.0 8.0
2 39.5 100.0 1983.360137 2020-01-15 16:30:00 39.0 2.0
3 39.5 2000.0 1916.952418 2020-01-15 16:30:00 39.0 8.0
sample() takes the grid cell and time nearest to
each point, and the model level whose layer holds the point’s height (its
zagl plus the height of the ground in the model). ct_ch4_ppb is the
value there; the ct_ columns say which cell, time and level it came from.
Each time step is a mean over 3 hours, labeled by the center of its period
(ct_time: 01:30, 04:30, … UTC) in every release, so a point takes the
mean of the period it is in: 17:00 takes 15:00 to 18:00, labeled 16:30.
A point outside the grid gets NaN, and a point on a day with no file in the
folder is dropped.
Background#
background() samples the points and averages
them:
In [4]: ct.background(points)
Out[4]:
background_ppm sigma_ppm n_endpoints
0 1.944705 0.030022 4
The result is in ppm, for both gases. sigma_ppm is the standard deviation
over the points, and n_endpoints the number of points that had a value.
With by=, the name of a column of the points (by="receptor" in a STILT
run), you get one row per group.
Next#
CarbonTrackerCO2 works the same way for CO2; it takes the
version ("CT2019B", for example) and the grid. The molefractions
attribute opens every file of the version at once and caches that (see
What lair caches), so use sample or background when you need only a
few days.
molefractions opens the files in worker processes, one for each CPU your
job may use: a year of daily CT-CH4-2025 files, opened for the first time with
8 CPUs, took 9 seconds this way and 25 seconds one at a time. Each worker
starts by importing your script again, so a script that reads
molefractions puts its work under the guard Python’s multiprocessing
asks for:
from lair.noaa import CarbonTrackerCH4
def main():
ct = CarbonTrackerCH4()
print(ct.molefractions)
if __name__ == "__main__":
main()
Without it, molefractions raises a RuntimeError that says so. A notebook
needs no guard. parallel_parse=False opens the files one at a time, and so
does molefractions inside a worker process, such as one of
lair.parallel.parallelize(), which may not start processes of its own.