📝 Temperature size rules

docs/src/man/temperature.md

@@ -9,7 +9,7 @@ The default behavior of the model will always be to assume that none of the biol
 - exponential Boltzmann Arrhenius function
 - extended Boltzmann Arrhenius function
 - Gaussian function
--
+
 These functions determine the shape of the thermal curves used to scale the biological rates with temperature.
 
 ### General example
@@ -313,4 +313,50 @@ p_newvalues = model_parameters(A, handlingtime = Gaussian(:handlingtime, paramet
 
 ## Temperature dependence for body sizes
 
+The default behavior of the model is to assume, as it does for biological rates, that typical adults body sizes are not affected by temperature. In this case, the bodymass vector can eighter:
+- be provided to `model_parameters` through the keyword `bodymass`: `model_parameters(A, bodymass = [...])`
+- be calculated bu `model_parameters` as $Mi= Z^(TR_i-1)$ where $TR_i$ is the trophic level of species $i$ and $Z$ is the typical consumer-resource body mass ratio in the system. $Z$ can be passed to `model_parameters` by using the `Z` keyword: `model_parameters(A, Z = 10.0)`
+- be calculated a vector of dry masses (at 293.15 Kelvins) provided by the user: `model_parameters(A, dry_mass_293 = [...])`
+
+If multiple keywords are provided, the model will use this order of priority: body masses, dry masses, Z.
+
+To simulate the effect of temperature on body masses, the model uses the following general formula:
+
+$$
+M_i(T) = m_i * exp(log_{10}(PCM / 100 + 1) * T - 293.15)
+$$
+
+Where $M_i$ is the body mass of species $i$, $T$ is the temperature (in Kelvins), $m_i$ is the mody mass when there is no effect of temperature (provided by the user through `Z`, `bodymass` or `dry_mass_293`) and $PCM$ is the Percentage change in body-mass per degree Celsius. This percentage is calculated differently depending on the type of system or the type of response wanted:
+
+- Mean Aquatic: $PCM = -3.90 - 0.53 * log_{10}(dm)$ where $dm$ is the dry mass (calculated in the model from Z or wet mass if not provided). Body size decreases with temperature.
+- Mean Terrestrial: $PCM = -1.72 + 0.54 * log_{10}(dm)$ where $dm$ is the dry mass (calculated in the model from Z or wet mass if not provided). Body size decreases with temperature.
+- Maximum: $PCM = -8$. Body size decreases with temperature.
+- Reverse: $PCM = 4$. Body size **increases** with temperature.
+
+To set the temperature size rule, use the `TSR` keyword in `model_parameters`:
+
+``` julia
+A = [0 1 1 ; 0 0 1 ; 0 0 0] #omnivory motif
+p_aqua = model_parameters(A, T = 290.0, TSR = :mean_aquatic) #mean aquatic, wet and dry masses calculated from Z and trophic levels (Z default value is 1.0)
+p_terr = model_parameters(A, T = 290.0, TSR = :mean_terrestrial, bodymass = [26.3, 15.2, 4.3]) #mean terrestrial, typical wet masses (at 20 degrees C) are provided and will we used to estimate dry masses and wet masses at T degrees K.
+p_max = model_parameters(A, T = 290.0, TSR = :maximum, dry_mass_293 = [1.8, 0.7, 0.2]) #maximum, dry masses are provided and will be used by the temperature size rule to calculate wet masses at T degrees K.
+p_rev =  model_parameters(A, T = 290.0, TSR = :maximum, Z = 10.0) #reverse - masses increse with T, wet and dry masses calculated from Z and trophic levels.
+```
+
 # References
+
+Amarasekare, P. (2015). Effects of temperature on consumer–resource interactions. Journal of Animal Ecology, 84(3), 665-679.
+
+Bernhardt, J. R., Sunday, J. M., Thompson, P. L., & O'Connor, M. I. (2018). Nonlinear averaging of thermal experience predicts population growth rates in a thermally variable environment. Proceedings of the Royal Society B: Biological Sciences, 285(1886), 20181076.
+
+Binzer, A., Guill, C., Brose, U., & Rall, B. C. (2012). The dynamics of food chains under climate change and nutrient enrichment. Philosophical Transactions of the Royal Society B: Biological Sciences, 367(1605), 2935-2944.
+
+Binzer, A., Guill, C., Rall, B. C., & Brose, U. (2016). Interactive effects of warming, eutrophication and size structure: impacts on biodiversity and food‐web structure. Global change biology, 22(1), 220-227.
+
+Brose, U., Williams, R. J., & Martinez, N. D. (2006). Allometric scaling enhances stability in complex food webs. Ecology letters, 9(11), 1228-1236.
+
+Englund, G., Öhlund, G., Hein, C. L., & Diehl, S. (2011). Temperature dependence of the functional response. Ecology letters, 14(9), 914-921.
+
+Eppley, R. W. (1972). Temperature and phytoplankton growth in the sea. Fish. bull, 70(4), 1063-1085.
+
+Kremer, C. T., Thomas, M. K., & Litchman, E. (2017). Temperature‐and size‐scaling of phytoplankton population growth rates: Reconciling the Eppley curve and the metabolic theory of ecology. Limnology and Oceanography, 62(4), 1658-1670.