Merge pull request #73 from davidorme/release/0.10.0

Version 0.10.0 release

Author: davidorme

.github/workflows/pre-commit_autoupdate.yaml

@@ -8,10 +8,12 @@ jobs:
   auto-update:
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
       - uses: browniebroke/pre-commit-autoupdate-action@main
-      - uses: peter-evans/create-pull-request@v3
+      - uses: peter-evans/create-pull-request@v5
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           branch: update/pre-commit-hooks

CHANGES.txt

@@ -135,3 +135,9 @@
           author_year citation styling.
         - Constrain estimation of g_s to exclude VPD = 0 and ca - ci = 0, which give
           values tending to limit of infinity.
+0.10.0  - Implementation of the Mengoli et al 2023 soil moisture penalty factor. The
+          existing calc_soilmstress function is now calc_soilmstress_stocker and the
+          new function is calc_soilmstress_mengoli.
+        - The soilmstress argument to PModel is removed and both the Mengoli and Stocker
+          approaches are now intended to be applied as penalties to GPP after P Model
+          fitting, allowing the two to be compared from the same P Model outputs.

docs/source/refs.bib

@@ -716,3 +716,125 @@ @article{frank:2015a
 	pages = {579--583},
 	file = {Frank et al. - 2015 - Water-use efficiency and transpiration across Euro.pdf:/Users/dorme/Zotero/storage/DQE7I4U4/Frank et al. - 2015 - Water-use efficiency and transpiration across Euro.pdf:application/pdf},
 }
