Documentation

• 1: Overview
• 2: Installation
• 3: Examples
• 4: Physics
• 5: Citation

1 - Overview

The heatindex software package contains two main functions: heatindex and wetbulb. The heatindex function calculates the heat index following the simpler and faster algorithm described by this paper. The wetbulb function calculates the wet-bulb temperature following using the accurate Rankine-Kirchhoff framework as described by this paper.

Installing and using the heatindex package in R or Python is easy. Get started in seconds:

• Installation: Install in R or Python
• Examples: Calculate the heat index and wet-bulb temperature

2 - Installation

Installation in R or Python is simple.

• R
• Python

# From inside R, run:
install.packages("heatindex")

# At the terminal, run:
pip install heatindex

So is loading heatindex and calculating the heat index or the thermodynamic wet-bulb temperature.

• R
• Python

library(heatindex)
heatindex(300,0.5)
wetbulb(1e5,300,0.5)

import heatindex as hi
hi.heatindex(300,0.5)
hi.wetbulb(1e5,300,0.5)

That is all there is to it. But, if you need to see another example, check out Examples.

3 - Examples

The heatindex package has two main functions: one of those functions has the same name as the package and the other function is named wetbulb. The heatindex function takes two arguments: the absolute air temperature in kelvin and the relative humidity from 0 to 1. The wetbulb function takes three arguments: the pressure in pascal, the air temperature in kelvin, and the relative humidity from 0 to 1. Below are some examples.

Calculate a single value of the heat index

Given a single temperature, e.g., 300 K, and a single relative humidity, e.g., 0.5, we can calculate the heat index as follows.

• R
• Python

library(heatindex)
heatindex(300,0.5)

import heatindex as hi
hi.heatindex(300,0.5)

This returns the heat index in kelvin.

Calculate an array of heat index values

If, instead, we have an array of temperature and an array of relative humidity, we can feed those to heatindex and it will return an array of heat index values.

• R
• Python

library(heatindex)
T <- matrix(301:312,nrow=3,byrow=TRUE)
rh <- matrix(1:12/12,nrow=3,byrow=TRUE)
heatindex(T,rh)

import heatindex as hi
import numpy as np
T = np.linspace(301, 312, 12).reshape(3, 4)
rh = np.linspace(1, 12, 12).reshape(3, 4)/12
hi.heatindex(T,rh)

This returns a 3 x 4 matrix of heat index values in kelvin.

Calculate a single value of the wet-bulb temperature

Given a single pressure, e.g., 1 bar, a single temperature, e.g., 300 K, and a single relative humidity, e.g., 0.5, we can calculate the thermodynamic wet-bulb temperature as follows.

• R
• Python

library(heatindex)
wetbulb(1e5,300,0.5)

import heatindex as hi
hi.wetbulb(1e5,300,0.5)

This returns the wet-bulb temperature in kelvin.

Calculate an array of wet-bulb temperatures

If, instead, we have arrays of pressure, temperature, and relative humidity, we can feed those to wetbulb and it will return an array of thermodynamic wet-bulb temperatures.

• R
• Python

library(heatindex)
p <- 1e5 - 5e3*matrix(1:12,nrow=3,byrow=TRUE)
T <- matrix(301:312,nrow=3,byrow=TRUE)
rh <- matrix(1:12/12,nrow=3,byrow=TRUE)
wetbulb(p,T,rh)

import heatindex as hi
import numpy as np
p = 1e5 - 5e3*np.linspace(1,12,12).reshape(3, 4)
T = np.linspace(301, 312, 12).reshape(3, 4)
rh = np.linspace(1, 12, 12).reshape(3, 4)/12
hi.wetbulb(p,T,rh)

This returns a 3 x 4 matrix of wet-bulb temperatures in kelvin.

Switch to psychrometric and/or an ice bulb

By default, wetbulb calculates the thermodynamic wet-bulb temperature, which is what is most often meant when someone refers to “the wet-bulb temperature.” Sometimes, however, we may want to calculate the temperature of a psychrometric (a.k.a., aspirated or ventilated) wet bulb. Or, we may wish to calculate the temperature of an ice bulb. These values can be accessed using optional arguments.

• R
• Python

