calibrate: Fit model parameters to experimental data

In cvasi: Calibration, Validation, and Simulation of TKTD Models

Fit model parameters to experimental data

Description

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.

Usage

## S4 method for signature 'EffectScenario'
calibrate(x, output, data, ...)

## S4 method for signature 'list'
calibrate(
  x,
  par,
  output,
  err_fun = "sse",
  log_scale = FALSE,
  verbose = TRUE,
  ode_method = NULL,
  ...
)

Arguments

x	either a single scenario. sequence, or a list of caliset objects to be fitted. If only a scenario or sequence is supplied, the additional argument data is required.
output	character, name of a single output column of simulate() to optimize on
data	a data.frame or return value of tox_data(); the scenarios's output is fitted to the (observed) data. See tox_data() for valid tabular data formats.
...	additional parameters passed on to stats::optim() and simulate()
par	named numeric vector with parameters to fit and their start values
err_fun	a character choosing one of the pre-defined error functions, or alternatively a function implementing a custom error function. Defaults to Sum of squared errors ("sse").
log_scale	logical, if TRUE then observed and predicted values are log-transformed before the error function is evaluated. Defaults to FALSE.
verbose	logical, if TRUE then debug outputs are displayed during optimization
ode_method	optional character to select an ODE solver for simulate()

Details

Fitting of model parameters can be performed in two ways:

1. A single scenario is fitted to a single dataset. The dataset must represent a time-series 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.

2. 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.

Observed data

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 observed quantitiy must match in unit and meaning with the model output defined by argument 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 represent biomass as well. A minimal observed dataset could look like this:

observed <- data.frame(time=c(0,  7, 14, 21),
                       BM=c( 12, 23, 37, 56))

Error function

The error function quantifies the deviations between simulated and observed data. The decision for an error function can have influence on the result of the fitting procedure. Two error functions are pre-defined by the package and can be selected by the user, but custom error functions can be used as well.

Available pre-defined error functions:

• "sse": Sum of squared errors

By default, the sum of squared errors is used as the error function which gets minimized during fitting. A custom error function must accept four vectorized arguments and return a numeric of length one, i.e. the total error value. The arguments to the error function will all have the same length and are defined as follows:

• First argument: all observed data points

• Second argument: all simulated data points

• Third argument: optional weights for each data point

• Fourth argument: a list of optional caliset tags

You can choose to ignore certain arguments, such as weights and tags, in your custom error function. An example of a custom error function which returns the sum of absolute errors looks as follow:

my_absolute_error <- function(observed, predicted, weights, tags) {
  sum(abs(observed - predicted))
}

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.

Value

A list of fitted parameters (as produced by stats::optim()) is returned.

Methods (by class)

• calibrate(EffectScenario): Fit single scenario to a (tox_data) dataset

Examples

# Create an artificial data set of observed frond numbers.
# It assumes exponential growth with an effective growth rate of 0.38
trial <- data.frame(time=0:14,
                   fronds=12 * exp(0:14 * 0.38))
plot(trial)

# Create a Lemna scenario that represents unrestricted, exponential growth.
scenario <- Lemna_Schmitt() %>%
  set_param(c(k_phot_max=1, k_resp=0, EC50=1, b=1, P_up=1)) %>%
  set_init(c(BM=12)) %>%
  set_noexposure()

# Fit scenario parameter 'k_phot_max' to observed frond numbers:
fit <- calibrate(
  scenario,
  par="k_phot_max",
  data=trial,
  output="BM"
)

# The fitted value of 'k_phot_max' matches the effective growth rate which
# was used to create the artificial data set:
fit$par

cvasi documentation built on Sept. 11, 2025, 5:11 p.m.