WetBulbTracker — Scientific Methodology

A complete specification of every heat-stress metric, algorithm, physical constant, and adjustment used by WetBulbTracker.com.

Last updated: September 2026 · Engine version: Liljegren WBGT (physics epoch 2026-07-alb020)

This document is intended for scientists, clinicians, safety officers, and engineers who need to audit or reproduce the numbers shown in the app. Every formula below is implemented verbatim in the open metrics engine; source-file references are given for each section so the code and this document can be cross-checked line by line.

1. Scope and conventions

• Internal units. Every quantity is computed and stored in SI / metric units: temperature in degrees Celsius (°C), wind in meters per second (m/s), pressure in hectopascals (hPa), shortwave irradiance in watts per square metre (W/m²). Imperial conversion happens only at the display layer, so the calculation engine has a single source of truth.
• Display conversion. °F = °C · 9/5 + 32; mph = (m/s) · 2.236936; km/h = (m/s) · 3.6. The default display unit is chosen from the location's country (°F for the United States, °C elsewhere) and can be overridden.
• Determinism. The metrics engine is a set of pure functions: given the same raw inputs it always returns the same outputs. It performs no I/O and has no dependency on the UI framework.
• Reference temperature for thermodynamics. Energy-balance solvers work in Kelvin (K = °C + 273.15) and pascals (Pa = hPa · 100) internally, converting back to °C for the public result.

Source: src/lib/units.ts, src/lib/metrics/index.ts.

2. Data sources and pipeline

Raw weather fields requested (current conditions): temperature_2m, relative_humidity_2m, apparent_temperature, is_day, wind_speed_10m, surface_pressure, shortwave_radiation, dew_point_2m, uv_index, cloud_cover, precipitation. Wind is requested in m/s. Open-Meteo's underlying model is primarily ECMWF/national NWP blends at roughly 1–11 km resolution.

Freshness. Current conditions are cached for 15 minutes server-side; the forecast and historical archive for 1 hour and 24 hours respectively. A failed upstream request is retried once without cache before erroring.

Solar instant. For "current conditions" the solar geometry (§4) is evaluated at the present UTC instant; the sun moves slowly enough that the ≤15-minute data lag is immaterial. For the forecast strip and map time scrubber, each hour is evaluated at its own true UTC instant.

Source: src/lib/openmeteo.ts, src/app/api/conditions/route.ts.

2.1 Input variables

2.2 When a variable is missing

The provider types every hourly variable as nullable, and a null is not a zero. It matters most for S: with no radiant load the Liljegren globe settles near air temperature, so a fabricated zero reads as a sunless afternoon and moves WBGT by roughly 4 °C — typically a whole band, in the under-warning direction.

So an absent S is replaced by the clear-sky upper bound at that hour's own solar geometry — Haurwitz (1945), GHI = 1098·cos(z)·exp(−0.059/cos(z)) — which is computable from latitude, longitude and time, none of which go missing when the irradiance does. The substitution errs upward: near-exact on a genuinely clear hour, up to about +2.6 °C on a genuinely overcast one. That direction is deliberate. Below the horizon the bound is exactly 0, so a substituted night and a reported night agree.

A reported value is never overridden, zero included: a provider reporting no sun in daylight is believed rather than second-guessed.

Substituted values are marked, and two things decline to act on them — the learned bias correction (§5.9), which is indexed by the provider's reported irradiance, and the accuracy corpus (§5.6), which refuses the sample outright. We will estimate in order to answer; we will not estimate in order to learn.

The reader is told, too. When the sun in a reading was substituted, the card says so under the headline number, the hourly strip marks the hour and footnotes it, and the CSV export's solar_radiation_source column reads clear-sky estimate rather than provider. The note describes the input, not the reading: the learned correction is skipped for an estimated sun, and near dawn and dusk that correction is positive, so the number as a whole can land either side of what a reported sun would have given.

Source: resolveSolar in src/lib/openmeteo.ts, clearSkyGHI in src/lib/solar.ts, and src/lib/solarnote.ts for what the reader is told.

3. Metric overview

WBGT is the primary metric because it is the only one that incorporates solar radiation and is the recognized standard for occupational, athletic, and military heat-stress management.

4. Solar geometry

The Liljegren WBGT model needs two solar quantities: the cosine of the solar zenith angle and the fraction of incoming shortwave that arrives as a direct beam. Source: src/lib/solar.ts.

4.1 Cosine of the solar zenith angle (NOAA equations)

Let doy be the day of year (Jan 1 = 1) and h the UTC time in fractional hours. Define the fractional-year angle γ (radians):

γ = (2π / 365) · (doy − 1 + (h − 12) / 24)

Equation of time (minutes):

EqTime = 229.18 · ( 0.000075
                   + 0.001868·cos γ  − 0.032077·sin γ
                   − 0.014615·cos 2γ − 0.040849·sin 2γ )

Solar declination δ (radians):

δ = 0.006918 − 0.399912·cos γ  + 0.070257·sin γ
              − 0.006758·cos 2γ + 0.000907·sin 2γ
              − 0.002697·cos 3γ + 0.001480·sin 3γ

True solar time and hour angle (lng east-positive degrees):

TST       = h·60 + EqTime + 4·lng           (minutes)
HourAngle = (TST / 4 − 180) · π/180         (radians)

Cosine of the zenith angle (φ = latitude):

cos Z = sin φ · sin δ + cos φ · cos δ · cos(HourAngle)      (clamped to [−1, 1])

cos Z > 0 means the sun is above the horizon.

4.2 Direct-beam fraction (Liljegren clearness index)

Top-of-atmosphere irradiance on a horizontal surface, including the Earth-Sun distance correction (S₀ = 1367 W/m²):

