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/`` **and** ``co2/``, not one of them. lair adds the gas and the version. * :meth:`~lair.noaa.CarbonTracker.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. .. _carbontracker-data: 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: .. code-block:: text $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 -------- :class:`~lair.noaa.CarbonTrackerCH4` takes the version (``CT-CH4-2025`` by default) and the folder, as ``carbon_tracker_directory`` or ``$LAIR_CARBONTRACKER_DIR`` (see :ref:`data-locations`): .. code-block:: ipython 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) :meth:`~lair.noaa.CarbonTracker.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``: .. code-block:: ipython 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: .. code-block:: ipython 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 :meth:`~lair.noaa.CarbonTracker.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. .. _carbontracker-background: Background ---------- :meth:`~lair.noaa.CarbonTracker.background` samples the points and averages them: .. code-block:: ipython 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 ---- :class:`~lair.noaa.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 :ref:`data-cache`), 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 :mod:`multiprocessing` asks for: .. code-block:: python 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 :func:`lair.parallel.parallelize`, which may not start processes of its own.