Detect heatwaves using multiple standard methodologies

Applies several heatwave definitions to daily temperature and thermal comfort indices. The function expects an hourly data frame as produced by sus_climate_compute_indicators() or a similarly structured INMET dataset. It aggregates to daily scale, computes historical thresholds from a user-defined baseline period, identifies heatwave days with each requested method, extracts discrete events, and returns a list of event, daily, and annual summaries.

Usage

sus_climate_compute_heatwaves(
  data,
  method = c("WHO", "WMO", "INMET", "EHF", "UTCI", "WBGT", "HI"),
  baseline_start = NULL,
  baseline_end = NULL,
  percentile = 90,
  min_duration = NULL,
  lang = c("en", "pt", "es"),
  verbose = TRUE
)

Arguments

data

A data frame with hourly observations from sus_climate_inmet() or sus_climate_compute_indicators(). Must contain columns:

date (POSIX datetime)
station_code (character)
tair_dry_bulb_c, tair_max_c, tair_min_c (numeric, degrees Celsius)
utci_c, wbgt_c, hi_c (numeric, for corresponding methods) Pre-fill missing values using sus_climate_fill_inmet() before calling this function.

method

Character vector. One or more of "WHO", "WMO", "INMET", "EHF", "UTCI", "WBGT", "HI". Use "all" to run all available methods. Methods requiring missing thermal indices will be ignored with a warning.

baseline_start

Date or character (e.g., "1981-01-01"). Start of the reference period for percentile-based thresholds. NULL uses the entire data range.

baseline_end

Date or character. End of the reference period. NULL uses the entire data range.

percentile

Numeric (default 90). Percentile for the threshold calculation (applied to methods WHO, WMO, UTCI, WBGT, HI).

min_duration

Integer or NULL. Minimum consecutive days for a heatwave. NULL uses method-specific defaults: WHO=3, WMO=5, INMET=5, EHF=3, UTCI=3, WBGT=3, HI=3.

lang

Character. Language for progress messages: "en", "pt", or "es" (default "en").

verbose

Logical. Show progress steps (default TRUE).

Value

A list with three data frames:

events: One row per detected heatwave event. Columns: event_id, station_code, method, start_date, end_date, duration_days, temp_mean, temp_peak, anomaly_mean, anomaly_cumulative, severity_index, ehf_peak (EHF only), ehf_mean (EHF only), intensity_class (EHF only), and site metadata.
daily: The daily aggregated data with logical flags for each method (columns hw_<method>), plus an hw_any flag indicating whether any method detected a heatwave that day.
summary: Annual summary by station and method: year, n_events, total_days_hw, mean_duration, max_duration, mean_intensity, max_intensity, mean_anomaly, severity_total.

Implemented methods

1. WHO (World Health Organization / WMO Guidance) Condition: Tmax > P90(Tmax) for N consecutive days (default N=3) where P90(Tmax) is the 90th percentile of daily maximum temperature, smoothed over a 15-day rolling window by calendar day-of-year. Reference: WMO & WHO (2015).

2. WMO (World Meteorological Organization) Condition: Tmax > P90(Tmax) AND Tmin > P90(Tmin) for N consecutive days (default N=5), where P90 denotes the 90th percentile of each temperature variable. Double-threshold approach ensures both daytime and nighttime extremes. Reference: Perkins & Alexander (2013).

3. INMET (Brazilian National Institute of Meteorology) Condition: Tmax > mean(Tmax_hist) + 5 deg C for N consecutive days (default N=5), where mean(Tmax_hist) is the climatological mean of daily maximum temperature computed over the baseline period (typically 1961-1990 or user-specified). Designed for Brazilian tropical/subtropical contexts. Reference: INMET (2009); MCTI/Gov.br (2025).

4. EHF (Excess Heat Factor) Excess Heat Factor calculated as: EHF = EHI_sig * max(1, EHI_acc) where EHI_sig = T3 - P95(Tmean) (physiological signal) and EHI_acc = T3 - T30_mean (acclimatization index). T3 = 3-day centered mean temperature; T30_mean = 30-day prior mean. Days with EHF > 0 are flagged; intensity classified by the 85th percentile of positive EHF values (Low, Severe, Extreme). Reference: Nairn & Fawcett (2015); Nairn et al. (2018).