TOA = S₀ · (1 + 0.033·cos(2π(doy − 1)/365)) · cos Z

Clearness index and direct fraction:

Kt   = min(1, S / TOA)
fdir = exp(3 − 1.34·Kt − 1.65/Kt)        clamped to [0, 0.9]

fdir = 0 whenever the sun is below the horizon (cos Z ≤ 0) or S ≤ 0.

5. Primary metric — WBGT (Liljegren et al., 2008)

WBGT combines three temperatures:

WBGT (outdoor, in sun) = 0.7·Tnwb + 0.2·Tg + 0.1·Ta
WBGT (shade / indoor)  = 0.7·Tnwb + 0.3·Ta

where Tnwb is the natural wet-bulb temperature, Tg the black-globe temperature, and Ta the dry-bulb (air) temperature. The app uses the outdoor (in sun) form, solving Tnwb and Tg from two coupled radiative-convective energy balances by iteration.

This is a faithful port of the PyWBGT Cython implementation (github.com/QINQINKONG/PyWBGT), itself a port of Liljegren's original C code. Constants and equations are unchanged; the only deviation is the root-finder (robust bisection here versus Brent's method in the reference — both converge to the same root). Source: src/lib/metrics/liljegren.ts.

5.1 Physical constants

Derived: RATIO = CP·MAIR/MH2O, RAIR = RGAS/MAIR, Pr = CP / (CP + 1.25·RAIR) (Prandtl number).

5.2 Thermophysical helper functions

Air dynamic viscosity μ(T) [kg/(m·s)], with Ω = 1.2945 − T/1141.17647:

μ(T) = 2.6693×10⁻⁶ · √(28.97·T) / (13.082689 · Ω)

Thermal conductivity: k(T) = (CP + 1.25·RAIR) · μ(T).

Saturation vapor pressure (Pa), Buck-type with a pressure-enhancement factor; separate branches over water (T > 273.15 K) and ice:

water:  es = 611.21 · exp(17.502·(T−273.15)/(T−32.18)) · (1.0007 + 3.46×10⁻⁶·Ps_hPa)
ice:    es = 611.15 · exp(22.452·(T−273.15)/(T− 0.60)) · (1.0003 + 4.18×10⁻⁶·Ps_hPa)

Atmospheric emissivity, with vapor pressure e in hPa:

e      = RH·0.01 · (es·0.01)
εatm   = 0.575 · e^0.143

Water-vapor diffusivity in air:

D(T, Ps) = 2.471773765×10⁻⁵ · (T·0.00342105637)^2.334 / (Ps/101325)

Latent heat of vaporisation: λ(T) = 1665134.5 + 2370·T.

Convective heat-transfer coefficients (ρ = Ps/(RAIR·T)):

Sphere   (globe):  Re = v·ρ·Dglobe/μ;  Nu = 2 + 0.6·Re^0.5·Pr^0.3333;  h = Nu·k/Dglobe
Cylinder (wick):   Re = v·ρ·Dwick /μ;  Nu = 0.281·Re^0.6·Pr^0.44;       h = Nu·k/Dwick

5.3 Black-globe energy balance

Direct-beam geometry term (0 when fdir = 0 or cos Z ≤ 0):

directTerm = (0.5/cos Z − 1) · fdir

Radiative constant:

C0 = 0.5·(1 + εatm)·Ta⁴
   + (1 / (2·εg·σ)) · S·(1 − αg)·(1 + directTerm + αsfc)

Globe temperature Tg (K) is the root of, with h the sphere coefficient evaluated at the film temperature ½(Ta + Tg):

C0 − (1/(εg·σ))·h·(Tg − Ta) − Tg⁴ = 0          bracket [Ta−50, Ta+90]

5.4 Natural wet-bulb energy balance

eair       = RH·0.01 · es(Ta)
directTerm = ( tan(arccos(min(1, cos Z)))/π + Dwick/(4·Lwick) ) · fdir
D4         = εwick·0.5·σ·Ta⁴·(εatm + 1)
           + (1 − αwick)·S·( (1 + Dwick/(4·Lwick))·(1 − fdir) + directTerm + αsfc )

Natural wet-bulb temperature Tnwb (K) is the root of, with Tref = ½(Ta+Tw), Sc = μ(Tref)/(ρ·D(Tref)) the Schmidt number, h the cylinder coefficient at Tref, and Fatm = D4 − εwick·σ·Tw⁴:

Ta − (λ(Tref)/RATIO)·((es(Tw) − eair)/(Ps − es(Tw)))·(Pr/Sc)^0.56 + Fatm/h − Tw = 0

bracket [Ta − (100 − RH)/5 − 50, min(Ta + 70, 340)].

5.5 Adjustments and solver details

• Wind height correction & low-wind floor. Inputs are 10 m winds; the model expects ~2 m. Converted with the power law v₂ = v₁₀·(2/10)^0.2, then floored at 1.5 m/s. The Liljegren reference floors at 0.13 m/s, but near-calm air makes the globe and wet-wick energy balances hypersensitive and over-reads heat stress: checked against the NWS's own published WBGT across CONUS, below ~1 m/s we ran +5–8 °C high (a false "Extreme" on mild, sunny, dead-calm days) while NWS stayed put, with excellent agreement at a real breeze. The 1.5 m/s floor — a defensible minimum realistic ventilation at 2 m — removes those calm-air spikes. It does not keep us above NWS: below 50 W/m² our raw reading averages 1.70 °C lower than the reference (§5.9). The floor addresses the calm-sun over-read; the residual high bias at moderate wind and the night under-read are both handled by the conditions-based bias correction, not by this floor.
• Humidity clamp. RH is clamped to [1, 100] %.
• Irradiance / geometry guards. S is floored at 0; fdir is forced to 0 when the sun is below the horizon.
• Root finder. Bisection over the brackets above, tolerance 1×10⁻⁴ K, up to 80 iterations. If either balance fails to bracket a root (no sign change), the engine falls back to the simplified estimate (§5.7) rather than returning a bad number.

