effect: Effect level
In cvasi: Calibration, Validation, and Simulation of TKTD Models

effect

R Documentation

Effect level

Description

Derives the effect level due to toxicant exposure in the supplied scenarios. Either relative to a control scenario or derived directly from model endpoints, depending on model type. For scenarios with moving exposure windows, the maximum effect is returned.

Usage

effect(x, ...)

## S4 method for signature 'EffectScenario'
effect(x, factor = 1, max_only = TRUE, ep_only = FALSE, marginal_effect, ...)

## S4 method for signature 'ScenarioSequence'
effect(x, ...)

Arguments

`x`	a scenario objects
`...`	additional parameters passed on to `simulate()`
`factor`	optional numeric value which scales the exposure time-series
`max_only`	`logical`, if `TRUE` only the maximum effect is returned, else results for all effect windows are reported
`ep_only`	logical, if TRUE only effect endpoints are returned as a vector
`marginal_effect`	`numeric`, if set, any effect smaller than this threshold will be reported as zero to exclude pseudo-effects originating from small numerical errors

Details

By default, only the maximum effect in all moving exposure windows will be returned. If argument max_only=FALSE is set, the returned table will be converted to long-format and will contain effect levels for each assessed exposure window.

Calculation

Effects are calculated similarly to relative errors, i.e. the difference between control and treatment scenarios is divided by the absolute value of the control. Effects are usually in the interval ⁠[0,1]⁠, but values larger than one or smaller than zero can occur. As a special case, if the endpoint from the control scenario is zero, then the effect is either

zero, if also the treatment is zero
positive infinity, if the treatment is smaller than zero
negative infinity, if the treatment is greater than zero

As an example, a control scenario achieves a biomass of 1.0 and the treatment scenario achieves a biomass of 0.9, the effect will be equal to 0.1 or 10%. However, effects can take on any real value. If, for example, the biomass of the previously mentioned treatment scenario drops below zero, then an effect larger than 1.0 will be calculated If, instead, the biomass in the treatment scenario is greater than in the control, then the effect will be negative.

Output formatting

Start and end time of exposure windows can be disabled by setting ep_only=TRUE. Effect levels smaller than a certain threshold can be automatically set to zero (0.0) to avoid spurious effect levels introduced by numerical errors. Set marginal_effect to an adequate value less than 1%.

Computational efficiency

Calculations can be sped up by providing a data.frame of pre-calculated control scenarios for each assessed time window. As control scenarios are by definition independent of any exposure multiplication factor, they can be reused for repeated calculations, e.g. to derive effect profiles or dose-response relationships.

Value

a tibble, by default containing scenarios, effect levels, and the exposure window where the maximum effect level occurred. The number of columns depends on the enabled effect endpoints and function arguments.

By default, the first column, named scenarios, contains the original scenario objects that were the basis of the calculation. For each effect endpoint, it will be followed by one column with the maximum effect level and two columns containing start and end time of the associated exposure window. If exposure windows are disabled, the columns will just contain the start and end time of the simulation. The effect level column will have the name of the effect endpoint, start and end time will additionally have the suffixes .dat.start and .dat.end, respectively.