library(heatindex)
wetbulb(1e5,275,0.5) # thermodynamic wet-bulb temperature
wetbulb(1e5,275,0.5,psychrometric=TRUE) # psychrometric wet-bulb temperature
wetbulb(1e5,275,0.5,icebulb=TRUE) # thermodynamic ice-bulb temperature
wetbulb(1e5,275,0.5,psychrometric=TRUE,icebulb=TRUE) # psychrometric ice-bulb temperature

import heatindex as hi
print(hi.wetbulb(1e5,275,0.5)) # thermodynamic wet-bulb temperature
print(hi.wetbulb(1e5,275,0.5,psychrometric=True)) # psychrometric wet-bulb temperature
print(hi.wetbulb(1e5,275,0.5,icebulb=True)) # thermodynamic ice-bulb temperature
print(hi.wetbulb(1e5,275,0.5,psychrometric=True,icebulb=True)) # psychrometric ice-bulb temperature

4 - Physics

Physics of the heatindex function

The heat index is the air temperature at a reference vapor pressure of 1.6 kPa that induces the same physiological response as the actual air temperature and humidity. Therefore, the definition of the heat index HI can be expressed mathematically as

where “physiology” in this equation is a function that returns the physiological state, T_a is the air temperature, RH is the relative humidity, and p* is the saturation vapor pressure as a function of air temperature. In addition to this definition of the heat index, there is a mathematical model of thermoregulation that is used to calculation the “physiology” function above.

To calculate the physiological state, we first check if the human is in a state of hyperthermia.

For the hyperthermic and lethal regions, we use

To check that, the relevant equation is equation (18) of Lu and Romps (2022), which is

where C_c represents the heat capacity of the core, T_c = 310 K and T_a are the temperatures of the core and air; p_c = \(\phi\)_salt p*(T_c) and p_a are the vapor pressures of the core and air; \(\phi\)_salt is the effective relative humidity of sweat; p* is the saturation vapor pressure; R_a is the resistance to heat flow through the boundary layer at the surface of the skin; Z_a are the resistance to mass (i.e., sweat) flow through that boundary layer; Q is the metabolic heat flux generated in the core; and Q_v is the respiratory heat flux from the core to the air. In this equation, the skin’s temperature and vapor pressure are assumed to be the same as in the core, made possible by a very high skin blood flow. If dT_c/dt is positive in this equation, then hyperthermia is unavoidable and the rate of warming defines the physiological state. The heat index then equals the air temperature (in the presence 1.6 kPa of water vapor) that would give the same dT_c/dt.

Otherwise, if dT_c/dt is negative, then thermoregulation can be achieved with a lower skin blood flow, i.e., with skin that resists the flow of heat and water. The physiological state is then defined by the skin’s resistance to heat flow that achieves dT_c/dt = 0 at a normal core temperature of T_c = 310 K.

Here, the relevant equations are equations (14-16) of Lu and Romps (2022), which are

where variables with a subscript “s” denote properties of the shell, which represents the skin and, at colder temperatures, also clothing. Here, T_s and p_s are the temperature and vapor pressure of the shell’s outer surface, R_s is the shell’s resistance to heat flow; and Z_s is the shell’s resistance to mass (i.e., sweat) flow. Setting T_c = 310 K, these equations describe a steady-state solution to thermoregulation with a normothermic core temperature. The first equation describes the core’s heat balance, which has metabolic heat production Q balanced by ventilation Q_v and the flow of heat from core to shell. The second equation describes the heat balance of the shell, which is affected by the flow of heat from core to shell, the flow of heat from shell to air, and the cooling from evaporation of sweat. The third equation is the solution for the vapor pressure of the partially wetted shell. The minimum function was introduced by Lu and Romps (2022) and ensures that the vapor pressure does not exceed the saturation vapor pressure of sweat; in effect, this allows excess sweat to drip off the shell. Together with some auxiliary equations, these equations can be solved to find R_s, which defines the physiological state. The heat index then equals the air temperature (in the presence 1.6 kPa of water vapor) that would give the same R_s.

Physics of the wetbulb function

The wetbulb function calculate four different temperatures using the accurate Rankine-Kirchhoff framework: thermodynamic wet-bulb (the default), psychrometric (a.k.a., ventilated or aspirated) wet-bulb, thermodynamic ice-bulb, and psychrometric ice-bulb. The most commonly used of these is the thermodynamic wet-bulb temperature, which is usually denoted by T, so we retain that notation here. To denote the psychrometric wet-bulb temperature, we use T_pw. Likewise, we use T_i and T_pi to denote the thermodynamic and psychrometric ice-bulb temperatures.

