calibrate  R Documentation 
The function calibrate()
performs the calibration (fitting) of model
parameters to observed data. The data can originate from one or more experiments or
trials. Experimental conditions, such as model parameters and exposure
level, can differ between trials; fitting can be performed on all datasets
at the same time.
calibrate(x, ...)
## S4 method for signature 'EffectScenario'
calibrate(
x,
par,
data,
endpoint = deprecated(),
output,
by,
metric_fun = deprecated(),
err_fun,
as_tibble = deprecated(),
catch_errors = deprecated(),
verbose = TRUE,
...
)
## S4 method for signature 'CalibrationSet'
calibrate(x, par, output, err_fun, verbose = TRUE, ...)
## S4 method for signature 'list'
calibrate(
x,
par,
endpoint = deprecated(),
output,
metric_fun = deprecated(),
metric_total = deprecated(),
err_fun,
as_tibble = deprecated(),
catch_errors = deprecated(),
verbose = TRUE,
...
)
x 
either a single scenario or a list of caliset objects to be fitted 
... 
additional parameters passed on to 
par 
named numeric vector with parameters to fit and their start values 
data 

endpoint 
deprecated 
output 

by 
optional 
metric_fun 
deprecated, please use 
err_fun 
vectorized error function to calculate an error term that is minimized during optimization, must accept exactly four vectorized arguments, defaults to sum of squared errors 
as_tibble 
deprecated, result can no longer be returned as a tibble 
catch_errors 
deprecated, simulation errors are always caught 
verbose 

metric_total 
deprecated 
Fitting of model parameters can be performed in two ways:
A single scenario is fitted to a single dataset. The dataset must represent a timeseries of an output variable of the model, e.g. observed biomass over time (effect data). The dataset can represent results of one or more experimental replicates under identical conditions.
One or more datasets of observed data are fitted each to a scenario which describes the experimental conditions during observation, such as exposure level and environmental properties. Each combination of dataset and scenario is represented by a calibration set. During fitting, all calibration sets are evaluated and a total error term is calculated over all observed and predicted values.
Experimental, or effect, data must be supplied as a data.frame
in long format
with at least two columns: the first column contains numeric
timestamps and
the remaining columns must contain the observed quantity. The dataset must
contain a column that which matches with the contents of parameter output
.
As an example, the simulation result of Lemna_Schmitt model contains the
output column biomass (BM
), amongst others. To fit model parameters of said
Lemna_Schmitt scenario based on observed biomass, the observed data must
contain a column named BM
which represents the observed biomass.
A minimal observed dataset could look like this:
observed < data.frame(time=c(0, 7, 14, 21), BM=c( 12, 23, 37, 56))
By default, the total sum of squared errors is used as the target
function which is minimized during fitting. A custom error function can be
supplied by the user: The function must accept four vectorized
arguments and return a numeric of length one, i.e. the total error value
which gets minimized by calibrate()
.
Example of a custom error function which returns the sum of absolute errors:
my_absolute_error < function(observed, predicted, weights, tags) { sum(abs(observed  predicted)) }
The arguments to the error function will contain all observed and predicted
values, as well as any weights and tags that were defined by the calibration sets.
As tags are optional, the fourth argument may be a list containing NULL
values.
The fourth argument can be used to pass additional information to the error
function: For example, the tag may identify the study from where the data
originates from and the error function could group and evaluate the data
accordingly.
A list of fitted parameters (as produced by stats::optim()
)
is returned.
calibrate(EffectScenario)
: Fit single scenario using a dataset
calibrate(CalibrationSet)
: Fit using a CalibrationSet
calibrate(list)
: Fit using a list of caliset objects
library(dplyr)
# Get observed biomass during control experiment by Schmitt et al. (2013)
observed < Schmitt2013 %>%
filter(ID == "T0") %>%
select(t, BM=obs)
# Create a scenario that represents conditions during experiment
scenario < metsulfuron %>%
set_param(c(k_phot_fix=TRUE, k_resp=0, Emax=1)) %>%
set_init(c(BM=12)) %>%
set_noexposure()
# Fit parameter 'k_phot_max' to observed biomass growth from experiment
calibrate(
scenario,
par=c(k_phot_max=1),
data=observed,
output="BM",
method="Brent", # Brent is recommended for onedimensional optimization
lower=0, # lower parameter boundary
upper=0.5 # upper parameter boundary
) > fit
fit$par
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.