Variables¶
The registry in fluxatlas.variables is keyed by a canonical key: TA, PREC, NEE, and so
on. The metrics, badges and day tests are written against that key, and the column that supplies it
is resolved per file. The tables below are generated from the registry when the documentation is
built, so they cannot state a unit the package does not use.
What the registry describes¶
Key |
Variable |
Unit |
A span is its |
Warns under |
|---|---|---|---|---|
|
Air temperature |
°C |
mean |
50 % |
|
Precipitation |
mm |
total |
50 % |
|
Incoming shortwave radiation |
W m⁻² |
mean |
50 % |
|
Vapour pressure deficit |
kPa |
mean |
50 % |
|
Relative humidity |
% |
mean |
50 % |
|
Soil water content |
% |
mean |
50 % |
|
Net ecosystem exchange |
g C m⁻² |
total |
20 % |
|
Gross primary productivity |
g C m⁻² |
total |
20 % |
|
Ecosystem respiration |
g C m⁻² |
total |
20 % |
|
Latent heat flux |
W m⁻² |
mean |
20 % |
|
Sensible heat flux |
W m⁻² |
mean |
20 % |
“A span is its” says how a month or a season is summarised: air temperature is a mean, carbon is a total. “Warns under” is the measured share below which a span is marked as leaning on the gap-filling. Coverage sets out the two lines and why they differ.
What each one is¶
TA— Air temperature [°C]Air temperature. The variable most of the calendar’s structure is built on: the growing season, the frost boundaries and the degree-day sum are all taken from it.
PREC— Precipitation [mm]Precipitation as a per-record total. This variable sums rather than averages: a monthly figure is a total, and a record with no measurement contributes nothing to it rather than being treated as zero.
SW_IN— Incoming shortwave radiation [W m⁻²]Incoming shortwave radiation. The clear and overcast day tests are taken against the percentiles for the date rather than a fixed threshold, so a bright winter day counts as one.
VPD— Vapour pressure deficit [kPa]Vapour pressure deficit, the atmosphere’s evaporative demand. Physically the combination of temperature and humidity that closes stomata, which is why it is an axis of the composite and relative humidity is not.
RH— Relative humidity [%]Relative humidity. Kept for the saturation test - a mean of 95 % or more is the tower inside cloud or fog - rather than as an axis of the composite, where vapour pressure deficit carries the same information in a physically meaningful form.
SWC— Soil water content [%]Volumetric soil water content of the shallowest reported layer. The limb of a drought that the atmosphere’s demand acts on, and the slowest of the axes to recover.
NEE— Net ecosystem exchange [g C m⁻²]Net ecosystem exchange of CO₂, signed by the micrometeorological convention: negative is uptake by the ecosystem, positive is release to the atmosphere. The monthly figure is the total, so a month reads directly as the carbon the site gained or lost.
GPP— Gross primary productivity [g C m⁻²]Gross primary productivity: the carbon fixed by photosynthesis, as a positive quantity. Not measured but partitioned out of the net flux, so its quality is the quality of the net flux it came from.
RECO— Ecosystem respiration [g C m⁻²]Ecosystem respiration: the carbon returned by plant and soil respiration, as a positive quantity. The other half of the partitioned net flux, and the term that keeps rising through a warm night when photosynthesis has stopped.
LE— Latent heat flux [W m⁻²]Latent heat flux, the energy carried away as water vapour. The evaporative half of the surface energy balance, and the term that collapses when the soil runs dry while the atmosphere’s demand does not.
H— Sensible heat flux [W m⁻²]Sensible heat flux, the energy carried away as warm air. It takes over from the latent flux as soil water is exhausted, which is why the two are worth reading against each other rather than on their own.
Which columns supply them¶
Resolution goes by name, in the order listed, with the factor that converts onto the canonical unit. The first candidate present in the file wins.
Key |
Columns, in preference order |
Quality flags |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A variable whose column is not among its candidates is read by naming the column. The canonical key still has to be one of the above.
The carbon fluxes¶
Three decisions here are settled, and each shows up in the tables.
Carbon is a total in g C m⁻², not a mean of a rate. Each candidate carries the conversion
1e-6 × 1800 s × 12.011 g mol⁻¹ from µmol CO₂ m⁻² s⁻¹, and a month is summed. A tile then reads as
the carbon the site gained or lost. The sum preserves gaps, as precipitation already did: a record
with no measurement contributes nothing rather than counting as zero. LE and H stay in W m⁻²
and average.
NEE resolves VUT_REF before CUT_REF. Over a record of decades, a per-year u* threshold
is the better default.
GPP and RECO resolve nighttime (Reichstein) partitioning before daytime (Lasslop), as one
canonical key each rather than four. Neither is measured, since both are partitioned out of the net
flux, so both take their quality flag from the NEE they came from. That is why their flag lists
name NEE_*_QC columns.
The resolved column is printed on the page, in the bottom-right corner of every month tile. A FULLSET file carries a dozen variants of the same flux, and a reader cannot infer from the title which one produced a number.
Sign convention, and the rank that follows from it¶
The convention is the micrometeorological one: negative NEE is uptake. Green is uptake and red is
release everywhere on the page, and NEE diverges about zero rather than about the record mean,
because the convention makes zero the meaningful boundary.
That makes NEE the one variable ranked from the negative end. Ranked from the top like the
others, the largest carbon sink would come out last of its calendar month. So rank 1 is the record
sink, the record-sink and record-source badges are the other way round from every other record
badge, and the month tile prints “(1st = largest net uptake)”. That phrase is generated from the
same registry field that sets the ranking, so a variable cannot be ranked one way and described the
other.
The page writes the direction out¶
A figure of 66 g C m⁻² and a departure of +75 state a convention rather than a fact, and say
the opposite of the truth to a reader who assumes more is better. So the direction is written
beside every one of them, in words:
Net CO₂ exchange, total 66 g C m⁻²
net release · ± 100 g C m⁻² (random and u* threshold) · 75 g C m⁻² less uptake than normal
· 15th of 21 years (1st = largest net uptake) · 52 % measured
Two rules decide the wording:
The noun follows the normal, not the value. The same
+75 g C m⁻²is less uptake for a July that is normally a sink and more release for a January that is normally a source.Within a quarter of a standard deviation, a departure is neither. It reads “about the same uptake as normal”, because “2 g C m⁻² less uptake than normal” is a distinction without a difference next to the one-standard-deviation line every badge is defined at.
The words come from a sign field on the registry entry, so a later variable whose zero is
meaningful is covered by adding the field rather than by naming NEE in the renderer.
The same rule fixed two badges that had assumed the sign. Rank 1 is the largest uptake only where the calendar month is a sink at all; where it is a source in every year of the record, rank 1 is the smallest release. The record badges are therefore Best carbon balance on record and Worst carbon balance on record, and the departure badges are Shifted toward uptake and Shifted toward release, which hold whichever side of zero the month sits on.
Adding a variable¶
Add an entry to VARIABLES in fluxatlas.variables. To be colourable on the grid it also
needs a metric in build.METRICS, and to earn badges it needs rules in build.BADGES. Neither is
required. A variable with neither is still read, still shown in the day panel, still counted in
coverage.
Ask what a one-variable build does with it, then open a build of that variable alone in a browser. Selection explains why the Python suite cannot catch that class of problem.