The air’s thermodynamic wet-bulb temperature is the temperature of liquid water that is invariant with respect to isobaric thermodynamic equilibration with a parcel of the air. In other words, the thermodynamic wet-bulb temperature T_w is the temperature that yields the following outcome:

Note that the liquid water and the air parcel end up equilibrated (they are at a common temperature T_w and the air parcel is saturated), the process is isobaric (the pressure is held constant at p), and, most notably, the temperature of the liquid water does not change (its temperature remains at T_w). Note that the masses of the parcels of liquid water and air do not, in general, remain the same through this equilibration process; for RH < 1 the parcel of liquid water gives mass to the air parcel, and vice versa for RH > 1; for RH = 1, there is no exchange of mass and T_w = T.

The air’s psychrometric wet-bulb temperature is the temperature of liquid water that is invariant with respect to an isobaric exchange of heat and moisture with a stream of the air. In other words, the psychrometric wet-bulb temperature T_pw is the temperature that yields the following outcome:

As in the case of the thermodynamic wet-bulb temperature, this process is isobaric (the pressure is held constant at p) and the temperature of the liquid water does not change (its temperature remains at T_pw), but the liquid water and the stream of air do not reach equilibration (the downstream air will have a temperature T’ between T and T_pw and a relative humidity RH’ between RH and 1).

The ice-bulb versions of the above are the same, but with “liquid water” replaced with “solid water” or “ice.” The derivation of equations for all of these bulb temperatures using the Rankine-Kirchhoff framework can be found in Romps (2025).

5 - Citation

Citing the heatindex package

The heatindex package, available through PyPI and CRAN, is maintained by Yi-Chuan Lu and David M. Romps and can be cited as follows.

• APA
• BibTeX
• RIS

Lu, Y.-C. and Romps, D. M. (2025). heatindex: Tools for Calculating Heat Stress (Package version 0.0.2). https://heatindex.org

@manual{,
  title  = {heatindex: Tools for Calculating Heat Stress},
  author = {Yi-Chuan Lu and David M. Romps},
  year   = {2025},
  note   = {Package version 0.0.2},
  url    = {https://heatindex.org},
}

TY  - COMP
T1  - heatindex: Tools for Calculating Heat Stress
AU  - Lu, Yi-Chuan
AU  - Romps, David M.
PY  - 2025
UR  - https://heatindex.org
N1  - Package version 0.0.2
ER  -

Citing the heatindex function

The heatindex package’s heatindex function is based on the paper by Lu et al., which should be cited as follows.

• APA
• BibTeX
• RIS

Lu, Y.-C., et al. (2025). Simpler and faster: An improved heat index. Journal of Applied Meteorology and Climatology, in review.

@article{lu2025,
  author  = {Yi-Chuan Lu and Alex Goodman and Peter Kalmus and David M. Romps},
  title   = {Simpler and faster: an improved heat index},
  journal = {Journal of Applied Meteorology and Climatology},
  year    = {2025},
  note    = {In review},
}

TY  - JOUR
T1  - Simpler and faster: An improved heat index
AU  - Lu, Yi-Chuan
AU  - Goodman, Alex
AU  - Kalmus, Peter
AU  - Romps, David M.
PY  - 2025
JO  - Journal of Applied Meteorology and Climatology
N1  - In review
ER  -

Citing the wetbulb function

The heatindex package’s wetbulb and rh_from_wetbulb functions are based on the paper by Romps, which should be cited as follows.

• APA
• BibTeX
• RIS

Romps, D.M. (2025). Wet-bulb temperature from pressure, relative humidity, and air temperature. Journal of Applied Meteorology and Climatology, in review.

@article{lu2025,
  author  = {David M. Romps},
  title   = {Wet-bulb temperature from pressure, relative humidity, and air temperature},
  journal = {Journal of Applied Meteorology and Climatology},
  year    = {2025},
  note    = {In review},
}

TY  - JOUR
T1  - Wet-bulb temperature from pressure, relative humidity, and air temperature
AU  - Romps, David M.
PY  - 2025
JO  - Journal of Applied Meteorology and Climatology
N1  - In review
ER  -