5. UTCI (Universal Thermal Climate Index) Condition: UTCImax > P90(UTCImax) for N consecutive days (default N=3), where P90 is the 90th percentile smoothed over a 15-day window. UTCI integrates air temperature, humidity, wind speed, and radiation to estimate physiological heat stress (equivalent temperature). Reference: Broede et al. (2012).

6. WBGT (Wet Bulb Globe Temperature) Condition: WBGTmax > P90(WBGTmax) for N consecutive days (default N=3). WBGT combines temperature, humidity, wind, and radiation into a single index used widely in occupational health and sports medicine. Reference: Liljegren et al. (2008); ISO 7243:2017.

7. HI (Heat Index) Condition: HImax > P90(HImax) for N consecutive days (default N=3), where P90 is the 90th percentile smoothed over a 15-day window. Heat Index (apparent temperature) combines temperature and humidity to estimate how hot it feels to human perception. Reference: Steadman (1979a, 1984).

References

General heatwave concepts and percentile framework

Perkins, S.E. (2015). A review on the scientific understanding of heatwaves–their measurement, driving mechanisms, and changes at the global scale. Atmospheric Research, 164-165, 242-267. doi:10.1016/j.atmosres.2015.05.009
Perkins, S.E. & Alexander, L.V. (2013). On the measurement of heat waves. Journal of Climate, 26(13), 4500-4517.
Fischer, E.M. & Schaer, C. (2010). Consistent geographical patterns of changes in high-impact European heatwaves. Nature Geoscience, 3, 398-403.

WHO / WMO methods

WMO & WHO (2015). Heatwaves and Health: Guidance on Warning-System Development. World Meteorological Organization, Geneva.
WMO (2021). Guidelines on the Definition and Monitoring of Extreme Weather and Climate Events. World Meteorological Organization.

INMET method

INMET - Instituto Nacional de Meteorologia (2009). Normais Climatologicas do Brasil 1961-1990. Brasilia: MAPA/INMET.
MCTI/Gov.br (2025). Heatwave reports for Brazil (online).

EHF (Excess Heat Factor)

Nairn, J.R. & Fawcett, R.J.B. (2015). The Excess Heat Factor: A metric for heatwave intensity and its use in classifying heatwave severity. International Journal of Environmental Research and Public Health, 12(1), 227-253. doi:10.3390/ijerph120100227
Nairn, J.R. et al. (2018). Performance of Excess Heat Factor Severity as a global heatwave health impact index. International Journal of Environmental Research and Public Health, 15(11), 2494.

UTCI (Universal Thermal Climate Index)

Broede, P., Fiala, D., Blazejczyk, K., Holmer, I., Jendritzky, G., Kampmann, B., Tinz, B. & Havenith, G. (2012). Deriving the operational procedure for the Universal Thermal Climate Index (UTCI). International Journal of Biometeorology, 56(3), 481-494. doi:10.1007/s00484-011-0454-1

WBGT (Wet Bulb Globe Temperature)

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.
ISO 7243:2017. Ergonomics of the thermal environment – Assessment of heat stress using the WBGT index. International Organization for Standardization.

HI (Heat Index)

Steadman, R.G. (1979a). The assessment of sultriness. Part I: A temperature-humidity index based on human physiology and clothing science. Journal of Applied Meteorology, 18(7), 861-873.
Steadman, R.G. (1984). A universal scale of apparent temperature. Journal of Applied Meteorology and Climatology, 23(12), 1674-1687.

Brazil health context (SUS)

Fiocruz (2025/2026). Excess cardiovascular mortality associated with extreme heatwaves in Southeast Brazil, 2014-2023. Cadernos de Saude Publica.
Observatorio do Clima. Excess mortality during heatwaves in Brazilian urban areas (2000-2018).

Examples

if (FALSE) { # \dontrun{
  # After computing hourly indicators:
  # df_ind <- sus_climate_compute_indicators(...)

  hw_result <- sus_climate_compute_heatwaves(
    data          = df_ind,
    method        = c("WHO", "INMET", "UTCI"),
    baseline_start = "2000-01-01",
    baseline_end   = "2020-12-31"
  )

  # Extract event list
  head(hw_result$events)

  # Annual summary table
  hw_result$summary

  # Days with at least one active heatwave method
  head(hw_result$daily[hw_result$daily$hw_any, ])
} # }