Detect coldwaves using multiple standard methodologies

Applies seven coldwave detection methods (WHO, WMO, INMET, ECF, 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 coldwave days and discrete events per method, and returns a named list with events, daily-flag, and annual-summary tables — all carrying sus_meta at stage "climate" / type "coldwaves".

Usage

sus_climate_compute_coldwaves(
  df,
  method = c("WHO", "WMO", "INMET", "EHF", "UTCI", "WBGT", "HI"),
  baseline_start = NULL,
  baseline_end = NULL,
  percentile = 10,
  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/ECF; 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. Note: the internal algorithm for the "EHF" slot uses the Excess Cold Factor (ECF) formula.
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 10). Percentile used for WHO, WMO, UTCI, WBGT, and HI threshold calculations (lower tail for coldwaves).
min_duration: Integer or NULL. Minimum consecutive days to qualify as a coldwave. 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_cw and sus_meta attribute (stage "climate", type "coldwaves"):

events: One row per detected event: event_id, station_code, method, start_date, end_date, duration_days, temp_mean, temp_peak (coldest), anomaly_mean, anomaly_cumulative, severity_index, ecf_peak, ecf_mean, intensity_class, and station metadata.
daily: Daily aggregated data with logical flag columns cw_<method> and cw_any.
summary: Annual summary by station and method: year, n_events, total_days_cw, mean_duration, max_duration, mean_intensity, max_intensity, mean_anomaly, severity_total.

Implemented methods

1. WHO Tmin < P10(Tmin) 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 Tmin < P10(Tmin) AND Tmax < P10(Tmax) for >= N days (default N=5). Double threshold ensures both daytime and nighttime extremes are captured. Reference: Perkins & Alexander (2013).

3. INMET Tmin < mean(Tmin_hist) - 5 degC for >= N days (default N=5). Climatological mean from the baseline period. Designed for Brazilian context.

4. ECF Excess Cold Factor: ECF = ECI_sig x max(1, ECI_acc) where ECI_sig = P5(Tmean) - T3 and ECI_acc = T30 - T3. Intensity classified by ECF85 (85th percentile of positive ECF values). Adaptation of Nairn & Fawcett (2015) for cold extremes. Positive ECI_acc means the preceding month was warmer than the recent 3-day mean (body acclimatised to heat, amplifying cold stress).

5. UTCI UTCImin < P10(UTCImin) for >= N days (default N=3). Requires utci_c column from sus_climate_compute_indicators().

6. WBGT WBGTmin < P10(WBGTmin) for >= N days (default N=3). Requires wbgt_c column from sus_climate_compute_indicators().

7. HI HImin < P10(HImin) 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. (Adapted for coldwaves)
WMO & WHO (2015). Heatwaves and Health: Guidance on Warning-System Development. Geneva. (Adapted for coldwaves)
Nairn, J.R. & Fawcett, R.J.B. (2015). The Excess Heat Factor. Int. J. Environ. Res. Public Health, 12(1), 227-253. (Adapted for cold) doi:10.3390/ijerph120100227
INMET (2009). Normais Climatologicas do Brasil 1961-1990. Brasilia.

Examples

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

cw$events
cw$summary
cw$daily[cw$daily$cw_any, ]
} # }