Plan WBGT follow-up after phase-1 humidex support

[peetmate]

Summary

Phase-1 human heat support now uses xclim-backed humidex, including generic screening classes in calculate_hazards.

This follow-up issue is for a higher-fidelity WBGT workflow. It should stay clearly separate from the current generic humidex screening so users do not confuse the two.

Related:

• Propagate human heat-stress support through package workflows #93
• Plan human heat-stress metric support and source workflow #91
• Plan heat-stress support for people, livestock, and rangelands #9

Why this is separate

Current humidex support is useful for first-pass human heat screening because it works with the package's current source coverage.

WBGT is still deferred because it needs a stronger method decision and clearer source handling for:

• temperature
• humidity or dewpoint
• wind
• radiation / globe-temperature proxy inputs

Questions to resolve

1. Which WBGT formulation should the toolkit support first?

• full WBGT where inputs are truly available
• a clearly labelled proxy workflow where full inputs are not available
• indoor/shade and outdoor/sun variants as separate outputs

2. Which backends are acceptable?

• evaluate xclim support if suitable
• otherwise use a documented, well-cited implementation
• avoid adding an opaque Atlas-only proxy if a better-supported method exists

3. Which sources can support WBGT coherently?

• likely historical candidates: agera_5, nasa_power, some custom station inputs
• conditional: paired/composite historical workflows if variable provenance is explicit
• likely not ready: current nex_gddp workflow unless humidity/wind/radiation coverage is demonstrated and documented

4. How should users see this in the package?

• climate_statistics
• compare_periods
• calculate_hazards
• CLI/docs/examples

Implementation checklist

• write a short method note comparing humidex vs WBGT in toolkit scope
• decide first supported WBGT formulation and cite sources
• audit source-variable availability for humidity, wind, and radiation
• design source guardrails so unsupported combinations fail clearly
• decide whether paired/composite workflows can mix precip with independent heat-stress bundles
• add package helpers for WBGT calculation and metadata/provenance
• add reporting hooks in climate_statistics
• add period comparison support where both windows are compatible
• decide whether calculate_hazards should expose WBGT classes or keep them in a separate human-heat layer
• add tests and CLI smoke examples
• update README and method docs

Acceptance criteria

• toolkit docs clearly distinguish generic humidex screening from WBGT
• supported source combinations are explicit
• unsupported source combinations fail with actionable messages
• at least one end-to-end historical workflow is tested and documented
• no user-facing claim that future/projection WBGT is supported unless the required inputs are actually available

[Sammyjoseph999]

Scoping notes grounded in the current code, to frame the WBGT follow-up.

What phase-1 already gives us

• Human-heat lives in climatology/human_heat_stress.py: compute_daily_humidex(), classify_humidex_series/value(), build_humidex_screening_thresholds(), describe_human_heat_method().
• calculate_hazards wires humidex in as a distinct hazard class (HUMIDEX result/stat keys, its own print row), separate from crop indices — good precedent to keep WBGT as its own clearly-labelled class rather than folding it into humidex.

Key backend finding (answers Q2)

xclim has no WBGT. Its heat indices are humidex and heat_index only — no wet-bulb-globe or wet-bulb temperature. So WBGT cannot lean on xclim; it needs a documented, cited implementation. Recommendation:

• Shade/indoor WBGT first via the well-cited BoM/ACSM approximation WBGT ≈ 0.567·Ta + 0.393·e + 3.94 (e = vapour pressure) — needs only temperature + humidity, so it works with our current source coverage.
• Full outdoor/sun WBGT (Liljegren-style, needs wind + solar radiation + a globe-temp proxy) as an explicitly-labelled second variant, gated on true input availability. Avoids an opaque Atlas-only proxy.

Source coverage audit (answers Q3)

Transform mappings (data_dictionary.yaml) show which sources expose the needed variables:

• agera_5 — temperature + humidity + wind_speed + solar_radiation → the coherent candidate for full outdoor WBGT.
• nasa_power — similar coverage; viable.
• Any T+humidity source (incl. paired/composite with explicit provenance) → sufficient for shade WBGT.
• nex_gddp — humidity/wind/radiation coverage not demonstrated → not ready, matches the issue. No projection/future WBGT claim until inputs are proven.

Package surface (answers Q4)

• Add compute_daily_wbgt() + classification/thresholds alongside humidex in human_heat_stress.py, with its own describe_*_method() provenance.
• Expose in calculate_hazards as a separate WBGT class set (distinct keys/labels), never merged with generic humidex screening.
• Reporting hook in climate_statistics; compare_periods support only when both windows share source + variable provenance.
• Guardrails: if the chosen formulation's required variables are missing for the selected source, fail with an actionable message naming the missing variable(s) and the sources that do provide them.

Suggested first tranche

1. Short method note: humidex screening vs shade vs full WBGT, with citations.
2. Implement shade WBGT (T+humidity) end-to-end on agera_5/nasa_power, with source guardrails + tests + one CLI smoke, and README/docs that clearly distinguish it from humidex.
3. Defer full outdoor WBGT to a follow-up once (2) is validated.

Flagging for team direction rather than self-assigning. If the "no-xclim → BoM shade WBGT first, Liljegren outdoor later" call and the agera_5-first source choice look right, I can take the method note + shade-WBGT exemplar.