set_exposure: Set exposure time-series

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

Set exposure time-series

Description

Exposure refers to the toxicant concentration an organism is exposed to. In case of aquatic organisms, this would commonly be the concentration of a toxicant in water. Other interpretations are possible depending on model assumptions.

Usage

set_exposure(scenarios, series, ...)

## S4 method for signature 'ANY,ANY'
set_exposure(scenarios, series)

## S4 method for signature 'EffectScenario,data.frame'
set_exposure(scenarios, series, ...)

## S4 method for signature 'EffectScenario,ExposureSeries'
set_exposure(scenarios, series, reset_times = TRUE)

## S4 method for signature 'EffectScenario,list'
set_exposure(scenarios, series, ...)

## S4 method for signature 'list,list'
set_exposure(scenarios, series, ...)

## S4 method for signature 'list,ANY'
set_exposure(scenarios, series, ...)

Arguments

scenarios	vector of scenarios
series	vector of ExposureSeries objects or a single data.frame
...	additional arguments
reset_times	logical, if TRUE, the exposure time-series' time points will be set as output times. Defaults to TRUE

Details

Exposure time-series are generally represented by a data.frame containing two columns. The first column for time, the second representing the exposure level. The ordering of columns is mandatory. The column names are non-relevant but sensible names may help documenting the scenario and its data. The data.frame's rows must be ordered chronologically. A time-series can consist of only a single row; in this case it will represent constant exposure.

For convenience, a time-series with zero exposure can be set using set_noexposure().

Computational efficiency

Handling time-series is a costly task for the ODE solver due to consistency checks and interpolation between time steps. How the solver interpolates the time-series can be controlled by optional arguments to functions such as simulate() and effect(). Please refer to simulate() for a brief overview and deSolve::forcings for a detailed description.

Exposure time-series should be kept as short as possible and as complex as needed for optimal computational efficiency.

Output times

By default, the exposure time-series' time points will also be used as output times of the scenario. Any output times previously set by set_times() will be lost. If this behavior is undesired, set the function argument reset_times=FALSE.

Multiple exposure series and scenarios

The functions supports modifying multiple scenarios at once: by calling it with lists of scenario and ExposureSeries objects. The cartesian product of all scenarios and exposure series will be returned, iff the parameter expand = TRUE is set.

As an example for the expand mode, two scenarios A and B and one exposure series g will result in two scenarios Ag and Bg, both using exposure series g. Two scenarios A and B as well as two exposure seres g and h will result in four scenarios Ag,Ah,Bg, and Bh.

Value

list of EffectScenario objects

Examples

# set a data.frame as exposure series
Lemna_Schmitt() %>% set_exposure(data.frame(time=c(0, 1, 2, 3), conc=c(1, 1, 0, 0)))

# set one ExposureSeries
es1 <- ExposureSeries(data.frame(time=0, conc=0))
Lemna_Schmitt() %>% set_exposure(es1)

# set two ExposureSeries to create two scenarios
es2 <- ExposureSeries(data.frame(time=5:10, conc=1))
Lemna_Schmitt() %>% set_exposure(c(es1, es2))

# set one ExposureSeries without resetting existing output times
Lemna_Schmitt() %>%
  set_times(0:5) %>%
  set_exposure(es1, reset_times=FALSE)

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