Data locations#
lair has no built-in data paths. Functions and classes that read from a
local data archive take an explicit directory argument and otherwise fall back
to an environment variable. The last column links to the folder layout each
variable expects:
Variable |
Used by |
Folder layout |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
cached results (default |
For example:
export LAIR_INVENTORY_DIR=/path/to/inventories
Importing lair reads none of these folders. A variable is read when you call code
that needs it, so you can set it in a script or notebook after import lair,
and a missing one raises a ValueError that names it. LAIR_CACHE_DIR is the
exception: it has a default, so a missing one is no error.
Inventory folders#
Each inventory has its own folder below LAIR_INVENTORY_DIR. Its class page
says how the folder is laid out, which files lair reads, and where to download
them: EDGARv7, EDGARv8
(the monthly files), EPAv1,
EPAv2, GFEIv1,
GFEIv2, Vulcan and
WetCHARTs. The inventory example shows EDGAR v8’s annual files.
What needs which data#
You can use lair with no data folder at all. These modules work on what you pass
in, so they need no LAIR_* variable: air, clock, constants,
meteorology, pcaps, plotter, pollutants, records,
transects, parallel and utils, and lair.units (the pint unit
registry). So does background, which also needs the CCG filter and scipy
(see The first import downloads a file). Some of their functions need an extra.
These get data from somewhere else:
inventoriesreadsLAIR_INVENTORY_DIR. lair does not download inventories: get them from their providers (EDGAR, EPA, GFEI, Vulcan, WetCHARTs).soundingsusesLAIR_SOUNDING_DIR. For whenget_soundingsdownloads, see When get_soundings downloads.noaausesLAIR_CARBONTRACKER_DIRandLAIR_GML_DIR. Thedownload()methods ofCarbonTrackerandGMLDatafetch the files from NOAA’s FTP server into them.hrrrreads a public Amazon S3 bucket. It needs the internet and therequests,formatsandgeoextras, and no folder.synopticneeds a Synoptic Data API token, passed astoken=or set asSYNOPTIC_TOKEN, and therequestsextra.
Spelling a pollutant#
Spell a pollutant the way its folder, its file or its formula is spelled. Only a label ignores case. Of the inventories, only EDGAR takes a pollutant: EPA, GFEI and WetCHARTs hold methane, and Vulcan carbon dioxide.
In a folder or file name, the case must match.
EDGARv8("CH4")readsEDGAR/v8/CH4/, the folder as EDGAR names it.EDGARv8("ch4")looks forEDGAR/v8/ch4/, and on Linux, where folder names are case-sensitive, raisesFileNotFoundError.EDGARv7is the same.GMLData("ch4", "uta")builds the file name NOAA uses,ch4_uta_surface-flask_1_ccgg_event.txt, so"CH4"or"UTA"names a file that does not exist. A CarbonTracker version is a folder name too, as NOAA writes it:CT-CH4-2025, notct-ch4-2025.A formula needs its capitals.
molecular_weight()takes"CH4"and raises aFormulaErrorfor"ch4". NOx is the exception: any case gives the mass of NO2. AnInventorybuilt from data you pass in upper-cases a pollutant that has no capital letter ("ch4"becomes"CH4") and keeps one that has any as you typed it ("Ch4"stays, and fails when lair needs its formula).A label ignores case.
lair.pollutants.get_pollutant()takes"ch4","CH4","nox"and"PM25"; it reads no folder.
What lair caches#
One thing: the molefractions attribute of CarbonTrackerCH4
and CarbonTrackerCO2, which opens every file of a version at
once. sample() and background() save nothing, and nothing else in lair
writes to the cache folder. The cache is a file in LAIR_CACHE_DIR, with a
hidden index file beside it:
$LAIR_CACHE_DIR/
carbontracker/
ch4/CT-CH4-2025/molefractions.pkl
co2/CT2019B/molefractions_nam1x1.pkl
lair makes the folder the first time it saves something there, not when it is
imported, so import lair works with a read-only home directory. If the folder
cannot be made, the error names it and LAIR_CACHE_DIR: set the variable to a
folder you can write to, or pass cache=False, which saves nothing.
The file holds how to open the files, not their values: 8 to 15 KB for each daily file, so 3.2 MB for the 366 days of a year, whose files add up to 13 GB. That needs one file for each day (The data says what happens when a day has two).
The file is for one list of files. When the folder gains or loses a file, the next
molefractions adds an entry for the new list, as large as the first, to the
same file, and the old entry stays. To start again, delete the version’s folder in
the cache; lair makes it again the next time.
The entry is also keyed on the code that opens the files. A lair release that
changes how they are opened (the times, the variables kept, how the files are
combined) therefore opens them again the first time, instead of returning what an
older release saved, and that entry is added to the file too. A cache written by
lair 2026.12.11 or earlier is read once more in this way, for each list of files it
holds. What the key does and does not see is in the Notes of
Cacher.
Measured on 2026-10-14, with files of CT-CH4-2025 (36 MB each), CT-CH4-2023 and CT2019B (18 MB).