Introduction

Human biometeorology is experiencing a resurgence in research interest because of concerns about the impact of weather and climate on living organisms and the effects of human activities on the atmospheric environment1. The methods used in modern human biometeorology are increasingly diffused among practitioners in related fields, such as urban or regional planners, air conditioning engineers, public and occupant health, and tourism2,3,4,5,6,7,8,9. Thermal indices are used to conduct objective investigations into thermal perception as a part of modern human biometeorology7,10,11. Thermal indices are also used for the effective and comprehensive evaluation of climate sensitive designs towards the development of a zero-net power grid, sustainable urban development12,13,14,15,16,17, and architectural design18,19,20 for thermal comfort8,21,22. Parts of thermal indices are pointed out as standard reference for evaluation of thermal environments for comfort23,24. Thermal indices can be categorized as empirical or rational10,25. Empirical indices [i.e. Wet-Bulb Globe Temperature in \(^{\circ }\)C (WBGT)26 have been developed for specific and restricted thermal or meteorological conditions, such as indoor environments, or warm or cold environments. Empirical indices are regularly expressed through a simple formula and are not well suited for application to other thermal conditions or general use. Rational indices are calculated using complicated computational models based on a human energy equilibrium. A previous study11 proposed that certain rational thermal indices, such as Universal Thermal Climate Index in \(^{\circ }\)C (UTCI)27,28, Perceived Temperature in \(^{\circ }\)C (PT)29, Physiologically Equivalent Temperature in \(^{\circ }\)C (PET)30 and Outdoor Standard Effective Temperature in \(^{\circ }\)C (SET*)31, are effective for evaluating general thermal environments globally. These rational indices are too complex to be calculated with a simple equation by non-experts, e.g., urban planners and architects. Therefore, RayMan was developed as a Windows-based application to calculate mean radiant temperature in \(^{\circ }\)C (\(T_{mrt}\)) and these rational indices32,33. However, RayMan is compiled in Delphi, and is thus only supported on Windows 7 or older versions, and thus is not under active maintenance or development. Therefore, RayMan has failed to keep pace with advances in computational technology and thermo-physiological knowledge, and thus cannot be applied to innovative thermal indices, such as an improved version of the modified Physiologically Equivalent Temperature in \(^{\circ }\)C (mPET)34,35,36. This raises the need for a successor application for innovative thermal indices or further modification of existing thermal indices. A former Python package (pythermalcomfort) was proposed to calculate thermal comfort indices including emblematically empirical and rational indices using essential simulation of the \(T_{mrt}\) based on the RayMan routine as inputs37. The other two Python packages—Ladybug and thermofeel38—for calculating thermal indices mainly and originally focused on UTCI. Thermofeel aims to apply outputs of the traditional weather numeric model to calculate \(T_{mrt}\) as the input for calculating UTCI, while Ladybug-tool applies 3-dimensional street canyon and building to simulate \(T_{mrt}\). However, the results of Ladybug tool are different from ENVI-met39,40 and field measurements41. These three Python packages are all unable to calculate mPET. Thus, a novel Python library is proposed to calculate rational thermal indices—specifically advanced version of the mPET, directly simulate \(T_{mrt}\), and serve as an inheritor of RayMan.

Human biometeorological library in Python

The Python library is named “biometeo” as an abbreviation of “human biometeorology”. This section first describes the biometeo library functions, followed by an explanation of the library installation and its input and output variables.

Biometeo library functions

Table 1 summarizes the biometeo library functions, categorized as the auxiliary functions and computational models of human biometeorological indices. The biometeo library mainly provides the computational models of human biometeorology to calculate PET30, Predicted Mean Vote (PMV)42, UTCI27,28 based on Fiala-model43,44,45, SET*31 and specifically an innovative thermal index—mPET34,35,36. Beside of air temperature in \(^{\circ }\)C (\(T_{a}\)), calculating these thermal indices requires \(T_{mrt}\), vapor pressure in hPa (VP), and wind speed at the height of 1.1 m in m/s (\(v_{1.1\textrm{m}}\)) along with basic input variables in the biometeo Python package. These necessary input variables are not always available by regular measurements. The original UTCI requires wind speed at the height of 10 m in m/s (\(v_{10\textrm{m}}\)) as one of standard input variable, which is different from the other thermal indices. The input of wind speed variable of UTCI in biometeo package is \(v_{1.1\textrm{m}}\). This will be automatically adjusted with a wind speed exponential function to \(v_{10\textrm{m}}\) in the biometeo package46. This unified the input variables for users to calculate thermal indices. \(T_{mrt}\) can be calculated by two indirect measurement approaches using black globe temperature47 or six-directional radiation fluxes48. However, these two measurements are not regular meteorological measurement variables. Thus, \(T_{mrt}\) is simulated by several different approaches. The simplest approach is only the given solar constant which is related to the local target time and coordinate information including longitude, latitude, and elevation above sea level. The more accurate approach adds global radiation or cloud cover ratio as a variable, while the third approach also includes respectively or assembly additional variables, such as sky view factor, diffuse radiation, and fish eye photo. The Windows-based RayMan application was designed to simulate \(T_{mrt}\)32, 33. These three approaches to simulate \(T_{mrt}\) are provided by RayMan and now inherited by biometeo except fisheye photo approach. Otherwise, \(v_{1.1\textrm{m}}\)is needed to calculate thermal indices. Regular wind speed measurements are taken at a height of 10 m, based on recommendations from the World Meteorological Organization49. This requires an additional function to deduce wind speed from 10 to 1.1 m46. Thermal indices are commonly calculated using vapor pressure, relative humidity or both. Most datasets or reporting stations only provide vapor pressure or relative humidity, but both may be required to calculate the thermal index. Finally, these three additional functions are appended in the biometeo library.

Table 1 Biometeo library functions.
Full size table

Biometeo library installation

The Python library biometeo is installed simply with a Python pip command as follow:

$$\begin{aligned} \boxed {{\text {pip3 install biometeo}}} \end{aligned}$$

Installation of the Python library biometeo requires Python versions 3.8, 3.9, or 3.10 running on Windows, Linux, or Mac OS. All installation information can also be found at:

$$\begin{aligned} \boxed {{\text {https://pypi.org/project/biometeo/}}} \end{aligned}$$

Input and output variables of biometeo library

The input and output variables are numerous and complex in biometeo library. The explanation and abbreviation of the variables will be considered in the section.

Input and output variables for human biometeorological indices

The basic input variables for calculating rational thermal indices are the \(T_{a}\), VP or relative humidity in % (RH), \(v_{1.1\textrm{m}}\) or wind speed at the height of 10 m in m/s (\(v_{10\textrm{m}}\)), and \(T_{mrt}\). The PMV, PET, and mPET require \(T_{a}\), VP, \(v_{1.1\textrm{m}}\), and \(T_{mrt}\) as fundamental environmental inputs. SET* requires \(T_{a}\), RH, \(v_{1.1\textrm{m}}\), and \(T_{mrt}\) as basic input. The original UTCI only applies \(T_{a}\), VP, \(v_{10\textrm{m}}\), and \(T_{mrt}\) to assess the thermal perception. Hereby, UTCI in the biometeo package applies \(v_{1.1\textrm{m}}\) . In addition to environmental variables, calculating thermal indices also requires thermo-physiological and textile variables. All of the above mentioned thermal indices except UTCI require identifying inputs for both the thermo-physiological and textile variables. The UTCI considers an idealized walking subject with corresponding clothing insulation of individual subject in clo (\(I_{cl}\)) to current \(T_{a}\)50. On contrary, SET* and PMV all require input of a certain \(I_{cl}\). The \(I_{cl}\) of the PET is fixed at 0.9 clo. The mPET can alternatively input individual \(I_{cl}\) or apply \(I_{cl}\) corresponding to the current \(T_{a}\). The necessary thermo-physiological variables for SET* are activity loading of individual subject in W (work), height of individual subject in m (ht) and body weight of individual subject in kg (mbody). PMV also requires age of individual subject (age) and gender of individual subject (gender) as input. PET and mPET further require defining posture of the individual subject (pos). Briefly, \(I_{cl}\), work, ht, mbody, age, gender, and pos are additional thermo-physiological and textile variables used as inputs in biometeo. The basic output of these thermal indices are effective temperature (SET* and UTCI), equivalent temperature (PET and mPET), or thermal perception level (PMV). PMV uses another two output variables (Teq) and heat loss through clothing (hclo)—to validate PMV as a reasonable result. The computational model of PET and mPET generate more thermo-physiological parameters and energy fluxes as outputs than the SET*-model. These thermo-physiological parameters and energy fluxes include core temperature of individual subject in \(^{\circ }\)C (\(T_{core}\)), skin temperature of individual subject in \(^{\circ }\)C (\(T_{sk}\)), wearing clothing temperature in \(^{\circ }\)C (\(T_{cl}\)), skin wettedness of subject (dimensionless) (wetsk), total metabolic rate in W (h), respiratory energy fluxes of subject in W (\(E_{re}\)), convective energy fluxes of subject in W (\(c_{sum}\)), radiative energy fluxes of subject in W (\(r_{sum}\)), skin diffuse energy fluxes of subject in W (\(E_{d}\)), and sweating evaporative energy fluxes of subject in W (\(E_{sw}\)) for PET. The additional thermo-physiology and energy fluxes output for mPET are listed as \(T_{core}\), mean skin temperature of subject in \(^{\circ }\)C (\(T_{sk, mm}\)), mean wearing clothing temperature of subject in \(^{\circ }\)C (\(T_{cl, mm}\)), mean skin vapor pressure of subject in hPa (\(VP_{ts, mm}\)), mean skin wettedness of subject (dimensionless) (\(sk_{wetted, mm}\)), saturated ration of subject skin (dimensionless) (\(wet_{sk}\)), h, \(E_{re}\), \(c_{sum}\), \(r_{sum}\), and all total evaporative energy fluxes of subject skin in W (\(wet_{sum}\)). Finally, to calculate PMV, UTCI, PET, and mPET the foundational inputs are four environmental variables. Other optional variables can be automatically obtained using default values or values provided by users. The following are practical examples of applying the biometeo computational model.

$$\begin{aligned} \boxed {\{PMV, Teq, hclo\} = biometeo.PMV(Ta=20.0, VP=12.5, v=0.1, Tmrt=20.0)} \end{aligned}$$
$$\begin{aligned} \boxed {SET^{*} = biometeo.SET(Ta=20.0, RH=50.0, v=0.1, Tmrt=20.0)} \end{aligned}$$
$$\begin{aligned} \boxed {UTCI = biometeo.UTCI(Ta=20.0, VP=12.5, v=0.5, Tmrt=20.0)} \end{aligned}$$
$$\begin{aligned} \boxed {\begin{aligned}&\{PET\_v, Tcore, Tsk, Tcl, wetsk, metabolic\_rate, respiratory\_flux, convective\_flux, \\&radiative\_flux, diffuse\_flux, sweating\_flux\}= biometeo.PET(Ta=20.0, VP=12.5, v=0.1, Tmrt=20.0, work=\\&80, gender=1) \end{aligned}} \end{aligned}$$
$$\begin{aligned} \boxed {\begin{aligned}&\{mPET, Tcore, Tsk\_mm, Tcl, vpts, wetsk, icl, sk\_wetted\_mm, metabolic\_rate,\\&wet\_sum, convective\_flux, radiative\_flux, respiratory\_flux, energy\_balance\} = biometeo.mPET(Ta=20.0, VP=\\&12.5, v=0.1, Tmrt= 0.5,, icl=1.8, clo\_auto=False) \end{aligned}} \end{aligned}$$

Input and output variables for auxiliary functions

VP_RH_exchange and \(V_{1\textrm{m}}\)_cal are two simple functions. VP_RH_exchange requires only \(T_{a}\) and either VP or RH to calculate the other. \(V_{1\textrm{m}}\)_cal requires only wind speed and the height of wind measurement to generate the \(v_{1.1\textrm{m}}\). The two functions can be applied as in the following examples.

$$\begin{aligned} \boxed {\{VP\} = biometeo.VP\_RH\_exchange(Ta=20.0, RH=50.0)} \end{aligned}$$

or

$$\begin{aligned} \boxed {\{RH\} = biometeo.VP\_RH\_exchange(Ta=20.0, VP=12.5)} \end{aligned}$$

and

$$\begin{aligned} \boxed {v_{1.1\textrm{m}} = biometeo.v1\textrm{m}\_cal(WS=8.5, height=60)} \end{aligned}$$

The more complex of the three auxiliary functions is \(T_{mrt}\)_calc. The input variables of \(T_{mrt}\)_calc function include local time in floating hour format (hour_of_day), time zone offset (timezone_offset), longitude in ± 180 \(^{\circ }\) (longitude), latitude in ± 90 \(^{\circ }\) (latitude), sea level height in m (sea_level_height), day of the year (day_of_year), \(T_{a}\), VP, RH, \(v_{1.1\textrm{m}}\), cloud cover in 0–8 octals (N), global radiation in W/m\(^{2}\) (G), ratio of diffuse and global radiation (dimensionless) (DGratio), surface temperature in \(^{\circ }\)C (\(T_{ob}\)), Linke turbidity (dimensionless) (ltf), sky view factor in 0.0–1.0 (OmegaF), albedo of the surrounding (dimensionless) (alb), albedo of the human being (dimensionless) (albhum), reduction of G presetting by obstacles in boolean (RedGChk), lower limit of RH for full diffuse radiation in % (foglimit), and Bowen ratio (dimensionless) (bowen). The output of the \(T_{mrt}\)_calc function includes maximum of directional solar radiation in W/m\(^{2}\) (Imax), maximum of global radiation in W/m\(^{2}\) (Gmax), maximum of diffuse solar radiation in W/m\(^{2}\) (Dmax), current directional solar radiation in W/m\(^{2}\) (Itat), current global radiation in W/m\(^{2}\) (Gtat), current diffuse solar radiation in W/m\(^{2}\) (Dtat), atmospheric long wave radiation in W/m\(^{2}\) (A), long wave radiation from surface in W/m\(^{2}\) (Eu), long wave radiation from sides in W/m\(^{2}\) (Es), and the most important variable—\(T_{mrt}\). A following simple case calculates the current \(T_{mrt}\) for a given \(T_{a}\), RH, \(v_{1.1\textrm{m}}\), and longitude, latitude, and the sea level height. The other necessary inputs are automatically set up as default values.

$$\begin{aligned} \boxed {\begin{aligned}&\{Tmrt, VP, Imax, Gmax, Dmax, Itat, Gtat, A, Eu, Es, Tob\} = biometeo.Tmrt\_calc(Ta=20.0, RH=50.0, v=\\&0.1, longitude=121.5, latitude=23.5, sea\_level\_height=30) \end{aligned}} \end{aligned}$$

Calculation of \(T_{mrt}\) at specified time requires hour_of_day, day_of_year, and timezone_offset. Otherwise, G, N, DGratio, and OmegaF are commonly used optional inputs to calculate precise \(T_{mrt}\) under specifically spatial and temporal conditions. Hereby, OmegaF should be applied with shadowed or non-shadowed conditions. Therefore, OmegaF can be only fixed in 1.0 in \(T_{mrt}\)_calc. See the following example:

$$\begin{aligned} \boxed {\begin{aligned}&\{Tmrt, VP, Imax, Gmax, Dmax, Itat, Gtat, A, Eu, Es, Tob\} = biometeo.Tmrt\_calc(Ta=20.0, RH=50.0, v=\\&0.1, longitude=121.5, latitude=23.5, sea\_level\_height=30, hour\_of\_day=15.8, day\_of\_year=\\&210, timezone\_offset=8, N=6) \end{aligned}} \end{aligned}$$

All of the necessary inputs, optional inputs, default, and outputs of the functions and thermal indices are summarized in Table 2.

Table 2 Inputs and outputs of biometeo package.
Full size table

Comparison of biometeo and RayMan

Comparisons between RayMan and biometeo in PET, mPET, UTCI, and \(T_{mrt}\), applying old data set generated by original RayMan in Freiburg from 1999 to 2004, are shown in Fig. 1. It is hardly feasible to get the hardware and old-version Windows to recalculate PMV and SET* by RayMan. Also, we have no previous datasets to be able to validate them. Figure 1a and e show that biometeo is not significantly different from RayMan to calculate PET and UTCI. On contrary, the mPET which results from biometeo is slightly different from the mPET from RayMan. The obvious difference occurs, while the mPET from RayMan is higher than about 28 \(^{\circ }\)C (Fig. 1b). Comparing the mPETs from RayMan and biometeo to the PET from RayMan, we can find that the distribution of xy-paring in mPET from biometeo versus PET from RayMan are different from other one (Fig. 1c,d). The reasonable causes are that Delphi has no matrices operation libraries and sufficiently accurate floating point arithmetic, while Python has Numpy library and advanced precision in floating-point operations. The difference between Tmrt from RayMan and that from biometeo may also be caused by the similar reasons (Fig. 1f). Calculating \(T_{mrt}\) requires solar zenith and trigonometric functions. Python has better trigonometric functions supported by Numpy than Delphi. The difference of \(T_{mrt}\) occurs regularly at the moments of sunrise and sunset. This could be caused by the operations of trigonometric functions and if-loop. Overall, biometeo can generate almost the same PET and UTCI as RayMan. The mPET from biometeo was further revised as an more appropriate thermal index than from RayMan. The \(T_{mrt}\) generated by biometeo is applicable. However, the precision of \(T_{mrt}\) from biometeo should further validated to the observation data.

Figure 1
figure 1

Applying regularly measured meteorological data from Freiburg weather stations from 1999 to 2004 to compare (a) PET from RayMan (old) and biometeo (new), (b) mPET from RayMan (old) and biometeo (new), (c) PET and mPET from RayMan (old), (d) PET from RayMan (old) and mPET from biometeo (new), (e) UTCI from RayMan (old) and biometeo (new), and (f) \(T_{mrt}\) from RayMan (old) and biometeo (new).

Full size image

Example of use

This section provides two examples to illustrate the application of biometeo integrated with the other Python packages for scientific visualization. The first example uses regularly measured meteorological data from Taiwan’s Central Weather Bureau (CWB) to investigate the thermal environment of north Taiwan. The CWB data follows the measurement rules of the World Meteorological Organization49. We apply the \(T_{a}\), \(v_{10\textrm{m}}\), RH, N, and also the geographic information of weather stations to calculate the mPET with VP_RH_exchange, \(V_{1\textrm{m}}\)_cal, \(T_{mrt}\)_calc, and mPET Python module in the biometeo library, with Fig. 2. This is the monthly probability of thermal perception in two stations—Taipei and Danshuei—in north Taiwan during 2011 to 2016 on a topography map. The north Taiwan is classified as Cfa classification according to the Köppen–Geiger climate map51,52. The Fig. 2 showning rsults for the monthly probability of thermal perception in two north Taiwan stations—Taipei and Danshuei from 2011 to 2016. The figure is visualized using the matplotlib Python package implemented using basemap and gdal Python packages. This kind of visualization can be used to simply and effectively investigate seasonal differences of thermal stress in different regions. Figure 3 shows the thermal sensation in a grid format on an administration distinct map. The mPET on this map is calculated using biometeo with meteorological data from the Weather Research and Forecasting (WRF) Model53,54,55. A previous study applied RayMan as an external support on a Windows routine to calculate \(T_{mrt}\) and mPET with WRF output on a Linux sever56. In this case, global radiation from WRF was withdrawn by netCDF4 Python package and directly applied as Gtat to be inserted into the \(T_{mrt}\)_calc of the biometeo library to calculate the \(T_{mrt}\). Afterward, mPET was generated by inserting \(T_{a}\), VP, \(v_{1.1\textrm{m}}\), and \(T_{mrt}\) into the mPET computational model. Finally, a visualization thermal perception map was generated (Fig. 3). These two cases show the potential for the interdisciplinary application of biometeo to investigate human biometeorology.

Figure 2
figure 2

A case study applying regularly measured meteorological data from Taipei and Danshuei weather stations from 2011 to 2016 to investigate the probability of monthly thermal conditions.

Full size image
Figure 3
figure 3

Reanalyzing monthly mean data for July 2011 using weather regional and forecast model downscaling to consider geographically thermal condition patterns, shown in Mercator projection overlaid with urban administration districts.

Full size image

Discussion and summary

RayMan was previously an effective, widely applicable, and convenient method for calculating rational thermal indices, including most of the most widely used indices, such as PET, PMV, PT, SET* and UTCI7,11,57. RayMan could simulate \(T_{mrt}\) through several approaches, such as only given coordinates and target time, or any additional term from G, DGratio, N, OmegaF, and fisheye photo or building obstacle map32,33. Although previous studies58,59 critiqued the precision of \(T_{mrt}\) simulations by RayMan, convenience and various modeling conditions made RayMan a multifunctional and multipurpose software for investigating human biometeorology, thermal perception, urban climates, and tourism. However, due to update and maintenance issues related to Delphi, RayMan updates and support terminated after Windows 7. The proposed biometeo library recapitulates parts of RayMan functionality in Python to calculate thermal indices and simulate \(T_{mrt}\). The major contributions of biometeo are the computational model and calculation processes for the innovative thermal index—mPET34,35,36. mPET is currently the only practical thermal index based on the dynamic thermo-physiological model and semi-steady state for the evaluation of thermal perception. The mPET model in biometeo is improved for effective computation and a comprehensive and realistic thermal index. To simulate \(T_{mrt}\), biometeo avoids complicated approaches involving the application of fisheye photos or building obstacle maps. However, the \(T_{mrt}\) generated by biometeo is slightly different by RayMan in sunset and sunrise moment. This should be further validated. Another Python package—pythermalcomfort—underperforms in terms of simulating \(T_{mrt}\)and requires additional external function support to obtain \(T_{mrt}\), despite containing numeric models of PMV, Standard Effective Temperature in \(^{\circ }\)C (SET), UTCI, PET, WBGT, and other empirically thermal indices37. Thermofeel focuses on connection to the outputs of weather numeric model to calculate \(T_{mrt}\) and UTCI38. Ladybug-tool has been shown with lots of uncertainties to evaluate thermal perception41. Future work will append new functions and input methods to simulate \(T_{mrt}\) in biometeo, using improved image processing from fisheye photo and integrating Geographic Information System (GIS) data through GIS libraries in Python. Moreover, Python-based biometeo can be used to bridge various input file formats and datasets, such as simple text or csv files (pandas), complex netCDF-formats (netCDF4), and SQL-database (pyodbc), allowing for improved computational efficiency across different operating systems to generate useful scientific images and visualizations. Finally, future developments in advanced thermo-physiological mechanisms will allow for continuous improvement and development of mPET and other thermal indices. In summary, the Python package biometeo is a widely applicable, convenient and comprehensive tool to calculate effectively rational thermal indices for assessing thermal perception for application in urban climate and sustainable urban design, tourism, and public health across various spatial and temporal scales. Most importantly, biometeo is the only Python package with sufficient supporting tools for calculating mPET.