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

NicheMapR v3.1.0 - Now including an official release of the endotherm model

This is the official release of the endotherm model of NicheMapR, timed with the publication of the accompanying software note in Ecography:

Kearney M. R., Briscoe N. J., Mathewson, P. D. & Porter W. P. (2019) NicheMapR - an R package for biophysical modelling: the endotherm model. Ecography 43: 1-11. doi: 10.1111/ecog.05550

It includes major corrections to the equations for conduction from the previously released version, with the vignette describing all the equations in the model updated accordingly along with some other minor corrections.

It also rectifies an error that crept in to version 3 of NicheMapR's ectotherm model, whereby the egg batch buffer in the DEB model was filling faster than it should have been.

NicheMapR v3.0.0

This is a major update on the NicheMapR package, being an official release of the transient heat budget models (i.e. accounting for mass-related heating lag) in the form of the functions 'onelump', 'onelump_var', 'twolump' and the 'trans_behav' alogorithm. It also includes a fully open source version of the endotherm model. The release is timed with a forthcoming paper in Methods in Ecology and Evolution on the transient thermoregulation model.

Ectotherm and DEB model updates

The 'onelump' transient heat budget algorithm has been incorporated into the ectotherm function and is run when the parameter 'transient' is set to '1' (but it does not incorporate behaviour at present). The ectotherm function also now includes the 'powers' from the DEB model, i.e. energy flows for food intake, assimilation, mobilisation, maintenance, growth, reproduction/maturation, egg batch buffer, maturity maintenance, and dissipation (p_A, p_C, p_M, p_G, p_R, p_B, p_J, p_D, respectively). This can be useful for analysing the energy budget. The DEB parameter F_m (maximum food encounter rate) was previously an input but really it should have been p_Xm (maximum food energy intake rate), which has now been corrected.

Endotherm model

An issue with the longwave heat loss calculation was resolved in this version and a new vignette providing a full derivation and explanation of the model has been added. Also, some code causing a preemptive increase in core temperature for high air temperatures relative to body temperature was removed from the standard behavioural algorithm. The model is now fully open source and the endoR_devel function runs much faster than before as a result of all the code being in the NicheMapR dynamic link library.

NicheMapR v2.0.0 - Now including an official release of the ectotherm model

This is a major update on the NicheMapR package, being an official release of the ectotherm model and associated Dynamic Energy Budget model scripts as well as introducing some major improvements to the microclimate model and including a beta version of the endotherm model. The release is timed with two publications on the package as indicated below. There is now also a website for the package:

https://mrke.github.io/

The Fortran code is now open source (except for aspects of the endotherm model, for the time being) and the whole package has been set up to compile the underlying Fortran code for the microclimate and ectotherm models on installation from github.

Microclimate model updates:

1. The micro_ncep function is now included, which integrates with the recently released microclima package https://github.com/ilyamaclean/microclima, as well as the RNCEP package https://CRAN.R-project.org/package=RNCEP and elevatr package https://CRAN.R-project.org/package=elevatr to allow estimates of historical microclimates anywhere in the world, as described in this paper:

Kearney M. R., Gillingham P. K., Bramer I., Duffy J. P. & Maclean I. M. D. (2019) A method for computing hourly, historical, terrain-corrected microclimate anywhere on Earth. Methods in Ecology and Evolution.

2. The micro_usa function is finalised, which connects to the gridMET ~4km USA climatology (see Kearney, M. R. (2019). microclimUS: hourly estimates of historical microclimates for the United States of America with example applications. Ecology, 0(ja), e02829. doi:10.1002/ecy.2829).

