NicheMapR v3.2.1 - Now including a modularised version of the ectotherm model, improved dew and frost calculations, links to terraclimate historical and future scenarios, and functions for computing liquid water exchange with soil for ectotherms and their eggs

This release includes some substantial additions and improvements:

A modularised ectotherm model - ectoR_devel

The ectotherm heat budget calculations have been modularised in a series of new functions used by the master function 'ectoR_devel' which is similar in usage and approach to endoR_devel. It doesn't include any behaviour, the transient heat budget calculations, or the Dynamic Energy Budget models etc. of the 'ectotherm' function, just the heat budget and associated evaporative water exchange from respiration and the skin. It is fully in R based on R conversions of the relevant Fortran code from 'ectotherm'. It will be useful for learning and teaching the model, testing its behaviour, and for the development of customised behavoiural routines and integrations with metabolic theory.

Here is the full list of new functions that ectoR_devel uses:

GEOM_ecto (calculates biophyiscally relevant surfaces, volumes and dimensions)
SOLAR_ecto (calculates incoming solar)
RADIN_ecto (calculates incoming long-wave radiation)
RADOUT_ecto (calculates outgoing long-wave radiation)
CONV_ecto (calculates convective exchange and heat/mass transfer coefficients)
COND_ecto (calculates conductive heat exchange - very simply)
SEVAP_ecto (calculates cutaneous evaporative heat and water loss)
MET_ecto (calculates metabolic heat via allometry)
RESP_ecto (calculates respiratory heat and water exchange)
WATERPROP (calculates thermal properties of water)
FUN_ecto (computes the full heat budget for a given body temperature, used with a guessing algorithm (e.g. uniroot in R) to find a body temperature that balances the heat budget)

Improved calculations of dew and frost

This release also includes updated code in the microclimate model for computing dew and frost, where the amount in mm forming per hour is now calculated rather than presence/absence, using the formulation of Garratt and Segal (1988).

New capability for computing liquid and gaseous water exchange, and modelling egg development

This release includes new functionality for predicting heat and water exchange of developing eggs and water exchange in general. A major aspect of this is a new R function 'egg_water' which is incorporated into the ectotherm model as 'DGET_PSI.f', which computes simultaneous exchange of water as liquid (driven by water potential gradients) and gas (driven by vapour density gradients). The vapour exchange calculation has been expanded by allowing specification of the water potential of the organism, which can allow uptake of water vapour under high humidity when the solutes of the body reduce the vapour density at the surface of the organism to below that of the surrounding air. To allow egg temperature to be predicted in the soil, the microclimate model now produces outputs for bulk thermal conductivity. Bulk specific heat capacity and bulk density are also provided as outputs. The DEB model calculations have been expanded to improve heat production calculations (see below) which are important for egg water exchange, and the water budget has been more tightly linked to the DEB stoichiometric calculations. Full details are provided in Kearney and Enriquez-Urzelai (2022).

Connections to terraclimate

The release also includes the micro_terra function to connect to the terraclimate monthly climate database at ~4km res across the globe from 1958 to present (Abatzoglou et al. 2018). A function called 'get_terra' has been added which retrieves the required data via opendap or locally. The terraclimate data set includes climate change scenarios of +2 and +4 deg C. Code has been added to the 'micro_ncep' and 'micro_era5' functions to apply these terraclimate climate change scenarios to their predictions.

The 'micro_era5' function, integrating the powerful ERA5 historical weather data set, was added to the package prior to the last release but has been formally described and tested the recent paper in Methods in Ecology and Evolution, found here.

Other changes, fixes and improvements

The following issues were also addressed:

Microclimate model

• added code to 'micro_era5' to ensure rain falls at midnight irrespective of where midnight falls relative to UTM-based input data

Endotherm model

• fixed an error that crept in after the 'PANT_MULT' variable was changed to being an actual multiplier, which was causing panting metabolic costs to be subtracted rather than added
• passing zenith angle into the 'GEOM' function for silhouette area calculations
• removing redundant (and incorrectly functioning) 'TIMACT' because all multipliers on metabolic rate for activity etc. should be applied to 'QBASAL'
• ensured decimal points for all whole numbers throughout Fortran code - this was causing incorrect output after the transition to R v4.2 (compiler behaviour is mysterious)

Ectotherm model

• changed the calculation of the convection coefficient (and mass transfer coefficient) in the ectotherm model from summing the free and forced values to weighting them via a combined Nusselt number using Bird, Stewart and Lightfoot's (2002, p. 445) mixed convection formula. This was also changed in the transient heat exchange functions 'onelump', 'onelump_var' and 'twolump'. This would have slightly overestimated the total convection under mixed or free convection conditions
• added user specification of the soil and sky emissivity to the ectotherm model, these previously being assigned values of 1 by default
• related to the previous change, the emissivity environment (sky and ground) is set to 1 if the organism is below ground
• removed limitations on the minimum body temperature (previously there for stability purposes), including the limit of 0 deg C for the live = 0 scenario
• allowing hourly varying air pressure to be given to the ectotherm model
• allowing vapour pressure at the skin/egg surface to be driven by body water potential and hence to have potentially lower than saturation vapour pressure (and thus permitting water uptake as vapour when the integument is highly permeable and environmental humidity high)

DEB model heat production

• in all DEB functions, including those in the ectotherm model, heat production calculations are updated so that they are based on enthalpies rather than Gibbs energies, using an empirical relation between stoichiometry and enthalpy, to be described in a future paper led by Marko Jusup
• fixed an issue in how the reproduction and batch buffers were drained during starvation in the DEB models, which was preventing them from being fully depleted

R version of 'gads' (global aerosol database)

• adding the R function gads and thus the option to run GADS outside of the microclimate model because the Fortran version crashes on some OSX system due to an inexplicable segfault when the data tables are read
• also fixing issues in the original gads.f that led to erroneous results or crashes at some sites

References

Abatzoglou, J. T., Dobrowski, S. Z., Parks, S. A., & Hegewisch, K. C. (2018). TerraClimate, a high-resolution global dataset of monthly climate and climatic water balance from 1958–2015. Scientific Data, 5(1), 170191. https://doi.org/10.1038/sdata.2017.191

Bird, R. B., Stewart, W. E., & Lightfoot, E. N. (2002). Transport Phenomena (2nd ed.). Wiley and Sons.

Garratt, J. R., & Segal, M. (1988). On the contribution of atmospheric moisture to dew formation. Boundary-Layer Meteorology, 45(3), 209–236. https://doi.org/10.1007/BF01066671

Kearney, M. R., & Enriquez‐Urzelai, U. (in press). A general framework for jointly modelling thermal and hydric constraints on developing eggs. Methods in Ecology and Evolution.

Klinges, D. H., Duffy, J. P., Kearney, M. R., & Maclean, I. M. D. (2022). mcera5: Driving microclimate models with ERA5 global gridded climate data. Methods in Ecology and Evolution https://doi.org/10.1111/2041-210X.13877