heatstress

Vectorised heat-stress indices for public-health, climate-adaptation and occupational-safety analysis: NWS Heat Index, Humidex, Apparent Temperature, wet-bulb temperature, WBGT (full Liljegren et al. 2008 model, shade/indoor, ISO 7243, BoM approximation), UTCI, Wind Chill, mean radiant temperature, solar position, risk categories and heatwave detection, including the Excess Heat Factor.

• Pure numpy core; every function takes scalars, numpy arrays, pandas Series or xarray DataArrays and returns the same kind of object.
• Units are explicit: degC by default with a units="C" | "F" | "K" switch on temperature functions, wind in m/s, pressure in hPa, radiation in W/m2, humidity in %. Converters are in heatstress.units.
• Inputs outside a formula's validity range raise a ValidityRangeWarning; NaN propagates.
• Validated against published reference values and independent implementations (see Validation).
• A command-line tool for single values and CSV time series.

Disclaimer. heatstress computes screening indices from weather data. It is not medical advice and is not a substitute for on-site measurement, an occupational health programme, clinical judgement or the official warnings of your national meteorological or public-health service.

Installation

pip install heatstress            # numpy only
pip install "heatstress[pandas]"  # + pandas helpers (DataFrames, events_to_frame)
pip install "heatstress[xarray]"  # + xarray/pandas

Python 3.9 or newer.

Quick start

import heatstress as hs

hs.heat_index(35, 60)                     # 45.1 degC (NWS algorithm)
hs.heat_index(95, 50, units="F")          # 105.2 degF
hs.heat_index_category(45.1)              # 'danger'

hs.humidex(30, dew_point=15)              # 34.0
hs.apparent_temperature(30, 50, wind=2)   # 31.6 degC
hs.wet_bulb_psychrometric(25, 50)         # 17.9 degC
hs.utci(30, tmrt=50, wind=2, rh=50)       # 34.6 degC
hs.utci_category(34.6)                    # 'strong heat stress'

# Outdoor WBGT from standard weather data (Liljegren et al. 2008)
z = hs.solar_zenith("2026-07-15T10:00Z", lat=38.42, lon=27.14)
w = hs.wbgt_liljegren_components(t=33, rh=55, wind=1.5, solar=850, zenith=z, pressure=1008)
w.wbgt, w.globe_temperature, w.natural_wet_bulb    # 32.7, 49.7, 27.7 degC
hs.work_rest_allocation(w.wbgt, "moderate")   # ACGIH TLV work-rest guidance

# Heatwaves on a daily series
import pandas as pd
tmax = pd.Series(..., index=pd.date_range("1991-01-01", periods=..., freq="D"))
thr = hs.calendar_day_percentile(tmax, tmax.index, q=90, window=15, baseline=(1991, 2020))
events = hs.heatwave_events(tmax, thr, min_duration=3)
hs.events_to_frame(events)

ehf = hs.excess_heat_factor(tmean_daily)      # Nairn & Fawcett (2015)
hs.ehf_severity(ehf)                          # none / low-intensity / severe / extreme

Indices

Risk categories

Heatwave detection

• percentile_threshold and calendar_day_percentile (centred moving window of calendar days, optional baseline years, 29 February merged with 28 February).
• heatwave_mask, consecutive_runs and heatwave_events find spells of at least min_duration consecutive days above a scalar or day-varying threshold and report start, end, duration, peak and exceedance statistics; events_to_frame converts them to a DataFrame.
• excess_heat_factor: EHI_sig = T3 - T95, EHI_accl = T3 - T30prev, EHF = EHI_sig x max(1, EHI_accl), attributed to the first day of the three-day window; T95 from a reference period (t95= or reference=).

Command line

$ heatstress hi 35 --rh 60
              heat_index: 45.1 degC
                category: danger

$ heatstress wbgt 33 --rh 55 --wind 1.5 --solar 850 --time 2026-07-15T10:00Z --lat 38.42 --lon 27.14
$ heatstress utci 30 --tmrt 55 --wind 2 --rh 50
$ heatstress windchill 0 --wind 15 --wind-units mph --units F
$ heatstress series weather.csv -o indices.csv --lat 38.42 --lon 27.14

Every value command accepts --units C|F|K and --json; wind accepts --wind-units ms|kmh|mph|kn. heatstress series reads a CSV, recognises common column names (time, t/temperature, rh, td, wind, solar/ghi, pressure, tmrt, tg, zenith, lat, lon), and appends every index that the columns allow (UTCI needs tmrt or a globe temperature; the Liljegren WBGT needs wind, solar and either a zenith column or time plus coordinates). The same logic is available in Python as hs.compute_indices(df).

Validation

All comparisons are in the test suite (tests/test_reference_values.py) unless noted.

Units and conventions

• Temperatures: degC unless units="F" or "K" (applies to all temperature inputs and outputs of that call).
• Relative humidity in %, wind speed in m/s (10 m for Apparent Temperature, Wind Chill and UTCI; 2 m for Liljegren unless wind_height is given), pressure in hPa (station pressure), solar radiation in W/m2 (global horizontal).
• Results come back as Python floats for scalar input, numpy arrays for array input, and pandas Series / xarray DataArrays (same index or coordinates) when the first array argument is one.

Citation

See CITATION.cff. Please also cite the original authors of each index you use.

License

MIT (c) 2026 Yusuf Eminoğlu. The UTCI test data shipped in tests/data are by Broede et al., CC BY 4.0.