5.6 Validation status

The Liljegren method is the validated reference model for WBGT and the one this implementation follows (Liljegren et al., 2008 — reference 1; ISO 7243).

This section previously claimed the method is "more accurate than handheld WBGT meters," attributed to "Duke Nicholas Institute, 2024" — an attribution that appeared nowhere in §18 and pointed at no locatable paper. It has been removed rather than re-sourced. The claim also cuts against the published direction of error: Grundstein et al. (2025, GeoHealth) found smartphone-derived WBGT under-reporting on-site measurements. We model WBGT; we do not measure it, and we do not claim to beat an instrument.

Cross-validation against the National Weather Service. An automated suite (npm run validate:wbgt) compares this implementation against the NWS's published WBGT (api.weather.gov gridpoint forecasts) at eight CONUS cities for the next forecast hour. Representative run (June 9 2026, 23:00 UTC — a hot late-afternoon across the US):

In this June 2026 eight-station snapshot, mean |Δ| = 1.26 °C — within the ±1.5 °C target, with six of eight stations within ±1.1 °C. Treat this as a dated snapshot, not a standing guarantee: the figure moves day to day with conditions and station mix, and on some days it exceeds ±1.5 °C. A live version of this comparison runs continuously at [/validation](/validation) (and the public /api/validation endpoint) — that live value, not the number above, is the current source of truth. Note the comparison conflates method and input differences: NWS drives its WBGT from the National Blend of Models while this app uses Open-Meteo's model blend, so part of each Δ (especially at hours with uncertain afternoon convection, e.g. the Dallas/Atlanta rows) is the two systems disagreeing about clouds and irradiance, not about the WBGT physics. The suite asserts a mean |Δ| ≤ 1.5 °C and per-station |Δ| ≤ 3.5 °C and can be re-run at any time.

Retained accuracy corpus. Beyond the live snapshot, a scheduled collector records each comparison — the full input feature vector, our WBGT (sun and shade), and the NWS reference — into a growing, retained dataset. Because the inputs are stored (not just the final number), this corpus lets us measure systematic bias over time, correct it, and refine the methods, and it remains useful even as the models evolve. An aggregate, no-personal-data readout (total records and rolling mean bias / mean absolute error) is surfaced on the validation dashboard once enough has accrued.

Physical sanity checks also pass: dry desert heat (e.g. Phoenix) reads moderate WBGT, humid tropical nights (e.g. Miami) read elevated WBGT, and in direct sun Tnwb < WBGT < Tg, with Tg rising sharply under high irradiance and low wind.

5.7 Simplified fallback (only when geometry/pressure are unavailable)

When cos Z, fdir, or surface pressure are missing, WBGT uses a closed-form estimate: a Stull wet bulb (§7) for Tnwb and a parameterised globe term:

Tg ≈ Ta + min(25, 0.024·S / √max(0.5, v))
WBGT = 0.7·Tnwb_Stull + 0.2·Tg + 0.1·Ta

This is directionally correct but not validated to the ±1.5 °C target; in normal operation (with full solar geometry) the Liljegren path is always used.

5.8 Sun vs shade (microclimate)

WBGT is acutely sensitive to direct solar load — the same air can be safe under a tree and dangerous on open pavement. To make that difference explicit, the conditions API returns a second WBGT computed in full shade alongside the in-sun value, and the app lets you toggle between them.

The shade value drops the direct beam and fixes the mean radiant temperature at air temperature, which is the common convention in the literature (e.g. CarbonPlan):

Tnwb  =  Liljegren's natural wet-bulb balance at S = 0, fdir = 0
Tmrt  :=  Ta          (so the globe reads air temperature, Tg = Ta)
WBGT_shade  =  0.7·Tnwb  +  0.3·Ta

The second line is a choice, not a measurement, and it is where the honesty of this number lives. Running the full Liljegren globe balance at S = 0 and keeping its result is not shade: with no sun the globe radiates to a cold sky and settles below air temperature (34.3 °C globe at 35 °C air), which describes a clear night under open sky. Real shade replaces that cold sky with a canopy at or above air temperature. Pinning Tmrt to Ta is the simplest defensible stand-in for that canopy.

Treat the result as an idealised best case, and be careful how far you push that. It is a lower bound within the clear-sky open-shade convention family, not a physical floor. It ignores the diffuse and ground-reflected shortwave that real shade still receives, so ordinary shade reads higher — but shade with a hot radiant surface in view (shaded ground beside sunlit asphalt, or a sunlit wall) runs Tmrt above air temperature, and there the "floor" is a ceiling. We have no reference for that case, and no plan to get one.

The sun-minus-shade gap is surfaced directly on the card, rounded to a whole degree (e.g. "Full shade cuts heat stress by about 5°."). It is largest under high irradiance and light wind, and closes to nothing at night. It does not reach exactly zero there: the two numbers weight the globe differently by construction, so with S = 0 they differ by 0.2·(Ta − Tg) — about 0.1–0.2 °C, with the shade figure marginally the higher of the two. The card floors the gap at zero rather than printing a benefit that runs the wrong way. The shade value is then re-classified against the same WBGT scale (§11.1), so the displayed tier, color, and advice follow the shade reading.

