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

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,
  ...
)

Arguments

x	either a single scenario or a list of caliset objects to be fitted
...	additional parameters passed on to stats::optim() and simulate()
par	named numeric vector with parameters to fit and their start values
data	data.frame with two or more columns with experimental data, 1st column must contain time points, the following columns may values which the scenario is fitted to.
endpoint	deprecated character, please use output instead
output	character, name of a single output column of simulate() to optimize on
by	optional character, groups and splits the experimental data into multiple distinct trials and datasets before fitting
metric_fun	deprecated, please use err_fun instead
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	logical, if TRUE then debug outputs are displayed during optimization
metric_total	deprecated

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 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))

Error function

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.

Value

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

Methods (by class)

• calibrate(EffectScenario): Fit single scenario using a dataset

• calibrate(CalibrationSet): Fit using a CalibrationSet

• calibrate(list): Fit using a list of caliset objects

Examples

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 one-dimensional optimization
  lower=0,        # lower parameter boundary
  upper=0.5       # upper parameter boundary
) -> fit
fit$par

cvasi documentation built on Sept. 23, 2024, 9:08 a.m.