+
+@article{mengoli:2023a,
+	title = {A global function of climatic aridity accounts for soil moisture stress on carbon assimilation},
+	url = {https://egusphere.copernicus.org/preprints/2023/egusphere-2023-1261/},
+	doi = {10.5194/egusphere-2023-1261},
+	abstract = {{\textless}p{\textgreater}{\textless}strong class="journal-contentHeaderColor"{\textgreater}Abstract.{\textless}/strong{\textgreater} The coupling between carbon uptake and water loss through stomata implies that gross primary production (GPP) can be limited by soil water availability through reduced leaf area and/or reduced stomatal conductance. Vegetation and land-surface models typically assume that GPP is highest under well-watered conditions and apply a stress function to reduce GPP with declining soil moisture below a critical threshold, which may be universal or prescribed by vegetation type. It is unclear how well current schemes represent the water conservation strategies of plants in different climates. Here eddy-covariance flux data are used to investigate empirically how soil moisture influences the light-use efficiency (LUE) of GPP. Well-watered GPP is estimated using the P model, a first-principles LUE model driven by atmospheric data and remotely sensed green vegetation cover. Breakpoint regression is used to relate the daily value of the ratio \β(\θ) (flux-derived GPP/modelled well-watered GPP) to soil moisture, which is estimated using a generic water-balance model. Maximum LUE, even during wetter periods, is shown to decline with increasing climatic aridity index (AI). The critical soil-moisture threshold also declines with AI. Moreover, for any AI, there is a value of soil moisture at which \β(\θ) is maximized, and this value declines with increasing AI. Thus, ecosystems adapted to seasonally dry conditions use water more conservatively (relative to well-watered ecosystems) when soil moisture is high, but maintain higher GPP when soil moisture is low. An empirical non-linear function of AI expressing these relationships is derived by non-linear regression, and used to generate a \β(\θ) function that provides a multiplier for well-watered GPP as simulated by the P model. Substantially improved GPP simulation is shown during both unstressed and water-stressed conditions, compared to the reference model version that ignores soil-moisture stress, and to an earlier formulation in which maximum LUE was not reduced. This scheme may provide a step towards better-founded representations of carbon-water cycle coupling in vegetation and land-surface models.{\textless}/p{\textgreater}},
+	language = {English},
+	urldate = {2023-07-03},
+	journal = {EGUsphere},
+	author = {Mengoli, Giulia and Harrison, Sandy P. and Prentice, I. Colin},
+	month = jun,
+	year = {2023},
+	note = {Publisher: Copernicus GmbH},
+	pages = {1--19},
+	file = {Full Text PDF:/Users/dorme/Zotero/storage/JVIB9NS3/Mengoli et al. - 2023 - A global function of climatic aridity accounts for.pdf:application/pdf},
+}
+
+@techreport{allen:1998a,
+	address = {Rome},
+	title = {Crop evapotranspiration - {Guidelines} for computing crop water requirements},
+	number = {56},
+	institution = {FAO},
+	author = {Allen, Richard G. and Pereira, Luis S and Raes, Dirk and Smith, Martin},
+	year = {1998},
+	file = {Allen et al. - 1998 - Crop evapotranspiration - Guidelines for computing.pdf:/Users/dorme/Zotero/storage/68AVA64R/Allen et al. - 1998 - Crop evapotranspiration - Guidelines for computing.pdf:application/pdf},
+}
+
+@article{tsilingiris:2008a,
+	title = {Thermophysical and transport properties of humid air at temperature range between 0 and 100°{C}},
+	volume = {49},
+	issn = {0196-8904},
+	url = {https://www.sciencedirect.com/science/article/pii/S0196890407003329},
+	doi = {10.1016/j.enconman.2007.09.015},
+	abstract = {The aim of the present investigation is evaluation of the thermophysical and transport properties of moist air as a function of mixture temperature with relative humidity as a parameter, ranging between dry air and saturation conditions. Based on a literature review of the most widely available analytical procedures and methods, a number of developed correlations are presented, which are employed with recent gas mixture component properties as input parameters, to derive the temperature and humidity dependence of mixture density, viscosity, specific heat capacity, thermal conductivity, thermal diffusivity and Prandtl number under conditions corresponding to the total barometric pressure of 101.3kPa. The derived results at an accuracy level suitable for engineering calculations were plotted and compared with adequate accuracy with existing results from previous analytical calculations and measured data from earlier experimental investigations. The saturated mixture properties were also appropriately fitted, and the fitting expressions suitable for computer calculations are also presented.},
+	language = {en},
+	number = {5},
+	urldate = {2023-07-04},
+	journal = {Energy Conversion and Management},
+	author = {Tsilingiris, P. T.},
+	month = may,
+	year = {2008},
+	keywords = {Density, Prandtl number, Specific heat capacity, Thermal conductivity, Thermal diffusivity, Thermophysical properties, Viscosity},
+	pages = {1098--1110},
+	file = {ScienceDirect Full Text PDF:/Users/dorme/Zotero/storage/EZSDLB2V/Tsilingiris - 2008 - Thermophysical and transport properties of humid a.pdf:application/pdf;ScienceDirect Snapshot:/Users/dorme/Zotero/storage/IZWWYPC8/S0196890407003329.html:text/html},
+}
+
+@article{henderson-sellers:1984a,
+	title = {A new formula for latent heat of vaporization of water as a function of temperature},
+	volume = {110},
+	copyright = {Copyright © 1984 Royal Meteorological Society},
+	issn = {1477-870X},
+	url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/qj.49711046626},
+	doi = {10.1002/qj.49711046626},
+	abstract = {Existing formulae and approximations for the latent heat of vaporization of water, Lv, are reviewed. Using an analytical approximation to the saturated vapour pressure as a function of temperature, a new, temperature-dependent function for Lv is derived.},
+	language = {en},
+	number = {466},
+	urldate = {2023-07-04},
+	journal = {Quarterly Journal of the Royal Meteorological Society},
+	author = {Henderson-Sellers, B.},
+	year = {1984},
+	note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/qj.49711046626},
+	pages = {1186--1190},
+	file = {Snapshot:/Users/dorme/Zotero/storage/WJAU4R6F/qj.html:text/html},
+}
+
+@article{chen:2008a,
+	title = {The equation of state of pure water determined from sound speeds},
+	volume = {66},
+	issn = {0021-9606},
+	url = {https://doi.org/10.1063/1.434179},
+	doi = {10.1063/1.434179},
+	abstract = {The equation of state of water valid over the range 0–100 °C and 0–1000 bar has been determined from the high pressure sound velocities of Wilson, which were reanalyzed by Chen and Millero. The equation of state has a maximum error of ±0.01 bar−1 in isothermal compressibility and is in the form of a secant bulk modulus: K=V0P/(V0−V) =K0+AP+BP2, where K, K0, and V, V0 are the secant bulk moduli and specific volumes at applied pressures P and 0 (1 atm), respectively; A and B are temperature dependent parameters. The good agreement (to within 20×10−6 cm3 g−1) of specific volumes calculated using the above equation with those obtained from other modifications of the Wilson sound velocity data demonstrates the reliability of the sound velocity method for determining equations of state.},
+	number = {5},
+	urldate = {2023-07-04},
+	journal = {The Journal of Chemical Physics},
+	author = {Chen, Chen‐Tung and Fine, Rana A. and Millero, Frank J.},
+	month = aug,
+	year = {2008},
+	pages = {2142--2144},
+	file = {Full Text PDF:/Users/dorme/Zotero/storage/2WBI492T/Chen et al. - 2008 - The equation of state of pure water determined fro.pdf:application/pdf;Snapshot:/Users/dorme/Zotero/storage/IRHA5IDN/The-equation-of-state-of-pure-water-determined.html:text/html},
+}
+
+@article{hengl:2017a,
+	title = {{SoilGrids250m}: {Global} gridded soil information based on machine learning},
+	volume = {12},
+	issn = {1932-6203},
+	shorttitle = {{SoilGrids250m}},
+	url = {https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0169748},
+	doi = {10.1371/journal.pone.0169748},
+	abstract = {This paper describes the technical development and accuracy assessment of the most recent and improved version of the SoilGrids system at 250m resolution (June 2016 update). SoilGrids provides global predictions for standard numeric soil properties (organic carbon, bulk density, Cation Exchange Capacity (CEC), pH, soil texture fractions and coarse fragments) at seven standard depths (0, 5, 15, 30, 60, 100 and 200 cm), in addition to predictions of depth to bedrock and distribution of soil classes based on the World Reference Base (WRB) and USDA classification systems (ca. 280 raster layers in total). Predictions were based on ca. 150,000 soil profiles used for training and a stack of 158 remote sensing-based soil covariates (primarily derived from MODIS land products, SRTM DEM derivatives, climatic images and global landform and lithology maps), which were used to fit an ensemble of machine learning methods—random forest and gradient boosting and/or multinomial logistic regression—as implemented in the R packages ranger, xgboost, nnet and caret. The results of 10–fold cross-validation show that the ensemble models explain between 56\% (coarse fragments) and 83\% (pH) of variation with an overall average of 61\%. Improvements in the relative accuracy considering the amount of variation explained, in comparison to the previous version of SoilGrids at 1 km spatial resolution, range from 60 to 230\%. Improvements can be attributed to: (1) the use of machine learning instead of linear regression, (2) to considerable investments in preparing finer resolution covariate layers and (3) to insertion of additional soil profiles. Further development of SoilGrids could include refinement of methods to incorporate input uncertainties and derivation of posterior probability distributions (per pixel), and further automation of spatial modeling so that soil maps can be generated for potentially hundreds of soil variables. Another area of future research is the development of methods for multiscale merging of SoilGrids predictions with local and/or national gridded soil products (e.g. up to 50 m spatial resolution) so that increasingly more accurate, complete and consistent global soil information can be produced. SoilGrids are available under the Open Data Base License.},
+	language = {en},
+	number = {2},
+	urldate = {2023-07-05},
+	journal = {PLOS ONE},
+	author = {Hengl, Tomislav and Jesus, Jorge Mendes de and Heuvelink, Gerard B. M. and Gonzalez, Maria Ruiperez and Kilibarda, Milan and Blagotić, Aleksandar and Shangguan, Wei and Wright, Marvin N. and Geng, Xiaoyuan and Bauer-Marschallinger, Bernhard and Guevara, Mario Antonio and Vargas, Rodrigo and MacMillan, Robert A. and Batjes, Niels H. and Leenaars, Johan G. B. and Ribeiro, Eloi and Wheeler, Ichsani and Mantel, Stephan and Kempen, Bas},
+	month = feb,
+	year = {2017},
+	note = {Publisher: Public Library of Science},
+	keywords = {Agricultural soil science, Forecasting, Glaciers, Machine learning, Remote sensing, Shannon index, Soil pH, Trees},
+	pages = {e0169748},
+	file = {Full Text PDF:/Users/dorme/Zotero/storage/VS5FRVSK/Hengl et al. - 2017 - SoilGrids250m Global gridded soil information bas.pdf:application/pdf},
+}
+
+@article{davis:2017a,
+	title = {Simple process-led algorithms for simulating habitats ({SPLASH} v.1.0): robust indices of radiation, evapotranspiration and plant-available moisture},
+	volume = {10},
+	issn = {1991-959X},
+	shorttitle = {Simple process-led algorithms for simulating habitats ({SPLASH} v.1.0)},
+	url = {https://gmd.copernicus.org/articles/10/689/2017/},
+	doi = {10.5194/gmd-10-689-2017},
+	abstract = {Bioclimatic indices for use in studies of ecosystem function, species distribution, and vegetation dynamics under changing climate scenarios depend on estimates of surface fluxes and other quantities, such as radiation, evapotranspiration and soil moisture, for which direct observations are sparse. These quantities can be derived indirectly from meteorological variables, such as near-surface air temperature, precipitation and cloudiness. Here we present a consolidated set of simple process-led algorithms for simulating habitats (SPLASH) allowing robust approximations of key quantities at ecologically relevant timescales. We specify equations, derivations, simplifications, and assumptions for the estimation of daily and monthly quantities of top-of-the-atmosphere solar radiation, net surface radiation, photosynthetic photon flux density, evapotranspiration (potential, equilibrium, and actual), condensation, soil moisture, and runoff, based on analysis of their relationship to fundamental climatic drivers. The climatic drivers include a minimum of three meteorological inputs: precipitation, air temperature, and fraction of bright sunshine hours. Indices, such as the moisture index, the climatic water deficit, and the Priestley–Taylor coefficient, are also defined. The SPLASH code is transcribed in C++, FORTRAN, Python, and R. A total of 1 year of results are presented at the local and global scales to exemplify the spatiotemporal patterns of daily and monthly model outputs along with comparisons to other model results.},
+	language = {English},
+	number = {2},
+	urldate = {2023-07-05},
+	journal = {Geoscientific Model Development},
+	author = {Davis, Tyler W. and Prentice, I. Colin and Stocker, Benjamin D. and Thomas, Rebecca T. and Whitley, Rhys J. and Wang, Han and Evans, Bradley J. and Gallego-Sala, Angela V. and Sykes, Martin T. and Cramer, Wolfgang},
+	month = feb,
+	year = {2017},
+	note = {Publisher: Copernicus GmbH},
+	pages = {689--708},
+	file = {Full Text PDF:/Users/dorme/Zotero/storage/RUZWLGHT/Davis et al. - 2017 - Simple process-led algorithms for simulating habit.pdf:application/pdf},
+}

docs/source/users/pmodel/pmodel_details/lue_limitation.md

@@ -35,13 +35,11 @@ n_pts = 201
 
 # Create a range of representative values for key inputs.
 tc_1d = np.linspace(-25, 50, n_pts)
-soilm_1d = np.linspace(0, 1, n_pts)
 meanalpha_1d = np.linspace(0, 1, n_pts)
 co2_1d = np.linspace(200, 500, n_pts)
 
 # Broadcast the range into arrays with repeated values.
 tc_2d = np.broadcast_to(tc_1d, (n_pts, n_pts))
-soilm_2d = np.broadcast_to(soilm_1d, (n_pts, n_pts))
 meanalpha_2d = np.broadcast_to(meanalpha_1d, (n_pts, n_pts))
 co2_2d = np.broadcast_to(co2_1d, (n_pts, n_pts))
 ```
@@ -65,15 +63,14 @@ where $\phi_0$ is the quantum yield efficiency of photosynthesis, $M_C$ is the
 molar mass of carbon and $m_j$ is the $\ce{CO2}$ limitation term of light use
 efficiency from the calculation of optimal $\chi$.
 
-However, the {class}`pyrealm.pmodel.pmodel.PModel` class also incorporates three further
+However, the {class}`pyrealm.pmodel.pmodel.PModel` class also incorporates two further
 factors:
 
 * temperature (t) dependence of $\phi_0$,
 * $J_{max}$ limitation of $m_j$ by a factor $f_v$ and
-* an empirical soil moisture stress penalty on LUE.
 
 $$
-  \text{LUE} = \phi_0(t) \cdot M_C \cdot m_j \cdot f_v \cdot \beta(\theta)$
+  \text{LUE} = \phi_0(t) \cdot M_C \cdot m_j \cdot f_v$
 $$
 
 ### $\phi_0$ and temperature dependency
@@ -96,14 +93,8 @@ applied by default but can be turned off using the
 {class}`~pyrealm.pmodel.pmodel.PModel` argument `do_ftemp_kphio=False`.
 
 The default values of `kphio` vary with the model options, corresponding
-to the empirically fitted values presented for three setups in {cite:t}`Stocker:2020dh`.
-
-1. If the temperature dependence of $\phi_0$ is **not** applied,
-    $\phi_0 = 0.049977$,
-1. otherwise, if an [empirical soil moisture stress factor](soil_moisture)
-   is being applied, $\phi_0 = 0.87182$
-1. otherwise, with no soil moisture stress and temperature dependence
-   $\phi_0 = 0.081785$
+to the empirically fitted values from {cite:t}`Stocker:2020dh`. If the temperature
+dependence of $\phi_0$ is applied, $\phi_0 = 0.081785$, otherwise  $\phi_0 = 0.049977$.
 
 The initial value of $\phi_0$ and the values used in calculations are stored in
 the `init_kphio` and  `kphio` attributes of the {class}`~pyrealm.pmodel.pmodel.PModel`
@@ -195,8 +186,3 @@ pyplot.ylabel("Light Use Efficiency (g C mol-1)")
 pyplot.legend()
 pyplot.show()
 ```
-
-### Soil moisture stress
-
-This approach to handling soil moisture effects is presented
-[here](soil_moisture.md).