Skip to main content
  • Loading metrics

TrenchR: An R package for modular and accessible microclimate and biophysical ecology


Much understanding of organismal responses to climate change and variability relies on the assumption that body temperatures are equal to temporally averaged air temperatures high above the ground. However, most organisms experience microclimates near the ground and acute exposure to solar and thermal radiation and thermal extremes can substantially elevate or depress their body temperatures. We introduce the TrenchR package, which aids in Translating Environmental Change into organismal responses. The package includes microclimate models to vertically scale weather station data to organismal heights. Additional functions model and temporally partition air and soil temperatures and solar radiation. TrenchR biophysical modeling tools include both general models for heat flows and specific models to predict body temperatures for a variety of ectothermic taxa. We also offer utility functions to aid in estimating the organismal and environmental parameters needed for biophysical ecology. TrenchR focuses on simple and modular functions so users can create transparent and flexible models for biophysical applications. The package aims to introduce and enable microclimate and biophysical modeling to improve ecological and evolutionary forecasting. We further this aim through a series of educational modules that introduce the field of biophysical ecology.


Responses of organisms and ecosystems to climate change are heterogeneous and thus inconsistent with current predictive models [1]. Some of these predictive shortcomings stem from omitting spatial and temporal environmental variation and how it interacts with organismal phenotypes (e.g., size, coloration) [2, 3]. Many analyses assume that organismal body temperatures are equal to shaded air temperatures inside a screen at weather station height (usually 2 meters). However, air temperatures near the ground where most organisms reside are often considerably warmer, and absorption of solar and thermal radiation can raise body temperatures well above air temperatures, resulting in potential discrepancies of tens of degrees Celsius [46]. The rapid drop in performance and onset of thermal stress at high body temperatures can amplify the biological significance of underestimations [7].

Applications are increasingly demonstrating the importance of accounting for microclimate variation [810]. Acute thermal stress events are often more relevant to the physiology and energy balance of organisms than daily, monthly, or annually averaged environmental conditions. Yet, daily and seasonal environmental variation is often neglected [11, 12]. We aim to help remedy these shortcomings by introducing the TrenchR package ( as a component of the TrEnCh project (, which builds computational and visualization tools to Translate Environmental Change into organismal responses.

The mathematical tools for leveraging environmental data to predict organismal conditions have long lingered in books [13, 14] and articles [15, 16], but adoption of these tools has not kept pace with research on climate change responses. In recent decades, adoption of biophysical approaches is expanding with recognition of the importance of spatial and temporal environmental variation to determining climate change responses [17, 18] and the increased dissemination of computational tools.

Estimating how organisms experience their thermal environment generally entails two classes of models [13, 14] (Fig 1). Microclimate models allow scaling conditions from sensors to organism height. They can characterize heat and air transport to estimate vertical air and soil temperature and wind profiles. They can also characterize direct and diffuse solar radiation and longwave radiation emanating from the sky, ground, and surrounding objects like vegetation. Microclimate model output is used as input in biophysical models, which estimate body temperatures using an energy budget to balance heat exchanges between organisms and their environment.

Fig 1.

A) Microclimate models scale air and soil temperatures and wind speeds from sensor to organismal heights. B) Biophysical models balance heat exchanges between organisms and their environment to estimate body temperatures [19]. A thermal image depicts how grasshopper body temperatures vary substantially from vegetation, air, and ground temperatures due to heat exchange.

The TrenchR package is intended to complement the NicheMapR package, which includes sophisticated microclimate [18] and biophysical [20] models. Although the Fortran source code was recently released, the complexity of NicheMapR functions can make it difficult to understand and modify the source code and Fortran can be complicated to compile and run. The integrated functions made it difficult to separate and adapt different forms of heat flow, but we note that some modular R functions were made available during the review process for this manuscript that enable comparison with the TrenchR package (S1 Text). Many of the approaches are similar between the packages, but TrenchR provides simple R functions to aid the understanding and accessibility of biophysical approaches. The TrenchR functions are modular and easily adapt to a variety of organisms and research questions.

