Compute Bioclimatic and Thermal Stress Indicators

sus_climate_compute_indicators() calculates a comprehensive set of bioclimatic and thermal-stress indices from INMET station data (output of sus_climate_inmet() or sus_climate_fill_inmet()).

Scientific robustness highlights:

• WBGT uses a dual wet-bulb estimate (Liljegren + Bernard/Pourmoghani) averaged for numerical robustness; solar radiation NA treated as 0 (no solar load at night) so all hours yield a valid value.

• HI implements full Rothfusz (1990) regression with both NWS humidity adjustments and a regionally adapted validity threshold.

• UTCI uses a Fiala-polynomial-inspired multi-term regression (vapour pressure, logarithmic wind, radiation linear + non-linear, wind vs radiation interaction).

• PET is based on a MEMI-style energy-balance approximation with seasonal clothing adjustment and regional correction.

• Solar radiation undergoes optional physical consistency verification against extraterrestrial radiation limits.

• Diurnal range is a true daily aggregate (Tmax - Tmin per calendar day) broadcast to all hourly rows of that day.

• Multi-level confidence flags (_flag_extreme, _flag_high, _flag_low) replace a single _out_of_range flag.

• Optional 200-simulation Monte Carlo uncertainty estimation.

Available indicators:

Code	Output column	Requires
wbgt	wbgt_c	T, RH, SR, WS
hi	hi_c	T, RH
thi	thi_c	T, RH
wcet	wcet_c	T, WS
wct	wct_c	T, WS
et	et_c	T, RH, WS
utci	utci_c	T, RH, WS, SR
pet	pet_c	T, RH, WS, SR
cdd	cdd_c	T
hdd	hdd_c	T
gdd	gdd_c	T
diurnal_range	diurnal_range_c	T (daily agg.)
vapor_pressure	vapor_pressure_kpa	T, RH
heat_stress_risk	heat_stress_risk	T, RH, WS, SR
koppen_humidity	koppen_humidity	RH

(Where: T=tair_dry_bulb_c, RH=rh_mean_porc, SR=sr_kj_m2, WS=ws_2_m_s)

Usage

sus_climate_compute_indicators(
  df,
  indicators = "all",
  region = "auto",
  datetime_col = NULL,
  station_col = NULL,
  apply_validity_mask = TRUE,
  confidence_flags = NULL,
  custom_thresholds = NULL,
  keep_source_vars = FALSE,
  verify_physics = TRUE,
  compute_uncertainty = FALSE,
  verbose = TRUE,
  lang = "pt",
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/spatial"
)

Arguments

df

Data frame or tibble from sus_climate_inmet() or sus_climate_fill_inmet().

indicators

Character vector of indicator codes or "all" (default).

region

Character. "auto" (default, standard thresholds) or a Brazilian biome: "amazon", "cerrado", "caatinga", "atlantic_forest", "pampa", "pantanal", "southeast", "south".

datetime_col

Character or NULL (auto-detected).

station_col

Character or NULL (auto-detected).

apply_validity_mask

Logical (default TRUE). When region=="none", masks HI, WCET, WCT outside their valid meteorological domains with NA.

confidence_flags

Logical. Add _flag_extreme, _flag_high, _flag_low columns. Default TRUE when region is set, FALSE otherwise.

custom_thresholds

Named list to override regional defaults.

keep_source_vars

Logical (default FALSE).

verify_physics

Logical (default TRUE). Check solar radiation against extraterrestrial limits; requires latitude column.

compute_uncertainty

Logical (default FALSE). Monte Carlo 95% CI.

verbose

Logical (default TRUE).

lang

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

use_cache

Logical. If TRUE (default), uses cached spatial data to avoid re-downloads and improve performance.

cache_dir

Character string specifying the directory to store cached files. Default is "~/.climasus4r_cache/spatial".

Value

A tibble of class climasus_df containing indicator columns, optional flag/CI columns, and a sus_meta attribute.

Scientific References

• Liljegren et al. (2008) J. Occup. Environ. Hyg. 5(10):645-655.

• Bernard & Pourmoghani (1999) AIHAJ 60(1):32-37.

• Rothfusz (1990) NWS Tech. Attachment SR/SSD 90-23.

• Thom (1959) Weatherwise 12(2):57-59.

• Environment Canada (2001) Wind Chill Index.

• Brode et al. (2012) Int. J. Biometeorol. 56(4):481-494.

• Matzarakis et al. (1999) Int. J. Biometeorol. 43:76-84.

• Magnus (1844) / Tetens (1930) saturation vapour pressure.

Examples

if (FALSE) { # \dontrun{
result <- sus_climate_compute_indicators(df_clima)

result <- sus_climate_compute_indicators(
  df_clima, region = "amazon", confidence_flags = TRUE
)

result <- sus_climate_compute_indicators(
  df_clima,
  region              = "auto",
  verify_physics      = TRUE,
  compute_uncertainty = TRUE,
  keep_source_vars    = TRUE
)

df_clima |>
  sus_climate_fill_inmet(target_var = "all") |>
  sus_climate_compute_indicators(indicators = c("wbgt", "hi", "utci"))
} # }