README

HeatStressR calculates meteorological heat-stress metrics from aligned observations. Version 3 introduces canonical snake_case endpoints, one method registry, common validation and diagnostics, Romps thermodynamic wet bulb, and the simplified 2026 Lu Heat Index.

HeatStressR is an independently maintained GPL-3 fork of HeatStress at f77a263. Ana Casanueva wrote the original package and R translation; Yifei Zheng maintains this fork. It is not affiliated with the original project or authors.

Use citation("HeatStressR") for the package citation. Please also cite the original methodological reference for each heat-stress method used; see the corresponding function documentation.

Install

Requires R 4.1 or later. The new Romps and Lu methods depend on the authors’ heatindex package; source installs of that dependency require C++17/Rcpp. HeatStressR itself contains R code.

# CRAN:
install.packages("HeatStressR")

# R-universe:
install.packages(
  "HeatStressR",
  repos = c("https://zyf0717.r-universe.dev", "https://cloud.r-project.org")
)

# GitHub (development version):
remotes::install_github("zyf0717/HeatStressR")

library(HeatStressR)
heat_methods()

Calculate indices

Temperatures are Celsius, humidity is percent, pressure is hPa, wind is m/s, and downwelling shortwave radiation is W/m². See heat_methods() for each method’s requirements, humidity phase convention, units and references. Humidex uses a Celsius-equivalent index scale.

heat_index_rothfusz(c(25, 35), c(50, 10))
heat_index_lu(c(25, 35), c(50, 70))
wet_bulb_romps(30, 70, pressure = 950)
wbgt_simplified_abm(30, 70)
wbgt_simplified_indoor(30, 70)

indices <- heat_indices(c(25, 30), c(60, 70))
selected <- heat_indices(
  c(25, 30), c(60, 70), wind_10m = c(1, 2),
  indices = c("humidex", "heat_index_lu", "apparent_temperature")
)

heat_indices() automatically selects every method supported by supplied inputs, including numerical methods. Select indices explicitly for stable columns and predictable computation. It does not infer missing humidity inputs or substitute wind heights.

wet_bulb_romps() calculates thermodynamic liquid-water wet bulb. Natural wet bulb, aspirated wet bulb and WBGT are different quantities. The ABM and indoor simplified WBGT formulas also represent different approximations.

Liljegren WBGT

The existing vectorized R heat-balance solver remains the implementation, with automatic scalar fallback and optional PSOCK workers. Wind must be at 2 m; adjust other heights externally. Supply timestamps as instants and align interval data before calculation.

time <- as.POSIXct(
  c("2024-06-01 12:00:00", "2024-06-01 13:00:00"), tz = "UTC"
)
wbgt <- wbgt_liljegren(
  tas = c(30, 31), dewp = c(22, 22.5), wind = c(1.5, 2),
  radiation = c(700, 750), time = time, lon = 0, lat = 15,
  direct_fraction = c(0.6, 0.8)
)
detail <- wbgt_liljegren(
  30, 22, 1.5, 700, time[1], 0, 15, diagnostics = TRUE
)
detail$components

Pressure defaults to 1010 hPa, an explicit near-sea-level assumption. control groups advanced root/residual precision, albedo, globe diameter and minimum wind speed. Use workers > 1 only for a sufficiently large call and avoid nesting worker pools.

The model is an independently maintained R implementation, rather than a bitwise port of the original C program (see lwbgt). Match physical assumptions when comparing implementations.

Migration and reproducibility

Legacy 2.x names remain as deprecated adapters and warn once per session. Removal is planned no earlier than v4.0.0. hi() uses the corrected NWS procedure; swbgt() continues to represent the indoor approximation.

Reference fixtures use heatindex 0.0.2. The runtime dependency accepts compatible later versions; pin the dependency in your own environment for identical reproducibility. Diagnostic metadata reports the installed version. Use tools/install-reference-dependencies.R for the pinned validation library.

For local source tests, use an isolated library containing this checkout so PSOCK workers load the same package version as the parent:

Rscript tools/install-reference-dependencies.R /tmp/heatstressr-test-library
R_LIBS=/tmp/heatstressr-test-library R CMD INSTALL --library=/tmp/heatstressr-test-library .
R_LIBS=/tmp/heatstressr-test-library Rscript -e 'testthat::test_local()'