PnET-R

The R version of the Photosynthetic and EvapoTranspiration model family.

PnET is a simple lumped-parameter forest ecosystem model family designed to simulate the effects of climate change, disturbance, and biogeochemical perturbations on coupled C, H20, and N cycling. The PnET family consists of several models including PnET-II, PnET-Day, PnET-CN, PnET-Daily, and PnET-SOM. Currently, in this package, we provide PnET-II, PnET-Day, and PnET-CN.

Tip

This package is published in Methods in Ecology & Evolution!

Please cite:

Gao, X., Zhou, Z., Ollinger, S. V., Matthes, J. H., Jiao, W., & Thompson, J. R. (2025). pnetr: An R package for the PnET family of forest ecosystem models. Methods in Ecology and Evolution, 00, 1–11. https://doi.org/10.1111/2041-210X.70076

Installation

The package can be installed by running the following command in R terminal:

# install.packages("remotes")
remotes::install_github("hf-thompson-lab/pnetr")

We encourage users folk/download this repository and modify any part of the scripts for their needs. We often read science papers claiming:"earth system models do not capture or underestimate xxx processes/effects" but most earth system models are hard to modify because they are coded in low-level programming languages for computational reasons and they are too complex to handle for most scientists who only wants to test their scientific hypotheses/findings. In this case, users can modify the corresponding processes in this pacakge and test their hypothses directly. Also for this reason, we provided detailed documentation for the encoded processes in this pacakge for user's references.

A typical useage of this package would be, say, we find some new ecological process through empirical analysis and draw some inferences based on that, but we are not sure whether the process is causal or how much it can improve ecosystem models in representing the carbon/water cycles. In this case, we can directly add our new process into this model and test how it interacts with other variables and check whether it makes sense or not.

Note

We expect some errors/bugs in the first several versions, so please feel free to create an issue through Github if you suspect something is not working well. Thank you for helping us improve the package!

Documentation

The descriptions of the models can be found here. Additionally, the follwing resources are also useful:

• PnET official website (Note that although this is a University of New Hemisphere hosted website, somehow you may encounter a "not secure warning" from Chrome or other browsers. Please ignore it and click "Advanced"-->"Proceed")
• ORNL DAAC lists key references and includes some descriptions.
• Another effort of PnET-CN in R
• LANDIS-II PnET-Succession

Repository structure

The R folder contains the source code. In this folder, file names with dat_* indicate the script is related to data processing; hlp_* files are helper functions; obj_* files are objects as the package adopted some part of object-oriented programming; mod_* files are specific model implementations.

The doc folder contains documentation of the processes in the PnET models. These files contain detailed mathematic equations of the algorithm implementation.

The man folder is the API documentation generated by the devtools package. Users do not need to modify the content in this folder. After documenting the user-created functions with the roxygen2 format, the content in this folder can be automatically generated by running devtools::document().

The tests folder contains scripts that are used for unit tests by the testthat package. This folder also contains some example datasets and scripts that can help user get familiar with running the models.

Developer Notes

Developer notes can be found here, which provide more detailed information about how to code the repository.

There are two ways to modify routines in the package without breaking the original code for hypothesis testing:

1. To replace the exported functions (e.g., PnET-Day(), PnET-II(), and PnET-CN()), users can copy and paste the original function to modify it, then use source([the_modified_function_file]) to overwrite the function.
2. To replace the internal functions (e.g., Phenology(), Waterbal(), and CNTrans()), users can write another function with the same name as the internal function to be replaced, then use assignInNamespace("[the internal function]", [the modified function with the same name], ns = "pnetr"). For instance, we can write another function named Phenology() in our global namespace, then run assignInNamespace("Phenology", Phenology, ns = "pnetr"). After this operation, when pnetr calls the Phenology() function, it will use the customized Phenology() function instead of the original one in the package.

References

• Aber, J. D., Driscoll, C., Federer, C. A., Lathrop, R., Lovett, G., Melillo, J. M., Steudler, P., & Vogelmann, J. (1993). A strategy for the regional analysis of the effects of physical and chemical climate change on biogeochemical cycles in northeastern (U.S.) forests. Ecological Modelling, 67(1), 37–47. https://doi.org/10.1016/0304-3800(93)90098-D
• Aber, J. D., & Federer, C. A. (1992). A generalized, lumped-parameter model of photosynthesis, evapotranspiration and net primary production in temperate and boreal forest ecosystems. Oecologia, 92(4), 463–474. https://doi.org/10.1007/BF00317837
• Aber, J. D., Ollinger, S. V., & Driscoll, C. T. (1997). Modeling nitrogen saturation in forest ecosystems in response to land use and atmospheric deposition. Ecological Modelling, 101(1), 61–78. https://doi.org/10.1016/S0304-3800(97)01953-4
• Aber, J. D., Reich, P. B., & Goulden, M. L. (1996). Extrapolating Leaf CO₂ Exchange to the Canopy: A Generalized Model of Forest Photosynthesis Compared with Measurements by Eddy Correlation. Oecologia, 106(2), 257–265.
• Aber, J., Ollinger, S., Federer, C., Reich, P., Goulden, M., Kicklighter, D., Melillo, J., & Lathrop, R. (1995). Predicting the effects of climate change on water yield and forest production in the northeastern United States. Climate Research, 5, 207–222. https://doi.org/10.3354/cr005207
• De Bruijn, A., Gustafson, E. J., Sturtevant, B. R., Foster, J. R., Miranda, B. R., Lichti, N. I., & Jacobs, D. F. (2014). Toward more robust projections of forest landscape dynamics under novel environmental conditions: Embedding PnET within LANDIS-II. Ecological Modelling, 287, 44–57. https://doi.org/10.1016/j.ecolmodel.2014.05.004
• Ollinger, S. V., Aber, J. D., & Reich, P. B. (1997). SIMULATING OZONE EFFECTS ON FOREST PRODUCTIVITY: INTERACTIONS AMONG LEAF-, CANOPY-, AND STAND-LEVEL PROCESSES. Ecological Applications, 7(4), 1237–1251. https://doi.org/10.1890/1051-0761(1997)007[1237:SOEOFP]2.0.CO;2
• Ollinger, S. V., Aber, J. D., Reich, P. B., & Freuder, R. J. (2002). Interactive effects of nitrogen deposition, tropospheric ozone, elevated CO2 and land use history on the carbon dynamics of northern hardwood forests. Global Change Biology, 8(6), 545–562. https://doi.org/10.1046/j.1365-2486.2002.00482.x
• Zhou, Z., Ollinger, S. V., & Lepine, L. (2018). Landscape variation in canopy nitrogen and carbon assimilation in a temperate mixed forest. Oecologia, 188(2), 595–606. https://doi.org/10.1007/s00442-018-4223-2