epx: Effect profiles (EPx values)

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

Effect profiles (EPx values)

Description

Derives one or more EPx/LPx values for the supplied effect scenarios, i.e. it calculates the multiplication factors of an exposure profile that cause x% of effect. Scenarios are processed in parallel, if possible.

Usage

epx(
  scenarios,
  level = c(10, 50),
  effect_tolerance = 0.001,
  factor_cutoff = NA,
  min_factor = 1e-30,
  max_factor = 1e+30,
  verbose = FALSE,
  ep_only = FALSE,
  long_format = FALSE,
  ...
)

Arguments

scenarios	table or vector of EffectScenario objects
level	effect levels in percent (%), defaults to c(10,50)
effect_tolerance	numeric, minimum absolute accuracy of effect levels
factor_cutoff	optional numeric, the search for a multiplication factor will be cut short if tried factors exceed this value; the result will report the cutoff value as the final EPx value.
min_factor	numeric, if tried factors fall below this threshold, the algorithm will halt with an error
max_factor	numeric, if tried factors exceed this threshold, the algorithm will halt with an error
verbose	logic, if TRUE then infos about model evaluations are displayed
ep_only	logical, if TRUE then only EPx values are part of the output, any contextual information such as EffectScenario objects are left out
long_format	logical, if TRUE then EPx values are returned as a table in long format, any contextual information will be duplicated
...	additional arguments passed on to effect()

Details

To estimate EPx values, a binary search on multiplication factors is conducted. The algorithm can achieve arbitrary precision in terms of effects. The same approach is implemented in the morse package in the MFx() function. Convergence is often achieved in less than 10 iterations per effect level and endpoint.

Internally, a knowledge base of all tried factors and resulting effect levels is kept to speed up convergence if more than one endpoint or effect level was requested. The algorithm will automatically sweep the range of multiplication factors as needed but hard cutoff values are implemented to avoid infinite loops; the algorithm will halt with an error message if tried factors are smaller than 1e-30 or greater than 1e30.

Numerical precision

The precision of reported EPx values is controlled by the argument effect_tolerance and is given as the upper absolute error threshold of effects that is deemed acceptable. The default value of 0.001 ensures that a derived EPx will result in an effect of x% ± 0.1. Decreasing the effect_tolerance will result in additional model iterations and longer runtime. Setting an extremely small tolerance value may lead to a breakdown of the algorithm due to the occurrence of extremely small, quasi-random numerical errors in simulation results.

Value

The original tibble with additional columns named after the request effect levels, e.g. L.EP10. If no tibble was used as argument, then a new one is created. The first column scenario will contain the supplied EffectScenario objects.

Examples

minnow_sd %>% epx()
minnow_sd %>% epx(level=c(10,23,42))

# displays infos about tested multiplication factors
minnow_sd %>% epx(verbose=TRUE)

# return results as a table in wide format
minnow_sd %>% epx(long_format=TRUE)

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