One number, three places. The accuracy corpus (§5.6) archives this same quantity per row, computed by the same function, and stamps the convention on the row so a corpus spanning a change of convention can tell its halves apart. Nothing grades it yet — there is no shade reference in the record — which is precisely why the archived value has to be the shown value: when a reference does arrive it must grade the number people actually read. The standalone calculator's shade row uses the same function as well, with standard sea-level pressure and, when no wind is entered, a light 1 m/s breeze. It applies no bias correction, because the correction depends on the hour's sunlight and the calculator does not ask for it, so for identical air the calculator matches the card's shade value before correction.

This is a microclimate estimate, not a substitute for measuring your specific spot: real shade also depends on ground albedo, sky-view fraction, nearby hot surfaces, and ventilation, which a point model cannot see.

5.9 Bias correction (data flywheel)

The retained corpus (§5.6) lets us not only measure systematic bias but correct it — and the corpus showed the bias is conditions-dependent, not constant. On the 30-day window read 2026-09-09 under physics epoch 2026-07-alb020 (17,897 compared samples) the raw global mean residual is −0.78 °C with a mean absolute error of 1.40 °C, and that single pair hides the structure that matters. By shortwave irradiance:

The raw model runs slightly warm through the middle of the day and cool after dark, and the dark hours are both the largest share of the record and the least accurate — the one regime where the raw mean absolute error exceeds our ±1.5 °C target. Reading low is the direction worth stating plainly, so we state it.

A single global offset cannot fix that: the offset that lifted the night would push every daytime bin further off. So the correction is keyed on conditions — and it is what brings the dark hours inside the target. Day-blocked cross-validation on the same reading gives, for the displayed (corrected) number:

These are a dated read of a moving corpus. The live split is published on /validation, and the raw segmentation at /api/bias/segments.

So the displayed WBGT is corrected by a small, learned correction surface over (solar irradiance × wind speed) — the two variables that drive the residual. Both exist in the input for every point on Earth, so a surface learned at the U.S. reference locations generalizes anywhere with the same conditions. The correction is computed per point and bilinearly interpolated between anchor cells so it stays continuous (no banding on the map). Strict guardrails keep it honest:

