Documentation

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

1 - Overview

The heatindex software package contains one function, also called heatindex, which calculates the heat index following the simpler and faster algorithm described by this paper.

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

• Installation: Install in R or Python
• Examples: Calculate the heat index

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.

• R
• Python

library(heatindex)
heatindex(300,0.5)

import heatindex as hi
hi.heatindex(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 one function, which is also called heatindex. The heatindex function takes two arguments: the absolute air temperature in Kelvin and the relative humdity from 0 to 1. Below are some (rather trivial) 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 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.

4 - Physics

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.

5 - Citation

The official release of the heatindex package will coincide with the publication of Yu et al. (2025), which is currently in review. The paper provides a detailed description of heatindex package’s heatindex function.

The heatindex package, available through PyPI and CRAN, was written 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.1). 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.1},
  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.1
ER  -

The heatindex package’s heatindex function is based on the paper by Yi-Chuan Lu et al., which can 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 others},
  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  - et al.
PY  - 2025
JO  - Journal of Applied Meteorology and Climatology
N1  - In review
ER  -