3. The RnetCDF package is now used in place of ncdf4, which has the big bonus of allowing opendap connectivity on all platforms (ncdf4 wouldn't do this for Windows, although this has recently been rectified by pmjherman https://github.com/pmjherman/r-ncdf4-build-opendap-windows). This means you can set 'opendap =1' in micro_aust and micro_usa and you can web-query the weather grids of AWAP and gridMET, respectively.

4. All the microclimate functions (micro_global, micro_ncep, micro_aust, micro_usa, micro_nz, micro_uk) are set to use the SoilGrids database as an option for extracting textural and bulk density data from which hydraulic properties are derived (set 'soilgrids = 1').

5. An additional approach to computing the vertical air temperature profile has been added (in collaboration with Paul Mathewson), based on equations in Campbell, G. S., & Norman, J. M. (1998). Environmental Biophysics. New York: Springer. It can be invoked by making tne new parameter ZH greater than zero and explained further in the relevant help files and vignettes.

6. The global climate data set (global.climate.zip) is now provided as part of the release and the get.global.climate downloads it from here.

Ectotherm model

1. Although a beta version of the ectotherm model has been part of the package since its inception, it is now officially released with Fortran source included. The model is described in this software note:

Kearney M. R. & Porter W. P. (2019) NicheMapR - an R package for biophysical modelling: the ectotherm and Dynamic Energy Budget models. Ecography. doi 10.1111/ecog.04680

2. Compared to the earlier versions, the release version has some revisions to the naming of parameters for improved consistency, especially in regard to the Dynamic Energy Budget (DEB) model terminology. There is also improved and updated documentation including a revision of the vignette 'ectotherm model tutorial' and a new 'DEB model tutorial'. The DEB model functionality is also described in the software note mentioned above.

3. The DEB functionality has been improved by including the DOPRI5 integrator to do the integration through time (before a simple Euler method was used, and this option is still available), and the DEB models that can be run now include the standard model as before, but also the abj, abp and hex models (see http://www.debtheory.org/wiki/index.php?title=Typified_models). There are now also DEB R scripts for running the std, abj and abp DEB models independent of the ectotherm model. Code has been included to allow DEB model parameters to be passed directly from the DEB parameter database (now >2000 species), as explained in the 'DEB model tutorial' vignette.

Endotherm model

There is now a working beta version of the general endotherm model developed by Porter and colleagues over many years. This version is explained in two vignettes now included in the package and will be undergoing a number of updates over the next few months before being finalised. These updates will largely be cosmetic and the overall algorithm will remain unchanged. A software note will be produced explaining the model in detail.

NicheMapR Microclimate Model Release v1.1.4

This is a rather substantial revision of the microclimate model. The major aspects of this release include:

1. Fully open source code for the microclimate model under a GPLv3 license.

2. A Linux binary release (!), with thanks to Rafael Schouten for assistance with this.

3. Functionality to query the SoilGrid database for soil moisture related properties. You'll need to install GSIF and I've had trouble getting this to work on OSX and Ubuntu. See: http://gsif.isric.org/doku.php/wiki:tutorial_soilgrids - if you can get the "REST service for SoilGrids" example going on this page it will work in the microclimate functions. If not you'll have to specify the soil moisture property vectors (PE, KS, BB, BD) manually.

4. A replacement of all references to 'Julian days' with 'Day of Year' (DOY), since technically the former is the number elapsed days since noon on Monday, January 1, 4713 BC (thanks to Tim McVicar for pointing this problem out).

5. Some substantial revamps to the snow algorithm after extensive testing, including:

• snow density functions now based on days since snow, rather than DOY, and I have kept the original option for a linear function but also added capacity to include the four-parameter exponential function of Sturm et al. 2010 which includes snow depth as a factor too;
• a new output column in metout/shadmet for snow density so that snow water equivalent can be easily computed;
• fixed an issue with the way the model captures the phase transition between water and ice in both the snow pack and in the soil, that became apparent when running the model in very cold USA environments - it had a very large impact on soil temperatures, especially their tendency to stabilise near zero degrees C under the snow pack;
• added heat of fusion to the soil/snow heat budget for when snow is refreezing;
• the model cannot stably handle snow depths below 2 cm, so added code to save small snow falls until they can make it up to the 2 cm minimum threshold;
• fixed an issue with relative humidity in the shade at local height not being set properly and possibly exceeding 100%;
• ensured hourly rainfall forcing data was being used correctly for snow, making sure the melt factor was applied per hour at 1/24th the intensity;
• infiltration of water into soil under snow now only happens when snow temperature greater than zero (before it was erroneously happening whenever snow was present);
• made output for soil surface temperature always equal to that of the soil (not the snow skin, as was the case in the previous releases;
• included both shaded and unshaded snow pack temperature profiles in the output.

5. Some features to avoid excessive message output from the Fortran program and to kill the simulations if they are getting stuck in an endless loop:

• added the argument 'message' to suppress integrator messages when it is forced to restart the integration;
• added argument 'fail' which specifies the upper limit for integrator restarts before quitting to stop situations where there can be endless loops - if the model failed there will be zeros in all rows of the output files from where the problem occurred.

6. Some new functions are also included for running the microclimate model via daily forcing data from the NZ NIWA data set, the UK CHESS data set and the USA gridMET data set. The latter two can use opendaps to directly query the online data. Also, there's an opendap connection to the Australian AWAP/AGCD data from 1990-2015. Note that these opendap connections require the 'ncdf4' package which, for Windows, doesn't support opendaps. But, you can install from the compilation at https://github.com/pmjherman/r-ncdf4-build-opendap-windows and it should work. The examples for micro_usa and micro_aust should run fully from opendap connections to the respective weather data sets (with micro_aust assuming constant wind speed as there is as yet no opendap connection to daily wind grids).

7. Changed all real variables in the Fortran code to double precision to reduce integrator error occurrence.

NicheMapR Microclimate Model

This new release includes a couple of corrections and some additional features.

One correction is to the soil moisture algorithm. The value in Campbell's program 11.1 for VP (saturation vapour density) is fixed at the value for 20 degrees C and this was copied into the microclimate model code. However, it should vary with temperature and this correction has now been made (using the WETAIR function internal to the microclimate model). It will affect near surface (<5 cm) soil moisture calculations in particular.

The other correction relates to the emissivity value for the substrate, SLE (soil long wave emissivity) which had been erroneously hardwired at a value of 0.9 in the Fortran code but was meant to be accessible to the user to change. This is now fixed (most substrates have an emissivity between 0.9 and 0.95).

The additional features are to make the following parameters from the soil moisture model available to the user to alter: root radius, resistance per unit length of root and leaf, critical leaf water potential for stomatal closure, stability parameter for stomatal closure equation, maximum allowable mass balance error for soil moisture, maximum iterations for mass balance of soil moisture.

Also, the wavelength-specific solar radiation can now be outputted if required, with the option to undertake a more intensive calculation of the UV wavelengths if desired.

Finally, the model output now includes the snow temperature profiles in the sun and the shade (sunsnow and shadsnow) as well as plant outputs from Campbell's Program 11.1 (transpiration rate, leaf and root water potentials in the output matrices plant and shadplant).

NicheMapR Microclimate Model

This version now has scope to include hourly zenith angles to account for cases where the starting hour is not midnight (in which case you must pre-compute the zenith angles and provide them as input rather than having them be computed automatically via the solar radiation routines). There are also some minor typographical corrections to the "Microclimate Model Theory and Equations" vignette.

NicheMapR Microclimate Model

This version has a minor update to the way downward IR from cloud is computed (previously assumed cloud base temperature was the same as screen temperature but now using screen temperature - 2 deg C on advice of Warren Porter). It also fixes an issue that prevented the SCAN example dataset from being incorporated into the package.

NicheMapR Microclimate Model

This updated version of the microclimate model includes the capacity to use hourly weather data as input, in addition to the original daily min/max approach. The ectotherm model also has an updated and fully operational version of the holometabolus insect Dynamic Energy Budget model and a new option (warmsig) for activity to dependent on a warming signal if animal is in burrow.

NicheMapR microclimate model

This is the first release of the NicheMapR biophysical modelling system, specifically releasing the microclimate model component (the ectotherm model is also in this release together with some other functions but they are not fully documented nor finalised). This release is to be described formally as a software note currently in review. It includes a binary compiled for PC (i386 and x64) and OSX.