Skip to contents

Detect heatwaves using multiple standard methodologies

Source: R/sus_climate_compute_heatwaves.R
sus_climate_compute_heatwaves.Rd

Applies seven heatwave detection methods (WHO, WMO, INMET, EHF, UTCI, WBGT, HI) to a climasus_df at stage "climate" produced by sus_climate_inmet(), sus_climate_fill_gap(), or sus_climate_compute_indicators(). Aggregates hourly data to daily scale, computes smoothed historical percentile thresholds from a reference baseline, identifies heatwave days and discrete events per method, and returns a named list with event, daily-flag, and annual-summary tables — all carrying sus_meta at stage "climate" / type "heatwaves".

Usage

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

Arguments

df

A climasus_df at stage "climate" with type "inmet", "filled", or "indicators". Produced by sus_climate_inmet(), sus_climate_fill_gap(), or sus_climate_compute_indicators(). Must contain columns date and station_code. Temperature columns tair_max_c, tair_min_c, tair_dry_bulb_c are required for WHO/WMO/ INMET/EHF; utci_c, wbgt_c, hi_c are required for UTCI/WBGT/HI (available after sus_climate_compute_indicators()).

method

Character vector. One or more of "WHO", "WMO", "INMET", "EHF", "UTCI", "WBGT", "HI". Use "all" to run every method. Methods whose required columns are absent emit a warning and are skipped.

baseline_start

Date or character (e.g., "1981-01-01"). Start of the reference period for percentile thresholds. NULL uses the full series.

baseline_end

Date or character. End of the reference period. NULL uses the full series.

percentile

Numeric (0–100, default 90). Percentile used for WHO, WMO, UTCI, WBGT, and HI threshold calculations.

min_duration

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

lang

Character. Output language: "pt" (default), "en", "es".

verbose

Logical. Print progress messages. Default TRUE.

Value

A named list with class climasus_hw and sus_meta attribute (stage "climate", type "heatwaves"):

events

One row per detected event: event_id, station_code, method, start_date, end_date, duration_days, temp_mean, temp_peak, anomaly_mean, anomaly_cumulative, severity_index, ehf_peak, ehf_mean, intensity_class, and station metadata.

daily

Daily aggregated data with logical flag columns hw_<method> and hw_any.

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 Tmax > P90(Tmax) for >= N consecutive days (default N=3). Threshold smoothed over a 15-day rolling window by calendar day-of-year. Reference: WMO & WHO (2015).

2. WMO Tmax > P90(Tmax) AND Tmin > P90(Tmin) for >= N days (default N=5). Double threshold ensures both daytime and nighttime extremes are captured. Reference: Perkins & Alexander (2013).

3. INMET Tmax > mean(Tmax_hist) + 5 degC for >= N days (default N=5). Climatological mean from the baseline period. Designed for Brazilian context. Reference: INMET (2009); MCTI/Gov.br (2025).

4. EHF Excess Heat Factor: EHF = EHI_sig x max(1, EHI_acc) where EHI_sig = T3 - P95(Tmean) and EHI_acc = T3 - T30. Intensity classified by EHF85 (85th percentile of positive EHF values). Reference: Nairn & Fawcett (2015).

5. UTCI UTCImax > P90(UTCImax) for >= N days (default N=3). Requires utci_c column from sus_climate_compute_indicators().

6. WBGT WBGTmax > P90(WBGTmax) for >= N days (default N=3). Requires wbgt_c column from sus_climate_compute_indicators().

7. HI HImax > P90(HImax) for >= N days (default N=3). Requires hi_c column from sus_climate_compute_indicators().

References

  • Perkins, S.E. & Alexander, L.V. (2013). On the measurement of heat waves. Journal of Climate, 26(13), 4500-4517.

  • WMO & WHO (2015). Heatwaves and Health: Guidance on Warning-System Development. Geneva.

  • Nairn, J.R. & Fawcett, R.J.B. (2015). The Excess Heat Factor. Int. J. Environ. Res. Public Health, 12(1), 227-253. doi:10.3390/ijerph120100227

  • Broede, P. et al. (2012). Deriving the operational procedure for UTCI. Int. J. Biometeorology, 56(3), 481-494. doi:10.1007/s00484-011-0454-1

  • INMET (2009). Normais Climatologicas do Brasil 1961-1990. Brasilia.

See also

sus_climate_inmet(), sus_climate_compute_indicators()

Examples

if (FALSE) { # \dontrun{
hw <- df_indicators |>
  sus_climate_compute_heatwaves(
    method         = c("WHO", "INMET", "EHF"),
    baseline_start = "2000-01-01",
    baseline_end   = "2020-12-31",
    lang           = "pt"
  )

hw$events
hw$summary
hw$daily[hw$daily$hw_any, ]
} # }