• Direction. Mean residual is ours − reference; a positive bias (we run warm) yields a negative correction, and vice-versa. On the 2026-09-09 reading that means subtracting about 0.65 °C at 300–600 W/m² and adding about 1.7 °C below 50 W/m². The exact cell values move with the corpus and are printed in the correction table on /validation.
• Shrinkage and clamping. Each (solar, wind) cell is shrunk toward its solar-trend by how much data supports it — a thin, noisy cell borrows from the well-supported trend instead of swinging readings — and its magnitude is clamped to ±3 °C.
• Minimum data. No correction is applied until enough compared samples have accrued; below that threshold the correction is exactly zero.
• Proven to generalize (self-gating). The surface is applied only if it lowers error under day-blocked cross-validation — trained on all other calendar days and tested on a held-out day, by a margin of at least 5 %. We block by day rather than by location because the reference locations share synoptic weather days, so a leave-one-location-out test leaves the held-out day's pattern in the training set through the other locations and reports an optimistic gain; blocking by day removes that temporal leakage and yields the honest, more-conservative number. The live held-out figures are shown on the /validation page; if the correction ever stops clearing the margin, it switches itself off.
• Trained per physics epoch. The correction trains only on residuals gathered under the current raw-physics version. When the engine's physics changes (e.g. the §5.1 surface-albedo correction), residuals measured under the old physics are excluded, so a fixed bias can't be "corrected" twice — the correction simply falls back to the improved raw model until it re-accumulates.
• Applied consistently. The same per-point correction is applied across all user-facing in-sun WBGT — the current reading, the forecast, the map, the city pages, and heat alerts — so the corrected value (the product's core output) is the same everywhere. The shade figure takes the share of that same correction that the surface attributes to its beamless anchor — all of it when there is no sun, none of it in full daylight, and a smooth handover between. The reason for withholding it by day is unchanged: the correction surface has no daytime-shade reference (its solar=0 column is night-dominated), so applying it to daytime shade would add an unfounded offset. The reason for applying it after dark is that with no beam to remove, the in-sun and shade figures differ only by the globe convention of §5.8, a tenth or two of a degree — so correcting one and not the other would invent a difference of a degree or more rather than express the one the physics gives. This is a consistency rule, not a validated one: there is no shade reference at any hour, so we are not claiming the shade figure is more accurate, only that it does not disagree with the in-sun figure about the same air.
• No tail-chasing. It is applied only to that user-facing output. The collector and the validation suite always use the raw, uncorrected engine, so the flywheel keeps measuring the model's true bias rather than the bias of an already-corrected number.

The conditions breakdown is public at /api/bias/segments, and the correction surface with its cross-validation at /api/bias/validate; when a correction is in effect it is also surfaced per reading in the conditions API (biasCorrection, °C). A fully learned model — a regression on the complete feature vector (adding humidity, cloud, time of day, season) — is the natural next refinement (§7).

6. Heat Index (NWS Rothfusz regression)

The familiar US "feels like in the shade" number. Defined in °F; the engine converts in and out so the rest of the pipeline stays in °C. Source: src/lib/metrics/heatindex.ts.

A Steadman blend is always computed first (T in °F, R = RH %):

HI = 0.5·(T + 61 + (T − 68)·1.2 + R·0.094)

If the average (HI + T)/2 ≥ 80 °F, the full Rothfusz regression replaces it:

HI = −42.379
   + 2.04901523·T   + 10.14333127·R
   − 0.22475541·T·R − 0.00683783·T²
   − 0.05481717·R²  + 0.00122874·T²·R
   + 0.00085282·T·R² − 0.00000199·T²·R²

with the two standard corrections:

if R < 13 and 80 ≤ T ≤ 112:   HI −= ((13 − R)/4)·√((17 − |T − 95|)/17)
if R > 85 and 80 ≤ T ≤  87:   HI += ((R − 85)/10)·((87 − T)/5)

The result is converted back to °C.

7. Wet-bulb temperature (Stull, 2011)

A fast psychrometric (thermodynamic) wet-bulb approximation, valid near sea-level pressure for roughly T ∈ [−20, 50] °C and RH ∈ [5, 99] %, accurate to about ±0.3 °C. RH is clamped to [1, 100] %. Source: src/lib/metrics/wetbulb.ts.

Tw = T·arctan(0.151977·√(RH + 8.313659))
   + arctan(T + RH) − arctan(RH − 1.676331)
   + 0.00391838·RH^1.5·arctan(0.023101·RH)
   − 4.686035

Note: this thermodynamic wet bulb does not include radiation or wind, so in direct sun it slightly underestimates the natural wet bulb. The app surfaces it as its own "Wet Bulb" metric and uses it as the Tnwb term only in the simplified WBGT fallback (§5.7); the primary WBGT uses the full Liljegren natural wet-bulb solver.

8. Apparent Temperature / "Real Feel" (BoM, Steadman)

The Australian Bureau of Meteorology apparent-temperature formulation. Unlike Heat Index it includes the cooling effect of wind, making it the better everyday "real feel". Water-vapor pressure e in hPa, wind v in m/s. Source: src/lib/metrics/apparent.ts.

e   = (RH/100) · 6.105 · exp(17.27·Ta / (237.7 + Ta))
AT  = Ta + 0.33·e − 0.70·v − 4.00

When Open-Meteo supplies a native apparent_temperature, that value is used in preference to this formula; otherwise the formula above is computed.

9. Dew point (Magnus-Tetens)

Coefficients from Alduchov & Eskridge (1996); accurate to about ±0.4 °C for 0 < T < 60 °C. RH clamped to [1, 100] %. a = 17.625, b = 243.04. Source: src/lib/metrics/dewpoint.ts.

γ  = ln(RH/100) + (a·Ta)/(b + Ta)
Td = (b·γ) / (a − γ)

The provider's native dew_point_2m is preferred when present.

10. Supporting context fields

These are displayed for context and are not inputs to the heat-stress calculations:

• UV Index (uv_index) — bucketed Low / Moderate / High / Very High / Extreme at 3 / 6 / 8 / 11.
• Air Quality (us_aqi) — US AQI, bucketed Good / Moderate / Sensitive / Unhealthy / Very Bad / Hazardous at 50 / 100 / 150 / 200 / 300.
• Cloud cover (cloud_cover, %), surface pressure (surface_pressure, hPa), precipitation (precipitation, mm; shown in inches when imperial).

11. Classification scales

All thresholds are stored in °C (engine units); °F equivalents are given here for convenience. Bands share a common green → yellow → orange → red → purple → black severity gradient so that color means the same thing across metrics. Source: src/lib/metrics/scales.ts.

11.1 WBGT — "Heat Stress" (primary)

11.2 Wet-bulb temperature

The ~35 °C wet-bulb survivability limit is the temperature above which a healthy person can no longer shed metabolic heat by sweating, even at rest in shade.

11.3 Heat Index

11.4 Real Feel (apparent temperature)

11.5 Dew point (comfort)

11.6 Unified advisory

The card shows one persistent heat-danger advisory: the most severe guidance across the three monotonic heat-stress metrics (WBGT, Heat Index, Wet Bulb), independent of which metric the user is viewing. Severity is ranked by band index and mapped to the WBGT advisory ladder:

Dew point (a comfort scale) and Real Feel (which has cold bands) are excluded from the unified advisory.

12. "This day in history"

Places today's heat in climatological context using ERA5 reanalysis. Source: src/app/api/history/route.ts, src/lib/openmeteo.ts.

• Variable. Daily maximum apparent temperature (apparent_temperature_max), a humidity-aware, precomputed daily aggregate — chosen so decades of context come from a single cheap request rather than recomputing hourly WBGT.
• Window. A ±3-day window around today's calendar day, across the most recent 35 complete years.
• Per-year peak. For each year, the maximum daily feels-like high within the window. Window days are grouped by climatological season-year so a window that straddles 1 January stays in one group (correct for Southern-Hemisphere summers).
• Outputs. Percentile rank of today's forecast feels-like high among the per-year peaks; the climatological normal (mean of the peaks); the all-time record (value and year); and the full per-year series for the sparkline.
• Today's value. Today's forecast apparent_temperature_max.
• Location. The requested point rounded to 0.1° (about 11 km north-south), used for both today's value and the archive, so the whole panel describes one point and one cached answer serves a neighborhood.

If fewer than five valid years are available, the panel hides itself.

13. Map visualization (interpolation)

The heat map is a continuous field built from point samples. For a viewport the app samples a grid of points (current conditions, or a forecast hour from the time scrubber); at low zoom it uses an always-on 10°-aligned global grid (37 × 17 = 629 points). Sample nodes snap to a fixed absolute lat/lng lattice with a discrete halving step ladder (10° → 5° → … → ~0.01°), so node positions are stable across pans and zooming refines onto an aligned subgrid. All layers sample at a shared 15-minute time bucket: solar geometry is evaluated at the same instant for every zoom level, so the field is consistent across views and rolls over together. Each sampled point is run through the same metrics engine, then the grid is bilinearly interpolated per pixel and colored along the metric's continuous gradient; ocean / missing nodes fade to transparent so the field flows seamlessly. This is a visualization step only and does not alter the per-point metric values. Source: src/components/HeatMap.tsx, src/app/api/grid/route.ts, src/app/api/global/route.ts.

14. Limitations and assumptions

• Inputs are NWP model output, not in-situ observations; local microclimate (pavement, shade, buildings) is not captured.
• The Liljegren surface albedo (0.20, representative of vegetated/urban CONUS) and the assumption of a standing person in the open are fixed; true WBGT varies with ground cover and posture.
• Shortwave radiation is global horizontal; the direct/diffuse split is inferred from a clearness-index parameterisation, not measured.
• Stull wet bulb assumes near-sea-level pressure.
• Historical context uses daily apparent-temperature maxima (not WBGT) for tractability, and ERA5 has a coarser grid than the live forecast.
• The simplified WBGT fallback (§5.7) is not validated and is used only when solar geometry or pressure are unavailable.

15. Personalization ("safe for me")

The objective WBGT is universal and is never altered by personalization. To make it actionable for an individual, the app computes a separate personal-risk readout shown alongside the objective number. Source: src/lib/personalize.ts.

The person optionally provides a few heat-risk factors. Each maps to a small °C-equivalent "personal heat load" added to the objective WBGT to form an effective value, which is then classified on the same WBGT scale (§11.1) — so the "Your risk" tier and color mean the same thing as everywhere else.

The total load is clamped to +6 °C.

On the scientific basis (and its honest limits). There is no single published table that converts "age" or "a heart condition" into a WBGT offset. What the literature does establish is the underlying physiology and the practice of adjusting heat-stress limits for these factors. We translate that established guidance into one intuitive °C-equivalent readout, calibrated conservatively:

• Exertion. Heat-stress standards do not use a single WBGT threshold — they lower the safe limit (or shorten the work/rest ratio) as metabolic heat production rises. ISO 7243 sets WBGT limits by metabolic rate, and the U.S. ACGIH/NIOSH action limits drop by roughly 4–6 °C WBGT from rest to heavy work [10][11][12]. Our resting → light → heavy loads (0 / +1.5 / +3.0) sit well inside that established range.
• Heat acclimatization. Acclimatized individuals tolerate substantially higher heat strain; NIOSH and ACGIH publish separate, lower limits for the unacclimatized, and acclimatization is among the strongest modifiable protective adaptations [11][12][13]. Hence the +1.5 °C for "not acclimatized."
• Age. Older adults have blunted thermoregulation (reduced skin blood flow and sweating) [14]; children have a higher surface-area-to-mass ratio and lower sweat capacity [15]. Both are recognized heat-vulnerable groups [11].
• Health sensitivities. Cardiovascular and respiratory disease, pregnancy, and many common medications (e.g. diuretics, anticholinergics, some psychiatric drugs) impair heat dissipation or fluid balance and raise heat-illness risk [11][16][17]. We apply a conservative, capped load and never infer or display any specific condition.

This "objective hazard × personal vulnerability" framing mirrors public-health tools such as the U.S. CDC/NWS HeatRisk index [18]. Our specific weights are deliberately conservative starting points, not clinical thresholds, and are a prime target for data-driven refinement as the accuracy flywheel (§5.6) and the literature inform them.

This is guidance, not medical advice or a diagnosis. Inputs are optional and self-reported, stored on the device and synced to the account only when signed in, and can be cleared at any time.

16. Pavement / paw-safety surface temperature

Source: `src/lib/pavement.ts`.

Air temperature badly understates how hot the ground gets in the sun. A dark, dry surface in full sun runs roughly 40–60 °F (22–33 °C) hotter than the air, and a contact burn becomes possible within about a minute once the surface passes ~125 °F / 52 °C — the "the air feels fine but the pavement is dangerous" gap a dog owner (or a barefoot child) never thinks to check. The app already measures the three inputs a surface energy balance needs — shortwave solar, air temperature, and wind — so it estimates the surface temperature and turns it into a plain paw-safety verdict. This is an estimate to help you check before you walk, not a measurement — read the limitations in §16.5, especially the after-dark one, before relying on the number.

16.1 Surface energy balance

A horizontal opaque surface in quasi-steady state balances absorbed sunlight against three losses — net longwave radiation to the sky, convection to the air, and conduction/storage into the pavement mass:

α·S = ε·σ·(Ts⁴ − Tsky⁴) + h_conv·(Ts − Ta) + h_sub·(Ts − Ta)

solved for the surface temperature Ts by bisection (the balance is monotonic in Ts). S is the weather model's global horizontal shortwave irradiance (bounded as in §2.2 when the provider omits it), Tsky = Ta·ε_sky^0.25, and h_conv = 5.7 + 3.8·u is the standard McAdams (1954) combined convection coefficient [22] with u a near-surface wind (≈ half the 10 m wind). This is the same radiative–convective balance the app solves for the WBGT black globe (§5.3), specialised to flat ground; the closed form is essentially the Solaimanian & Kennedy (1993) maximum-pavement-temperature model [21] — the basis of the Superpave high-temperature binder grade.

The one departure from a full treatment is collapsing substrate conduction and storage into a single lumped conductance h_sub (calibrated below) rather than solving the transient 1-D heat-conduction equation. On its own this is quasi-steady: it returns the temperature the current sun, air, and wind would sustain — which snaps to air temperature at night and so cannot see the heat still stored in the pavement after sunset.

Thermal memory (transient model). For the live reading we therefore integrate the lumped-capacitance form of the same balance over the recent ~day of hourly weather:

C·dTs/dt = α·S − ε·σ·(Ts⁴ − Tsky⁴) − (h_conv + h_sub)·(Ts − Ta)

Now the surface has heat capacity C = ρ·c_p·D, with D the diurnal damping depth √(2·(k/ρc_p)/ω), ω = 2π/86400 s⁻¹ — for asphalt (k≈1.2, ρ≈2300, c_p≈900), D≈0.13 m and C≈2.6×10⁵ J/m²·K, a derived thermophysical value, not a fitted knob. At light wind it gives a cooling time constant τ = C/h_total ≈ 3 h, so the surface lags the sun (peaking an hour or two after solar noon) and stays materially hotter than the air for hours after sunset — matching field evidence that asphalt is far warmer late at night than at dawn. We report the warmer of the steady-state equilibrium and this transient integration: a single lumped capacity necessarily damps the mid-day peak, so the steady state (tuned to reproduce Berens' field readings) wins by day, while the transient term wins in the evening — keeping the Berens-calibrated afternoon number and an honest post-sunset one, and never reading cooler than either. When the recent history is unavailable (e.g. a scrubbed forecast hour) the reading falls back to the quasi-steady value.

16.2 Constants

Asphalt is the hot default (roads, lots, many paths); concrete sidewalks run cooler because they reflect more sunlight, so both are shown.

16.3 Calibration, and honesty about it

h_sub is set so the model reproduces the classic field readings of Berens (JAMA, 1970) [19] — a Phoenix case series that measured asphalt reaching ≈125 °F at 77 °F air, ≈135 °F at 86 °F, and ≈143 °F at 87 °F, explicitly "in direct sunlight and in the absence of wind." With h_sub ≈ 8.5 W/m²·K the model matches those readings to within a few °F at full sun.

We are deliberate about what that does and does not mean. Berens' numbers are informal spot-readings, not a controlled calibration curve — a 1 °F air rise (86→87) jumps the asphalt reading 8 °F, which only happens across different surfaces and days. So we treat them as illustrative field observations, not a lookup formula, and we do not claim the model is "validated" against them. The widely-copied "95 °F → 149 °F" row cannot be confirmed in Berens' original and is not used as an anchor. The general effect and its upper end are corroborated by peer-reviewed measurement — Harrington et al. (1995) recorded asphalt peaking near 68 °C / 154 °F [24]. Because the model is driven by the hour's own solar value rather than assuming "sunny," a mild but cloudy morning correctly reads cool while a merely-warm but sunny afternoon reads hot.

16.4 Paw-burn risk tiers

Contact injury follows a continuous time–temperature relationship (Moritz & Henriques, 1947) [20], not a hard cutoff, so the tiers are graded and never imply "below 125 °F is safe":

These thresholds come from human-skin studies. Dog paw pads are thicker and more keratinized, so the figures are a conservative safety floor, not a measured pad value; puppies and thin or injured pads are more vulnerable.

16.5 Limitations (read these)

• After dark. The live reading uses the thermal-memory model (§16.1), so it keeps the day's stored heat and reads an honest evening/night number rather than snapping to air temperature. It is still a reduced-order (single lumped-capacity) approximation of a distributed system, so treat the nighttime value as indicative, not exact — and always finish with the hand test. A scrubbed forecast hour has no recent history to integrate, so it falls back to the quasi-steady value and shows the hand-test warning after dark instead.
• Thermal-lag timing. The transient model peaks an hour or two after solar noon and lingers into the evening, but a single lumped capacity cannot perfectly resolve the fast surface skin and the slow deep mass at once — so the exact peak timing and the evening decay rate are approximate.
• Single-point, dry, clear-sky, open surface. The estimate assumes dry, exposed, aged asphalt (or gray concrete) under a clear sky. Real pavement varies within metres with shade, colour, age, wetness and material — a shaded or wet path runs far cooler, fresh black asphalt in full sun hotter. It is not a reading of the specific patch under your dog.
• The hand test is the cross-check. A widely-shared vet/shelter rule of thumb (durations vary — many guides say 5–7 s; the AKC suggests ~10 s [25][26]): press the back of your hand to the pavement; if you can't hold it there comfortably, it's too hot for paws. It's a sensory heuristic, not a measurement — pair it with the obvious moves: walk early or late, and use grass and shade.

17. Where this is headed (roadmap)

Accuracy here is a continuous commitment, not a fixed claim. Three directions, all powered by the retained corpus (§5.6):

1. A fully learned bias-correction model. The conditions-based correction is already live (§5.9): a (solar × wind) surface, cross-validated to cut held-out error 34.3 % across 31 day-blocked folds on the corpus read 2026-09-09. The staged rollout was global offset → segmented surface → a learned model, and that last step is the open one — a regression (gradient-boosted trees or a small network) on the complete feature vector stored with each sample (adding humidity, cloud cover, time of day, and season) to squeeze the residual further. Every candidate stays guarded by shrinkage, magnitude clamps, and held-out cross-validation, so a richer model ships only if it provably generalizes to days it never trained on.

1. Multi-source ground truth. The NWS reference is itself a model, so agreement measures method+input agreement, not absolute truth. The corpus schema carries a ref_source field so additional references slot in and are weighted by reliability: physical sensors (mesonets, handheld WBGT meters, a small owned network) > ERA5 reanalysis (global coverage, extends the comparison outside the US) > forecast models. Because raw inputs are retained, history can be re-graded as better truth arrives.

1. Microclimate refinement. Sun vs. shade (§5.8) is the first of several layers that move from the model's open-surface, ~km-scale grid toward the meter-scale reality: surface type and albedo (e.g. hot asphalt vs. grass, which feed the globe energy balance directly), the urban heat island, sky-view factor in urban canyons, tree canopy, and wind sheltering — each derivable from land-cover and terrain data and, ultimately, calibrated against the corpus.

Full detail and guardrails are in the project roadmap (docs/roadmap.md).

18. References

1. Liljegren, J. C., Carhart, R. A., Lawday, P., Tschopp, S., & Sharp, R. (2008). Modeling the Wet Bulb Globe Temperature Using Standard Meteorological Measurements. Journal of Occupational and Environmental Hygiene, 5(10), 645–655.
2. Stull, R. (2011). Wet-Bulb Temperature from Relative Humidity and Air Temperature. Journal of Applied Meteorology and Climatology, 50(11), 2267–2269.
3. Rothfusz, L. P. (1990). The Heat Index Equation. NWS Southern Region Technical Attachment SR/SSD 90-23.
4. Steadman, R. G. (1984). A Universal Scale of Apparent Temperature. Journal of Climate and Applied Meteorology, 23(12), 1674–1687. (BoM apparent temperature.)
5. Alduchov, O. A., & Eskridge, R. E. (1996). Improved Magnus Form Approximation of Saturation Vapor Pressure. Journal of Applied Meteorology, 35(4), 601–609.
6. NOAA Global Monitoring Laboratory. Solar Position Calculator equations (general solar geometry). Haurwitz, B. (1945). Insolation in relation to cloudiness and cloud density. Journal of Meteorology, 2(3), 154-166. (Clear-sky global horizontal irradiance, used as the upper bound in §2.2.)
7. Kong, Q., & Huber, M. PyWBGT — reference implementation of the Liljegren WBGT model. github.com/QINQINKONG/PyWBGT
8. Hersbach, H., et al. (2020). The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society, 146(730), 1999–2049.
9. Open-Meteo. Open-Meteo Weather, Air-Quality, and Historical Reanalysis APIs. open-meteo.com
10. International Organization for Standardization (2017). ISO 7243:2017 — Ergonomics of the thermal environment: Assessment of heat stress using the WBGT (wet bulb globe temperature) index.
11. National Institute for Occupational Safety and Health (2016). Criteria for a Recommended Standard: Occupational Exposure to Heat and Hot Environments. DHHS (NIOSH) Publication No. 2016-106.
12. American Conference of Governmental Industrial Hygienists (ACGIH). Heat Stress and Strain: TLV® Physical Agents documentation (WBGT screening limits by workload and acclimatization state).
13. Périard, J. D., Racinais, S., & Sawka, M. N. (2015). Adaptations and mechanisms of human heat acclimation. Scandinavian Journal of Medicine & Science in Sports, 25(S1), 20–38.
14. Kenney, W. L., & Munce, T. A. (2003). Invited Review: Aging and human temperature regulation. Journal of Applied Physiology, 95(6), 2598–2603.
15. Falk, B., & Dotan, R. (2008). Children's thermoregulation during exercise in the heat: a revisit. Applied Physiology, Nutrition, and Metabolism, 33(2), 420–427.
16. Westaway, K., Frank, O., Husband, A., et al. (2015). Medicines can affect thermoregulation and accentuate the risk of dehydration and heat-related illness during hot weather. Journal of Clinical Pharmacy and Therapeutics, 40(4), 363–367.
17. Ravanelli, N., Casasola, W., English, T., Edwards, K. M., & Jay, O. (2019). Heat stress and fetal risk: environmental limits for exercise and passive heat stress during pregnancy — a systematic review. British Journal of Sports Medicine, 53(13), 799–805.
18. U.S. Centers for Disease Control and Prevention & National Weather Service. HeatRisk — an index combining heat intensity with population vulnerability. cdc.gov / weather.gov.
19. Berens, J. J. (1970). Thermal Contact Burns From Streets and Highways. JAMA, 214(11), 2025–2027. (Origin of the classic air-vs-asphalt field readings; Phoenix case series, direct sun, no wind.)
20. Moritz, A. R., & Henriques, F. C. (1947). Studies of Thermal Injury: II. The Relative Importance of Time and Surface Temperature in the Causation of Cutaneous Burns. American Journal of Pathology, 23(5), 695–720.
21. Solaimanian, M., & Kennedy, T. W. (1993). Predicting Maximum Pavement Surface Temperature Using Maximum Air Temperature and Hourly Solar Radiation. Transportation Research Record, 1417, 1–11.
22. McAdams, W. H. (1954). Heat Transmission (3rd ed.). McGraw-Hill. (Combined surface convection coefficient h = 5.7 + 3.8·u.)
23. Lawrence Berkeley National Laboratory, Heat Island Group. Cool Pavements — solar-reflectance and emissivity values for asphalt and concrete. heatisland.lbl.gov.
24. Harrington, A. W., et al. (1995). Pavement Temperature and Burns: Streets of Fire. Annals of Emergency Medicine, 26(5), 563–568. (And the review "Streets of Fire revisited: contact burns," Burns & Trauma, 2019.)
25. American Kennel Club. How to Protect Dog Paws From Hot Pavement (J. Klein, Chief Veterinary Officer). akc.org.
26. FOUR PAWS USA. Hot Asphalt — A Danger to your Dog's Paws. fourpawsusa.org.
27. Grundstein, A., Clark, J., et al. (2025). Evaluation of smartphone applications for estimating wet bulb globe temperature. GeoHealth. doi:10.1029/2025GH001347. (Finds app-derived WBGT under-reporting on-site measurements — cited in §5.6 for the direction of error, not as a validation of this implementation.)

Generated for WetBulbTracker.com. The metrics engine is a pure, framework-free module; every formula above is implemented in `src/lib/metrics/` and `src/lib/solar.ts` and can be audited directly.