Although many of the TrenchR functions are general, some components of TrenchR are best suited for small ectothermic animals since body temperatures are generally assumed to be uniform and at steady-state. We omit plant specific biophysical models since they are the focus of several R packages [tealeaves: [21]; plantecophys: [22]]. Some energy budget calculation components of biophysical models are also available in the ThermImage package [23]. Microclimate models, with an emphasis on describing spatial variation, are also available in the microclima package [24].The microclimc package enables accounting for how forest canopies alter microclimates [25].

The development of increasingly complex microclimate and biophysical models before open and reproducible science was emphasized or feasible has limited their uptake. Yet, such models are crucial to improving understand and prediction of species responses to climate change. Simple and modular functions can be combined and extended in a null modeling approach until the model adequately describes organismal interactions with their environment while remaining accessible and transparent. Many applications will warrant the inclusion of more complex microclimate and biophysical algorithms from R packages such as NicheMapR, microclima, and microclimc.

Methods and features

The TrenchR package ( aims to promote accessibility and reproducibility. We welcome contributions and corrections from users. Our package was built using the devtools methodology ( with version control managed in Github. Issues and feature requests can be contributed in Github ( The package is available via CRAN and Github.

Validation against sensor data including from physical models of organisms is essential to microclimate and biophysical modelling. We adapted well established and validated functions from biophysical ecology textbooks [13, 14] and research articles. Source references are cited in function headers and reference sections. Many of the references, particularly those developing taxa-specific biophysical models, contain extensive empirical validation. S2 Text illustrates validation of biophysical models using a physical model of a grasshopper. S1 Text compares TrenchR functions to NicheMapR functions. We have incorporated default parameters (e.g., organism emissivity or heat conduction rates) when general values are available. Many functions additionally include comments that describe potential parameterizations. The biophysical ecology texts [13, 14] include many tables with parameter values and we provide several data tables describing solar and thermal absorptivity in TrenchR.


TrenchR functions are organized into the following categories (Fig 2):

Utility functions.

Calculate environmental metrics that form the basis of microclimate and biophysical models (e.g., zenith and declination angles, which describe the angles of incident sunlight), facilitate modeling diurnal temperature variation, and estimate biologically relevant aggregate metrics such as degree days available for organismal development.

Allometric functions.

Allow estimating the dimensions of organisms needed for energy balances and other analyses. Available functions can convert between organismal length, mass, surface area, and volume as well as estimate the silhoutte area, which describes the organismal area exposed to solar radiation.

Microclimate functions.

Facilitate calculating the environmental conditions experienced by organisms. Temperature and wind profile functions scale environmental conditions from sensors to organismal height. Radiation functions allow estimating incoming solar radiation and partitioning the variation diurnally and across components (i.e., direct, diffuse, reflected).

General biophysical functions.

Provide generalized models of heat exchanges between organisms and their environment so that users can build custom biophysical models. The functions allow implementing an energy balance including the following components of heat exchange between organisms and their environment:

  • radiative heat exchanges of solar and thermal radiation;
  • convective heat exchanges between organisms and their surrounding fluid (air or water) driven by fluid flow;
  • conductive heat exchanges between organisms and solid surfaces (generally the ground) due to physical contact; and
  • evaporative and metabolic heat exchanges associated with organisms’ evaporative water loss and metabolic heat generation.

Additional functions aggregate these forms of heat exchange into energy balances and to use the energy balances to predict body temperatures.

Fig 2. An examplar aim of translating from environmental and phenotypic data to organismal conditions in a given environment (grey boxes) can be achieved in TrenchR via several categories of functions (white boxes).

We list example functions for each category used in the example application below.

Specific biophysical functions.

provide biophysical models that have been built for particular organisms based on their physical properties, behavior, environment, and life history. We currently provide published biophysical models for lizards, salamanders, butterflies, grasshoppers, limpets, mussels, and snails. Most models predict operative environmental temperatures, which are the steady-state body temperatures of organisms with specified physical properties in a specific microclimate and assume no heat exchange via metabolism or evaporation [26]. However, we also present an analytical function for humid operative temperature that incorporates the effects of evaporative cooling on operative temperatures for wet-skinned ectotherms, such as salamanders.

Vignettes and introductory tutorials

We introduce the functions in several vignettes. A good place to start is the Allometry and Conversions vignette, which provides tools for preparing data, such as estimating additional dimensions of organisms from measured dimensions. The Estimating Microclimates vignette provides resources for estimating the environmental conditions experienced by organisms. This includes estimating solar radiation and its components, diurnal variation in temperature and radiation, temperature and wind speed profiles, and soil temperatures and profiles. Finally, the core biophysical modeling functions are described in a tutorial on Using Energy Balances to Estimate Body Temperatures. Components of an energy budget can be estimated using individual functions and then body temperatures can be solved for using either a generic energy balance or taxa specific biophysical models. We additionally offer a List of Symbols used in equations.

For additional background on microclimate and biophysical modeling, we have updated a series of tutorials entitled Physical Processes in Ecosystems. We intend the tutorials to provide a more contained and accessible introduction to microclimate and biophysical modeling than that included in classic textbooks [13, 14]. The tutorials provide less detailed coverage of many of the topics contained in the books. The series of 14 tutorials starts with an overview of the calculus and physics principles underlying the modeling.

Thermodynamics and energy budget modeling are then introduced with detailed examples. Tutorials address the climate space concept, operative temperatures, biophysical models for leaves and sheep, and heat flow in soils. We have revised the tutorials (which originated from an NSF training grant in 1979 and lacked broad distribution) to include R code and utilization of TrenchR functions. We expanded the original series to include tutorials contributed by M. Kearney introducing the Microclim environmental data [27] and integrating the Microclim data with biophysical modeling to examine broad scale climatic limits. The tutorials are provided in html form and available for download as a pdf at the bookdown server ( R markdown files for the tutorials are available in Github (


We illustrate the use of the TrenchR package by estimating an energy budget for a Sceloporus lizard on June 1, 2021 in Santa Fe, New Mexico, USA (35.69°N, -105.944°W, elevation: 2121 m). The simplified example, which is designed to be self-contained, is also incorporated in the Using energy balances to estimate body temperatures vignette. We start by generating environmental inputs (Fig 2). Using these inputs, we estimate the energy budget with component functions. Finally, we use an integrated biophysical model to estimate operative environmental temperatures. See S2 Text for a more realistic example examining a time series of microclimate data and applying and testing the biophysical models.

We will use the energy budget to estimate body temperature, Tb, which can depart dramatically from the air temperatures due to heat exchange with the environment. Heat energy is exchanged with the environment by way of solar and thermal radiation, metabolic reactions, and evaporation. The organism also exchanges heat with the surrounding air or water via convection and with substrate it is in contact with via conduction. The balance of these heat exchanges (omitting metabolism and evaporation, which are often negligible for ectotherms) can be estimated and often referred to as operative environmental temperature, Te [26]. Te is an estimate of Tb and the package functions refer to Tb for simplicity. Our exemplar estimation of Tb assumes steady-state thermal conditions. Additionally, we assume that the lizard’s body temperature is homogenous, which is generally reasonable for small ectotherms. Approaches to account for thermal gradients between the animal’s core and its skin are available elsewhere [28].

Let us assume the lizard is in an unshaded location where a weather station at standard height (2 meters) reports that the daily air temperature varies from a minimum of 10°C to a maximum of 25°C and the wind speed averages 1 m/s. The soil surface temperature varies from a minimum of 15°C to a maximum of 30°C. We assume that atmospheric transmissivity τ = 0.7 and albedo ρ = 0.6.

Environmental data

At the first stage, we prepare the environmental data for analysis. We will estimate hourly air and soil temperatures and radiation using a function describing diurnal temperature variation. We start by estimating the day of year and the timing of sunrise and sunset:

  1. # Set up input data as variables
  1. lat <- 35.69 # Latitude (degrees)
  2. lon <- -105.944 # Longitude (degrees)
  3. elev <- 2121 # Elevation (meters)
  1. Tmin <- 10 # Minimum air temperature (C)
  2. Tmax <- 25 # Maximum air temperature (C)
  3. Tmin_s <- 15 # Minimum soil temperature (C)
  4. Tmax_s <- 30 # Maximum soil temperature (C)
  5. u <- 1 # Wind speed (m/s)
  1. # Assumptions
  1. tau <- 0.7 # Atmospheric transmissivity
  2. rho <- 0.6 # Albedo
  3. Tb0 <- 25 # Initial assumption of body temperature (C)
  1. doy <- day_of_year("2021-06-01", format = "%Y-%m-%d") # Day of year
  1. snoon <- solar_noon(lon = lon, doy = doy) # Estimate solar noon
  2. dayl <- daylength(lat = lat, doy = doy) # Estimate day length
  1. tr <- snoon—dayl / 2 # Time of sunrise
  2. ts <- snoon + dayl / 2 # Time of sunset

Although measured solar radiation is preferable if available, we can estimate hourly solar radiation by discounting incoming solar radiation as it moves through the atmosphere as follows. We use the approach from Cambpell and Norman [14], which uses an empirical relation to partition radiation into direct, diffuse, and reflected components. The partition_solar_radiation() function includes 8 empirical relationships for, and the proportion_diffuse_solar_radiation() includes a more complex numerical approximation for, partitioning radiation components as described in the Estimating microclimates vignette.

  1. # Estimate zenith angle (degrees)
  1. psi_deg <- sapply(0:23, FUN = zenith_angle, doy = doy, lat = lat, lon = lon)
  1. # Convert to radians
  1. psi_rad <- degrees_to_radians(psi_deg)
  1. # Estimate radiation
  1. Srad <- sapply(psi_rad, FUN = solar_radiation, doy = doy, tau = tau, elev = elev, rho = rho)
  1. # Separate solar radiation into direct, diffuse, and reflected components
  1. Sdir <- Srad[1,] # Direct solar radiation (W/m2)
  2. Sdif <- Srad[2,] # Diffuse solar radiation (W/m2)
  3. Sref <- Srad[3,] # Reflected solar radiation (W/m2)

We then calculate hourly air and soil surface temperatures based on daily minimum and maximum temperatures. We select the sine-exponential model for air temperature and the sine model for surface temperature [29]:

  1. # Air temperature (C)
  1. Ta <- sapply(1:24, diurnal_temp_variation_sineexp, T_max = Tmax, T_min = Tmin, t_r = tr, t_s = ts, alpha = 2.59, beta = 1.55, gamma = 2.2)
  1. # Soil surface temperature (C)
  1. Ts <- sapply(1:24, diurnal_temp_variation_sine, T_max = Tmax_s, T_min = Tmin_s)

At the second stage, we use microclimate models to scale air temperature (Tr) and wind speed (ur) from weather station height (reference height zr = 2 m) to lizard height (organism height z = 0.02 m). We assume a surface roughness of z0 = 0.2 m, which corresponds to bare sand and determines the turbulence of airflow. We implement free air temperature and wind speed profiles driven by density differences but profiles forced by wind speed are also available.

  1. # Neutral air temperature profile
  1. Ta_liz <- air_temp_profile_neutral(T_r = Ta, zr = 2, z0 = 0.2, z = 0.02, T_s = Ts)
  1. # Neutral wind speed profile
  1. u_liz <- wind_speed_profile_neutral(u_r = u, zr = 2, z0 = 0.2, z = 0.02)

Energy balance

Finally, we will use our microclimates estimates to solve the following energy balance to estimate Te: where Qnet is the net energy exchange with the environment (W), Qabs is the solar radiation absorbed (W), Qemit is the net thermal radiation emitted (W), Qconv is energy exchange due to convection (W), Qcond is energy exchange due to conduction (W), Qmet is the energy generated by metabolism (W), and Qevap is the energy generated by evaporative water loss (W). We will estimate each term on the right side of the equation in turn. Estimating Qabs requires the surface area exposed to radiation and the solar absorptivity of the animal surface (a proportion). We use zenith angle psi to estimate the projected (silhouette) area as a portion of the surface area of the organism, which allows estimating absorbed solar radiation. We model a 10 gram Sceloporus lizard with solar absorptivity a = 0.9 [13]. We will initially assume Tb = Ta + 10 to illustrate the calculations before solving for Tb given the environmental conditions.

  1. mass <- 10 # Mass (g)
  2. svl <- 0.006 # Snout vent length (meters)
  3. a <- 0.9 # Solar absorptivity (proportion)
  1. #assume 1/3 of surface area is in contact with surface
  2. psa_g <- 0.33
  1. # Estimate surface area (m^2) and the proportion sihouette area
  1. A <- surface_area_from_mass(mass, "lizard")
  2. psa <- sapply(psi_deg, proportion_silhouette_area, taxon = "lizard", posture = "prostrate")
  1. # Change negative values to zero
  2. psa[psa < 0] = 0

We calculate the hourly solar and thermal radiation absorbed (W) as follows:

  1. Qabs <- rep(NA, 24)
  2. for (hour in 1:24) {
  1. Qabs[hour] <- Qradiation_absorbed(a = a, A = A, psa_dir = psa[hour], psa_dif = 0.5, psa_ref = 0.5, S_dir = Sdir[hour], S_dif = Sdif[hour], rho = rho)
  1. }

We estimate thermal radiation Qemit (W) for the lizard outdoors, where psadir and psaref are the view factors, also refered to as configuration factors, that indicate the proportions of surface area A (m2) exposed to the sky and ground, respectively. We assume the surface emissivity of lizards, epsilons = 0.965 [30].

  1. epsilon_s <- 0.965 # Surface emissivity of lizards
  1. Qemit <- rep(NA, 24)
  2. for (hour in 1:24) {
  1. Qemit[hour] <- Qemitted_thermal_radiation(epsilon = epsilon_s, A = A, psa_dir = 0.5, psa_ref = 0.5, T_b = Ta_liz[hour] + 273.15, T_g = Ts[hour] + 273.15, T_a = Ta_liz[hour] + 273.15, enclosed = FALSE)
  1. }

We next estimate convection Qconv (W) and conduction Qcond (W). We will estimate the lizard’s heat transfer coefficient, HL (Wm-2K-1) using an empirical relationship for lizards (heat_transfer_coefficient()). We average thermal conductivity and kinematic viscosity across the day for simplicity and since there is not substantial diurnal variation. We also illustrate a function estimating HL using a spherical approximation (heat_transfer_coefficient_approximation()) and a simplified approximation (heat_transfer_coefficient_simple()) for cases when taxon specific relationships for estimating heat transfer coefficients are not available. We estimate the characteristic dimension, which determines exposure to convective heat exchange as the cube root of volume, assuming the animal density approximates that of water [31].

These coefficients assume convection is forced by the wind. TrenchR includes approaches for free convection and a function (free_or_forced_convection()) that evaluates whether free or forced convection is appropriate. The function uses dimensionless numbers, which have been developed to describe heat transfer coefficients associated with convection over different geometries and can be estimated using TrenchR (e.g., Grashof, Nusselt, and Reynolds numbers).

  1. # Use DRYAIR from NicheMapR to estimate the thermal conductivity of air and kinematic viscosity.
  1. ap <- airpressure_from_elev(elev) * 1000 # Barometric pressure (pascal)
  1. DRYAIRout <- DRYAIR(db = Ta, bp = ap, alt = elev)
  1. K <- mean(DRYAIRout$thcond) # Thermal conductivity (Wm^-2K^-1)
  2. nu <- mean(DRYAIRout$viskin) # Kinematic viscosity (m2 s-1)
  1. # Estimate the characteristic dimension as cube root of volume, assuming density of water as 1000kg/m^3
  1. D <- ((mass / 1000) / 1000) ^ (1 / 3)
  1. # Estimate the heat transfer coefficient using an empirical relationship for lizards
  1. H_L <- heat_transfer_coefficient(u = u_liz, D = D, K = K, nu = nu, taxon = "lizard_surface")
  1. # Estimate the heat transfer coefficient using a spherical approximation
  1. H_L2 <- heat_transfer_coefficient_approximation(u = u_liz, D = D, K = K, nu = nu, taxon = "lizard")
  1. # Estimate the heat transfer coefficient using a simplified version of the approximation
  1. H_L3 <- heat_transfer_coefficient_simple(u = u_liz, D = svl, type = "Gates")

We estimate convective heat exchange between the animal and surrounding air using the following relationship: where an enhancement factor, ef, multiplier can be incorporated to account for increases in heat exchange resulting from air turbulence in field conditions. We implement the function in R assuming that 2/3 of the lizard’s surface area is exchanging heat through convection.

  1. Qconv <- rep(NA, 24)
  2. for (hour in 1:24) {
  1. Qconv[hour] <- Qconvection(T_a = Ta_liz[hour] + 273.15, T_b = Ta_liz[hour] + 10 + 273.15, H = H_L, A = A, proportion = 0.67, ef = 1.3)
  1. }

We estimate conductive heat flow (W) from the lizard to the surface assuming conductance through the animal tissue is the rate limiting step as follows:

where Kskin in the thermal conductivity of lizard skin (Wm-2K-1). We implement the estimate assuming that conductive heat exchange occurs down to a soil depth of 2.5cm. We use this value rather than skin thickness, which results in rapid conduction and does not readily reach steady state conditions.

  1. Qcond <- rep(NA, 24)
  2. for(hr in 1:24) {
  1. Qcond[hr] <- Qconduction_animal(T_g = Ts[hr] + 273.15, T_b = Ta_liz[hr] + 10 + 273.15, d = 0.025, K = 0.5, A = A, proportion = psa_g)
  1. }

We assume, as is generally done for lizards, that heat exchange associated with metabolism and evaporation is negligible. However, functions for estimating both forms of heat exchange available in TrenchR.

  1. Qmet <- 0
  2. Qevap <- 0

The full heat budget can be calculated as follows [13]:

  1. Qnet <- Qnet_Gates(Qabs = Qabs, Qemit = Qemit, Qconv = Qconv, Qcond = Qcond, Qmet = Qmet, Qevap = Qevap)

We now use a function based on the Gates energy balance above to estimate body temperature given the environmental conditions:

  1. Te <- rep(NA, 24)
  2. for (hour in 1:24) {
  1. Te[hour] <- Tb_Gates(A = A, D = svl, psa_dir = psa[hour], psa_ref = 1—psa[hour], psa_air = 0.67, psa_g = 0.25, T_g = Ts[hour], T_a = Ta_liz[hour], Qabs = Qabs[hour], epsilon = epsilon_s, H_L = H_L, ef = 1.3, K = K)
  1. }

We also implement a similar but simplified energy balance [14]. The energy balance omits conduction with the ground:

  1. Te2 <- rep(NA, 24)
  2. for (hr in 1:24) {
  1. # S is solar radiation flux (W m^-2), so we divide by surface area, A
  1. Te2[hr] <- Tb_CampbellNorman(T_a = Ta_liz[hr], T_g = Ts[hr], S = Qabs[hr] / A, a_l = 0.96, epsilon = epsilon_s, c_p = 29.3, D = D, u = u_liz)
  1. }

We additionally estimate Tb using a specialized function for lizards [32], where Fd, Fr, Fa, and Fg are the view factors between the surface of the lizard and diffuse solar radiation, reflected solar radiation, atmospheric thermal radiation, and ground thermal radiation, respectively:

  1. Te3 <- rep(NA, 24)
  2. for (hour in 1:24) {
  1. Te3[hour] <- Tb_lizard(T_a = Ta_liz[hour], T_g = Ts[hour], u = u_liz, svl = svl * 1000, m = mass, psi = psi_deg[hour], rho_s = rho, elev = elev, doy = doy, sun = TRUE, surface = TRUE, a_s = a, a_l = 0.965, epsilon_s = epsilon_s, F_d = 0.8, F_r = 0.5, F_a = 0.5, F_g = 0.5)
  1. }

The microclimate models indicate that air temperatures at lizard height are similar to surface temperatures (Fig 3). The biophysical models indicate that solar radiation can elevate lizard body temperatures far above air temperatures and that the lizard will face thermal stress if it is unable to seek shade (Fig 3). The three biophysical models predict different body temperatures during peak period of solar radiation because they model interactions with the ground differently and users are encouraged to review the details of each biophysical model and perform empirical validations before selection. Differences in estimated body temperatures are accentuated by the high level of solar radiation. Tb_Gates is a general and comprehensive model that is appropriate for many applications. Taxa-specific biophysical models often best account for details of organism environment interactions and have generally been well tested.

Fig 3. Body temperatures (Te) are predicted to drastically exceed air temperature when lizards are exposed to high levels of solar radiation.

Air temperatures (Ta, °C) at lizard height (0.02 m) are predicted to exceed air temperatures at 2 m and to be similar to surface temperatures (Ts). We estimate body temperatures using two general energy budgets [solid: Tb_Gates(); dotted: Tb_CampbellNorman()] and a lizard specific biophysical model [dashed: Tb_lizard()] that differ in how they model heat exchanges.


TrenchR is intended to promote understanding of how organisms interact with their environment and consequences for physiology, energetics, behavior, and demography. Our example implementation highlights the importance of considering organismal body temperatures, rather than air temperatures, when examining thermal stress and other responses to environmental variability and change. TrenchR currently focuses on heat balances but may be expanded to include water balances. Simple functions can be combined as needed to produce comprehensive and transparent models for biophysical ecology and evolution. The resultant models are likely to be sufficiently detailed for many applications, but users are referred to NicheMapR for more detailed biophysical models [18, 20]. We focus on models that predict steady-state conditions for simplicity (that is, steady-state conditions). Such models generally do not present computational challenges so our models are not optimized for computational efficiency. Making classic biophysical ecology techniques more accessible will allow researchers to take advantage of rapidly accumulating data on environmental conditions and organismal traits to understand and predict ecological and evolutionary responses. Considering how organisms experience their environment is central to understanding responses to variable and changing environments [33].

Supporting information

S1 Text. We compare TrenchR and NicheMapR implementations.

We thank Michael Kearney for making modular R functions corresponding to NicheMapR available and providing code comparing TrenchR and NicheMapR functions during the review process. Our adaptation of the provided code corresponds to the operative temperature estimation in the manuscript. The NicheMapR implementation relies on the micro_global environmental data available through NicheMapR. The modular NicheMapR functions are available in version 3.2.1 via GitHub (


S2 Text. We provide an additional example using microclimate data measured along an elevation gradient in CO, USA to illustrate use of TrenchR.

We first use a time series of air temperatures and wind speeds collected at multiple heights to examine profiles and surface roughness. We then use a time series of air and surface temperatures, wind speeds, and solar radiation collected at a single height to implement a biophysical model for grasshoppers and compare estimates to observations. We omit the code to read and process the environmental data here for brevity. R markdown files with the full code and the associated environmental data are available at



We thank A. Cannistra, R. Huey, J. Kingsolver, L. Miller, W. Porter, R. Potter, and H. A. Woods for assistance and input and B. Helmuth for providing functions. We particularly thank M. Kearney for extensive input on TrenchR and its alignment with NicheMapR and for contributing two educational modules and code for comparing TrenchR to NicheMapR.


  1. 1. Maguire KC, Nieto-Lugilde D, Fitzpatrick MC, Williams JW, Blois JL. Modeling species and community responses to past, present, and future episodes of climatic and ecological change. Annual Review of Ecology, Evolution, and Systematics. 2015;46:343–368.
  2. 2. Nadeau CP, Urban MC, Bridle JR. Coarse climate change projections for species living in a fine-scaled world. Global change biology. 2017;23: 12–24. pmid:27550861
  3. 3. Potter KA, Arthur Woods H, Pincebourde S. Microclimatic challenges in global change biology. Global change biology. 2013;19: 2932–2939. pmid:23681970
  4. 4. Sinclair BJ, Marshall KE, Sewell MA, Levesque DL, Willett CS, Slotsbo S, et al. Can we predict ectotherm responses to climate change using thermal performance curves and body temperatures? Ecology Letters. 2016;19: 13721385. Available: pmid:27667778
  5. 5. Sunday JM, Bates AE, Kearney MR, Colwell RK, Dulvy NK, Longino JT, et al. Thermal-safety margins and the necessity of thermoregulatory behavior across latitude and elevation. Proceedings of the National Academy of Sciences. 2014;111: 56105615. Available: pmid:24616528
  6. 6. Kearney MR, Shine R, Porter WP. The potential for behavioral thermoregulation to buffer “cold-blooded” animals against climate warming. Proceedings of the National Academy of Sciences. 2009;106: 3835–3840. pmid:19234117
  7. 7. Buckley LB, Huey RB, Kingsolver JG. Asymmetry of thermal sensitivity and the thermal risk of climate change. Global Ecology and Biogeography. 2022;31: 2231–2244.
  8. 8. Bramer I, Anderson BJ, Bennie J, Bladon AJ, De Frenne P, Hemming D, et al. Advances in monitoring and modelling climate at ecologically relevant scales. Advances in ecological research. 2018;58: 101–161.
  9. 9. Bütikofer L, Anderson K, Bebber DP, Bennie JJ, Early RI, Maclean IM. The problem of scale in predicting biological responses to climate. Global Change Biology. 2020;26: 6657–6666. pmid:32956542
  10. 10. Lembrechts JJ, Lenoir J, Roth N, Hattab T, Milbau A, Haider S, et al. Comparing temperature data sources for use in species distribution models: From in-situ logging to remote sensing. Global Ecology and Biogeography. 2019;28: 1578–1596.
  11. 11. Dillon ME, Woods HA. Introduction to the symposium: Beyond the mean: Biological impacts of changing patterns of temperature variation. Integrative and comparative biology. 2016;56: 11–13. pmid:27252197
  12. 12. Dillon ME, Woods HA, Wang G, Fey SB, Vasseur DA, Telemeco RS, et al. Life in the frequency domain: The biological impacts of changes in climate variability at multiple time scales. Integrative and Comparative Biology. 2016;56: 14–30. pmid:27252201
  13. 13. Gates DM. Biophysical ecology. Courier Corporation; 1980.
  14. 14. Campbell GS, Norman J. An introduction to environmental biophysics. Springer Science & Business Media; 2000.
  15. 15. Porter WP, Gates DM. Thermodynamic equilibria of animals with environment. Ecological monographs. 1969;39: 227–244.
  16. 16. Porter WP, Tracy CR. Biophysical analyses of energetics, time-space utilization, and distributional limits. Lizard ecology: Studies of a model organism. 1983; 55–83.
  17. 17. Buckley LB, Cannistra AF, John A. Leveraging organismal biology to forecast the effects of climate change. Integrative and comparative biology. 2018;58: 38–51. pmid:29701771
  18. 18. Kearney MR, Porter WP. NicheMapR–an r package for biophysical modelling: The microclimate model. Ecography. 2017;40: 664–674.
  19. 19. Porter WP, Mitchell JW, Beckman WA, DeWitt CB. Behavioral implications of mechanistic ecology. Oecologia. 1973;13: 1–54.
  20. 20. Kearney MR, Porter WP. NicheMapR–an r package for biophysical modelling: The ectotherm and dynamic energy budget models. Ecography. 2020;43: 85–96.
  21. 21. Muir CD. Tealeaves: An r package for modelling leaf temperature using energy budgets. AoB Plants. 2019;11: plz054. pmid:31844509
  22. 22. Duursma RA. Plantecophys-an r package for analysing and modelling leaf gas exchange data. PloS one. 2015;10: e0143346. pmid:26581080
  23. 23. Tattersall GJ. Thermimage: Thermal image analysis. Dec; 2017.
  24. 24. Maclean IM, Mosedale JR, Bennie JJ. Microclima: An r package for modelling meso-and microclimate. Methods in Ecology and Evolution. 2019;10: 280–290.
  25. 25. Maclean IM, Klinges DH. Microclimc: A mechanistic model of above, below and within-canopy microclimate. Ecological Modelling. 2021;451: 109567.
  26. 26. Bakken GS. Measurement and application of operative and standard operative temperatures in ecology. American Zoologist. 1992;32: 194–216.
  27. 27. Kearney MR, Isaac AP, Porter WP. Microclim: Global estimates of hourly microclimate based on long-term monthly climate averages. Scientific data. 2014;1: 1–9. pmid:25977764
  28. 28. Porter WP, Johnson E, Martin Y. Heat balances in ecological contexts. A biogeoscience approach to ecosystems. 2016; 49–87.
  29. 29. Wann M, Yen D, Gold HJ. Evaluation and calibration of three models for daily cycle of air temperature. Agricultural and Forest Meteorology. 1985;34: 121–128.
  30. 30. Barlett PN, Gates DM. The energy budget of a lizard on a tree trunk. Ecology. 1967;48: 315–322.
  31. 31. Mitchell JW. Heat transfer from spheres and other animal forms. Biophysical Journal. 1976;16: 561–569. pmid:1276385
  32. 32. Buckley LB. Linking traits to energetics and population dynamics to predict lizard ranges in changing environments. The American Naturalist. 2008;171: E1–E19. pmid:18171140
  33. 33. Suggitt AJ, Wilson RJ, Isaac NJ, Beale CM, Auffret AG, August T, et al. Extinction risk from climate change is reduced by microclimatic buffering. Nature Climate Change. 2018;8: 713–717.