-
Notifications
You must be signed in to change notification settings - Fork 36
Expand file tree
/
Copy pathCITATION.cff
More file actions
245 lines (201 loc) · 13.7 KB
/
Copy pathCITATION.cff
File metadata and controls
245 lines (201 loc) · 13.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
cff-version: 1.2.0
message: >-
If you use this software, please cite it using the
metadata from this file.
The corresponding documentation paper can be found as https://doi.org/10.5194/gmd-18-9855-2025
title: 'rsofun: The P-Model and BiomeE Modelling Framework'
type: software
license: GPL-3.0-only
repository: 'http://dx.doi.org/10.32614/CRAN.package.rsofun'
repository-code: 'https://github.com/fabern/zenodo_sandbox'
repository-artifact: 'https://doi.org/10.5281/zenodo.3712928'
url: 'https://doi.org/10.5281/zenodo.3712928'
contact:
- affiliation: University Bern
family-names: Stocker
given-names: Benjamin David
orcid: https://orcid.org/0000-0003-2697-9096
email: benjamin.stocker@gmail.com
authors:
- affiliation: University Bern
family-names: Stocker
given-names: Benjamin David
orcid: https://orcid.org/0000-0003-2697-9096
- affiliation: '@bluegreen-labs'
family-names: Hufkens
given-names: Koen
orcid: https://orcid.org/0000-0002-5070-8109
- affiliation: University Bern
family-names: "Ar\xE1n Paredes"
given-names: Josefa
orcid: https://orcid.org/0009-0006-7176-2311
- affiliation: University Bern
family-names: Bernhard
given-names: Fabian
orcid: https://orcid.org/0000-0003-0338-0961
- affiliation: University Bern
family-names: Marcadella
given-names: Mayeul
orcid: https://orcid.org/0000-0001-8555-3808
keywords:
- dgvm
- growth
- modeling
- p-model
- simulation
- vegetation-dynamics
abstract: '<h1>rsofun</h1>
<p>An R package for Simulating Optimal FUNctioning (rsofun). A model for site-scale
simulations of ecosystem processes. The package contains the following modules:</p>
<p>- P-model for leaf-level acclimation of photosynthesis from <a href="https://gmd.copernicus.org/preprints/gmd-2019-200/">Stocker
et al. (2019)</a>.<br>- SPLASH for bioclimatic variables, including the surface
radiation budget and the soil water balance from <a href="https://doi.org/10.5194/gmd-10-689-2017">Davis
et al. (2017)</a>.<br>- BiomeE for comprehensive simulations of ecosystem carbon
and water cycling, tree growth, and tree cohort-explicit forest dynamics following
the Perfect Plasticity Approximation, from <a href="https://doi.org/10.5194/bg-12-2655-2015">Weng
et al., (2015)</a>.</p>
<h2>Installation</h2>
<h3>Stable release</h3>
<p>To install the current stable release use a CRAN repository:</p>
<p><code>install.packages("rsofun")</code><br><code>library("rsofun")</code></p>
<h3>Development release</h3>
<p>To install the latest development release of the package run the following commands
to install rsofun directly from GitHub:</p>
<p><code>if(!require(remotes)){install.packages("remotes")}</code><br><code>remotes::install_github("geco-bern/rsofun")</code><br><code>library("rsofun")</code><br><br></p>
<p>**NOTE:** Installing from GitHub requires compilation of Fortran and C source
code contained in {rsofun}. To enable compiling source code, install <a href="https://cran.r-project.org/bin/windows/Rtools/">Rtools</a>
on Windows, or <a href="https://developer.apple.com/xcode/">Xcode</a> and the <a
href="https://github.com/fxcoudert/gfortran-for-macOS">GNU Fortran compiler on Mac</a>
(see also ''Mandatory tools'' <a href="https://mac.r-project.org/tools/">here</a>).
On Linux, the gfortran compiler is usually installed already.</p>
<p>Vignettes are not rendered by default, if you want to include additional documentation
please use:</p>
<p><code>if(!require(remotes)){install.packages("remotes")}</code><br><code>remotes::install_github("geco-bern/rsofun",
build_vignettes = TRUE)</code><br><code>library("rsofun")</code></p>
<h3>From source </h3>
<p>Assuming <code>rsofun</code> is the location of the source directory, on can
build the R package (with extension .tar.gz) from the command line using in a bash
shell:<br><br><code>R CMD build --no-manual --no-build-vignettes rsofun</code><br><br>The
package can then be installed with:</p>
<p><code>R CMD INSTALL -c --preclean *.tar.gz</code></p>
<p>, where the star <code>*</code> can be replaced by the name of the package produced
at the previous step.</p>
<h2>Use</h2>
<p>Below sections show the ease of use of the package in terms of model parameter
specification and running both a single run or optimizing the parameters for a given
site (or multiple sites). For an in depth discussion we refer to the <a href="https://geco-bern.github.io/rsofun/articles/">vignettes</a>.</p>
<h3>Running model</h3>
<p>With all data prepared we can run the P-model using <code>runread_pmodel_f()</code>.
This function takes the nested data structure and runs the model site by site, returning
nested model output results matching the input drivers. In R:</p>
<p><br><code># define model parameter values from previous</code><br><code># work</code><br><code>params_modl
<- list(</code><br><code> kphio
= 0.04998, # setup ORG in Stocker et al. 2020 GMD</code><br><code>
kphio_par_a = 0.0, #
set to zero to disable temperature-dependence of kphio</code><br><code>
kphio_par_b = 1.0,</code><br><code> soilm_thetastar
= 0.6 * 240, # to recover old setup with soil moisture stress</code><br><code>
soilm_betao = 0.0,</code><br><code>
beta_unitcostratio = 146.0,</code><br><code> rd_to_vcmax
= 0.014, # value from Atkin et al. 2015 for C3
herbaceous</code><br><code> tau_acclim
= 30.0,</code><br><code> kc_jmax
= 0.41</code><br><code> )</code></p>
<p><code># run the model for these parameters</code><br><code>output <- rsofun::runread_pmodel_f(</code><br><code>
pmodel_drivers,</code><br><code> par = params_modl</code><br><code>
)</code><br><br></p>
<h3>Parameter optimization</h3>
<p>To optimize new parameters based upon driver data and a validation dataset we
must first specify an optimization strategy and settings, as well as a cost function
and parameter ranges. In R:</p>
<p><br><code>settings <- list(</code><br><code> method
= "GenSA",</code><br><code> metric
= cost_rmse_pmodel,</code><br><code> control
= list(</code><br><code> maxit = 100),</code><br><code> par =
list(</code><br><code> kphio = list(lower=0.02, upper=0.2, init = 0.05)</code><br><code>
)</code><br><code>)</code><br><br></p>
<p>`rsofun` supports both optimization using the `GenSA` and `BayesianTools` packages.
The above statement provides settings for a `GenSA` optimization approach. For this
example the maximum number of iterations is kept artificially low. In a real scenario
you will have to increase this value orders of magnitude. Keep in mind that optimization
routines rely on a cost function, which, depending on its structure influences parameter
selection. A limited set of cost functions is provided but the model structure is
transparent and custom cost functions can be easily written. More details can be
found in the "Parameter calibration and cost functions" vignette.</p>
<p>In addition starting values and ranges are provided for the free parameters in
the model. Free parameters include: parameters for the quantum yield efficiency
`kphio`, `kphio_par_a` and `kphio_par_b`, soil moisture stress parameters `soilm_thetastar`
and `soilm_betao`, and also `beta_unitcostratio`, `rd_to_vcmax`, `tau_acclim` and
`kc_jmax` (see `?runread_pmodel_f`). Be mindful that with newer versions of `rsofun`
additional parameters might be introduced, so re-check vignettes and function documentation
when updating existing code.</p>
<p>With all settings defined the optimization function `calib_sofun()` can be called
with driver data and observations specified. Extra arguments for the cost function
(like what variable should be used as target to compute the root mean squared error
(RMSE) and previous values for the parameters that aren''t calibrated, which are
needed to run the P-model).</p>
<p><br><code># calibrate the model and optimize free parameters</code><br><code>pars
<- calib_sofun(</code><br><code> drivers = pmodel_drivers, </code><br><code>
obs = pmodel_validation,</code><br><code> settings = settings,</code><br><code>
# extra arguments passed to the cost function:</code><br><code>
targets = "gpp", # define target variable
GPP</code><br><code> par_fixed = params_modl[-1] # fix non-calibrated
parameters to previous </code><br><code>
#
values, removing kphio</code><br><code> )</code><br><br></p>
<h2>Data and code for model documentation paper (Paredes et al., 2025)</h2>
<p>The model documentation paper is available at <a href="https://doi.org/10.5194/gmd-18-9855-2025">https://doi.org/10.5194/gmd-18-9855-2025</a>
and can be cited as:
Paredes, J. A., Bernhard, F., Hufkens, K., Marcadella, M., and Stocker, B. D.:
rsofun v5.1: a model-data integration framework for simulating ecosystem processes,
Geosci. Model Dev., 18, 9855–9878, <a href="https://doi.org/10.5194/gmd-18-9855-2025">https://doi.org/10.5194/gmd-18-9855-2025</a>, 2025.</p>
<p>Code to reproduce the analysis and plots presented in the documentation paper is
contained in the repository at https://github.com/geco-bern/rsofun_doc and
archived on Zenodo (https://doi.org/10.5281/zenodo.17204361, Bernhard and
Stocker, 2025).</p>
<h2>Data for rsofun example data sets</h2>
<p dir="auto">Versioned releases of the rsofun package are deposited on Zenodo
(see badge at the top of the README file).</p>
<p dir="auto">Model forcing and evaluation data stems form the following sources:</p>
<ul dir="auto">
<li>The model forcing and evaluation data for GPP sites are based on the publicly
available data, prepared by FluxDataKit v3.4.2
(<a href="https://doi.org/10.5281/zenodo.14808331" rel="nofollow">https://doi.org/10.5281/zenodo.14808331</a>, Hufkens and Stocker, 2025).</li>
<li>The model forcing for Δ sites are based on the publicly available WorldClim
(<a href="https://doi.org/10.1002/joc.5086" rel="nofollow">https://doi.org/10.1002/joc.5086</a>, Fick and Hijmans, 2017),
ETOPO1 (<a href="https://doi.org/10.7289/V5C8276M" rel="nofollow">https://doi.org/10.7289/V5C8276M</a>, NOAA National Geophysical Data Center,
2009), and Mauna Loa CO2 (<a href="https://doi.org/10.6075/J08W3BHW" rel="nofollow">https://doi.org/10.6075/J08W3BHW</a>, Keeling et al., 2017)
data.</li>
<li>The model evaluation data for Δ sites are based on data associated with Cornwell
et al. (2018) available at (<a href="https://doi.org/10.5281/zenodo.15239220" rel="nofollow">https://doi.org/10.5281/zenodo.15239220</a>, Cornwell, 2025).</li>
</ul>
<p dir="auto">Scripts for generating these data are contained in the <code>rsofun_doc</code> repository
(<a href="https://doi.org/10.5281/zenodo.17204361" rel="nofollow">https://doi.org/10.5281/zenodo.17204361</a>, Bernhard and Stocker, 2025) in the subdirectory <code>data-raw/</code>.</p>
<h2>References</h2>
<p>Paredes, J. A., Bernhard, F., Hufkens, K., Marcadella, M., and Stocker,
B. D.: rsofun v5.1: a model-data integration framework for simulating ecosystem
processes, Geosci. Model Dev., 18, 9855–9878, https://doi.org/10.5194/gmd-18-9855-2025, 2025.</p>
<p>Stocker, B. D., Wang, H., Smith, N. G., Harrison, S. P., Keenan, T. F., Sandoval,
D., Davis, T., and Prentice, I. C.: P-model v1.0: an optimality-based light use
efficiency model for simulating ecosystem gross primary production, Geosci. Model
Dev., 13, 1545–1581, https://doi.org/10.5194/gmd-13-1545-2020, 2020.</p>
<p>Cornwell, W. K., Wright, I. J., Turner, J., Maire, V., Barbour, M. M., Cernusak,
L. A., Dawson, T., Ellsworth, D., Farquhar, G. D., Griffiths, H., Keitel, C., Knohl,
A., Reich, P. B., Williams, D. G., Bhaskar, R., Cornelissen, J. H. C., Richards,
A., Schmidt, S., Valladares, F., … Santiago, L. S.: Climate and soils together
regulate photosynthetic carbon isotope discrimination within C3 plants worldwide.
Global Ecology and Biogeography, 27(9), 1056–1067. https://doi.org/10.1111/geb.12764, 2018.</p>
<p>Davis, T. W., Prentice, I. C., Stocker, B. D., Thomas, R. T., Whitley, R. J.,
Wang, H., Evans, B. J., Gallego-Sala, A. V., Sykes, M. T., and Cramer, W.: Simple
process-led algorithms for simulating habitats (SPLASH v.1.0): robust indices of
radiation, evapotranspiration and plant-available moisture, Geoscientific Model
Development, 10, 689–708, doi:10.5194/gmd-10-689-2017, URL http: //www.geosci-model-dev.net/10/689/2017/,
2017.</p>
<p>Weng, E. S., Malyshev, S., Lichstein, J. W., Farrior, C. E., Dybzinski, R., Zhang,
T., Shevliakova, E., and Pacala, S. W.: Scaling from individual trees to forests
in an Earth system modeling framework using a mathematically tractable model of
height-structured competition, Biogeosciences, 12, 2655–2694, https://doi.org/10.5194/bg-12-2655-2015,
2015.</p>
<h2>Acknowledgements</h2>
<p>The {rsofun} is part of the LEMONTREE project and funded by Schmidt Futures and
under the umbrella of the Virtual Earth System Research Institute (VESRI). </p>'