AFE.pk: Calculate average fold error

Description

Calculate average fold error

Usage

# S3 method for pk
AFE(
  obj,
  newdata = NULL,
  model = NULL,
  method = NULL,
  exclude = TRUE,
  use_scale_conc = FALSE,
  AFE_group = NULL,
  sub_pLOQ = TRUE,
  ...
)

Value

A dataframe with one row for each `data_group`, `model` and `method`. The final column contains the AFE of the model fitted by the corresponding method, using the data in `newdata`.

Arguments

obj: A `pk` object
newdata: Optional: A `data.frame` with new data for which to make predictions and compute AFE. If NULL (the default), then AFE will be computed for the data in `obj$data`. `newdata` is required to contain at least the following variables: `Time`, `Time.Units`, `Dose`, `Route`, `Media`, `Conc`, `Conc_SD`, `N_Subjects`, `Detect`, `pLOQ`.
model: Optional: Specify one or more of the fitted models for which to make predictions and calculate AFE. If NULL (the default), AFE will be returned for all of the models in `obj$stat_model`.
method: Optional: Specify one or more of the [optimx::optimx()] methods for which to make predictions and calculate AFE. If NULL (the default), RMSEs will be returned for all of the models in `obj$optimx_settings$method`.
exclude: Logical: `TRUE` to compute the AFE excluding any observations in the data marked for exclusion (if there is a variable `exclude` in the data, an observation is marked for exclusion when `exclude `FALSE` to include all observations, regardless of exclusion status. Default `TRUE`.
use_scale_conc: Possible values: `TRUE`, `FALSE`, or a named list with elements `dose_norm` and `log10_trans` which themselves should be either `TRUE` or `FALSE`. If `use_scale_conc = TRUE`, then the concentration scaling/transformations in `object` will be applied to both predicted and observed concentrations before the log-likelihood is computed. If `use_scale_conc = FALSE` (the default for this function), then no concentration scaling or transformation will be applied before the log-likelihood is computed. If `use_scale_conc = list(dose_norm = ..., log10_trans = ...)`, then the specified dose normalization and/or log10-transformation will be applied.
AFE_group: Default: Chemical, Species. Determines what the data grouping that is used to calculate average fold error (AFE). Should be set to lowest number of variables that still would return unique experimental conditions. Input in the form of `ggplot2::vars(Chemical, Species, Route, Media, Dose)`.
sub_pLOQ: TRUE (default): Substitute all predictions below the LOQ with the LOQ before computing AFE. FALSE: do not.
...: Additional arguments. Not currently in use.

Author

Caroline Ring

Details

Average fold error is calculated as

$$ 10^{\frac{1}{N}\sum{log_{10} \left( \frac{\textrm{predicted}}{\textrm{observed}} \right)}} $$

# Left-censored data

If the observed value is censored, and the predicted value is less than the reported LOQ, then the observed value is (temporarily) set equal to the predicted value, for an effective error of zero.