Movatterモバイル変換

Pipe operator

Description

Seemagrittr::%>% for details.

Usage

lhs %>% rhs

Value

description

Algae models

Description

Overview of supportedAlgae models

Details

• Algae_Weber() by Weberet al. (2012)

• Algae_TKTD() based on Weberet al. (2012), but with scaled damage

• Algae_Simple() simplified growth model without additional forcing variables

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

References

Weber D, Schaefer D, Dorgerloh M, Bruns E, Goerlitz G, Hammel K, Preuss TGand Ratte HT, 2012. Combination of a higher-tier flow-through system andpopulation modeling to assess the effects of time-variable exposure ofisoproturon on the green algae Desmodesmus subspictatus andPseudokirchneriella subcapitata. Environmental Toxicology andChemistry, 31(4), 899-908.doi:10.1002/etc.1765

EFSA Panel on Plant Protection Products and their Residues, 2018. Scientificopinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effectmodels for regulatory risk assessment of pesticides for aquatic organisms.EFSA journal 16:5377doi:10.2903/j.efsa.2018.5377

See Also

Lemna-models,Transferable

Other algae models:Algae_Simple(),Algae_TKTD(),Algae_Weber()

Other models:DEB-models,GUTS-RED-models,Lemna-models,Macrophyte-models

Simple algae model without environment (Rendal et al. 2023)

Description

The model is a mechanistic combined toxicokinetic-toxicodynamic (TK/TD) andgrowth model for algae. It follows the concept of a simplified algae modeldescribed in Rendal et al. (2023). The model simulates the development ofalgal biomass. The growth of the algae population is simulated on the basisof growth rates, which are, in contrast to the Weber model, independent onenvironmental conditions which are usually optimal in laboratory effect studies.The toxicodynamic sub-model describes the effects of growth-inhibitingsubstances through a corresponding reduction in the photosynthesis rate on thebasis of either external or internal concentrations (depending on user choiceofscaled parameter setting).

Usage

Algae_Simple()

Value

an S4 object of typeAlgaeSimple

State variables

The model has two state variables:

• A, Biomass (µg fresh wt/mL, cells/mL *10^4)

• Dw, scaled internal damage, only takes effect if parameterscaled = 1

Model parameters

• Growth model

  • mu_max, Maximum growth rate (d-1)

• Concentration response (Toxicodynamics)

  • EC_50, Effect concentration of 50% inhibition of growth rate (µg L-1)

  • b, slope of concentration effect curve at EC_50 (-)

  • dose_response, shape of the dose response curve (0 = logit, 1 = probit)

• External concentration (Toxicokinetics)

  • scaled, 1 = scaled internal damage, 0 = no internal damage / 1 = yes (-)

  • kD, dominant rate constant of toxicant in aquatic environments (d-1), onlytakes effect if parameterscaled = 1

Forcings

Simplified model without additional forcings for e.g. irradiation or temperatureas implemented inAlgae_Weber. A constant growth over time is assumed.In case that growth is time dependent, a forcing variable (f_growth) can be set.Forcing time-series are represented bydata.frame objects consisting of twocolumns. The first for time and the second for a scaling factor of mu_max.The input format for all forcings is a list of the data frames. If f_growth isnot set, a default scaling factor of 1 is used.

Parameter boundaries

Upper and lower parameter boundaries are set by default for each parameter. This,to avoid extreme values during calibration (particularly likelihood profiling)

Simulation output

Simulation results will contain the state variables biomass (A) andscaled damage concentration (Dw).

It is possible to amend the output ofsimulate() with additional modelquantities that are not state variables, for e.g. debugging purposes or toanalyze model behavior. To enable or disable additional outputs, use theoptional argumentnout ofsimulate(). As an example, setnout=2 toenable reporting of external concentration (Cw) and growth scaling factor(f_growth). Setnout=0 to disable additional outputs (default).

The available output levels are as follows:

• nout >= 1:Cw external concentration (µg L-1)

• nout >= 2:f_growth growth scaling factor (-)

• nout >= 3:dA, biomass derivative (µg)

• nout >= 4:dDw, damage concentration derivative (µg L-1)

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• hmax = 0.01
  Maximum step length in time suitable for most simulations.

References

Rendal C, Witt J, Preuss TG, Ashauer R, 2023: A Framework for Algae Modelingin Regulatory Risk Assessment. Environ. Toxicol. Chem. 42(8), pp. 1823-1838.doi:10.1002/etc.5649

Weber D, Schaefer D, Dorgerloh M, Bruns E, Goerlitz G, Hammel K, Preuss TGand Ratte HT, 2012: Combination of a higher-tier flow-through system andpopulation modeling to assess the effects of time-variable exposure ofisoproturon on the green algae Desmodesmus subspictatus andPseudokirchneriella subcapitata. Environ. Toxicol. Chem. 31(4), pp. 899-908.doi:10.1002/etc.1765

See Also

Scenarios,Transferable

Other algae models:Algae-models,Algae_TKTD(),Algae_Weber()

Algae model variant (Weber et al. 2012) with scaled damage

Description

The model is a mechanistic combined toxicokinetic-toxicodynamic (TK/TD) andgrowth model for algae. The model simulates the development of algal biomassunder laboratory and environmental conditions. The growth of the algaepopulation is simulated on the basis of growth rates, which are dependent onenvironmental conditions (radiation, temperature and phosphorus).The model is a variant of theAlgae_Weber() model (Weber 2012) as citedin EFSA TKTD opinion (2018). This Algae model,Algae_TKTD(), provides anadditional possibility (probit) to simulate the dose-response curve andconsiders a scaled internal damage instead of the external concentration.

Usage

Algae_TKTD()

Value

an S4 object of typeAlgaeTKTD

State variables

The model has four state variables:

• A, Biomass (µg fresh wt/mL, cells/mL *10^4)

• Q, Mass of phosphorous internal (µg P/µg fresh wt)

• P, Mass of phosphorous external (µg P/L)

• Dw, Damage concentration (µg/L)

Model parameters

• Growth model

  • mu_max, Maximum growth rate (d-1)

  • Q_min, Minimum intracellular P (µg P/µg fresh wt)

  • Q_max, Maximum intracellular P (µg P/µg fresh wt)

  • v_max, Maximum P-uptake rate at non-limited growth (µg P/µg fresh wt/d)

  • k_s, Half-saturation constant for extracellular P (mg P/L)

  • m_max, Natural mortality rate (1/d)

  • I_opt, Optimum light intensity for growth (µE/m²/s)

  • T_opt, Optimum temperature for growth (°C)

  • T_max, Maximum temperature for growth (°C)

  • T_min, Minimum temperature for growth (°C)

  • D, Dilution rate (1/d)

  • R_0, Influx concentration of P (mg P/L)

• Concentration response (Toxicodynamics)

  • EC_50, Effect concentration of 50% inhibition of growth rate (µg L-1)

  • b, slope of concentration effect curve at EC_50 (-)

  • dose_resp, shape of the dose response curve (0 = logit, 1 = probit)

• External concentration (Toxicokinetics)

  • kD, dominant rate constant (d-1)

Forcings

The Weber model variant requires two environmental properties as time-series input:

• T_act, temperature (°C), and

• I, irradiance (uE/m²/s).

The following constant default values are used for these properties:

• T_act = 23 °C

• I = 100 uE/m²/s

Forcings time-series are represented bydata.frame objects consisting of twocolumns. The first for time and the second for the environmental factor in question.

Entries of thedata.frame need to be ordered chronologically. A time-seriescan consist of only a single row; in this case it will represent constantenvironmental conditions. Seescenarios for more details.

Simulation output

Simulation results will contain the state variables Biomass (A), mass ofinternal phosphorous (Q), mass of external phosphorous (P) and the damageconcentration (Dw).

It is possible to amend the output ofsimulate() with additional modelquantities that are not state variables, for e.g. debugging purposes or toanalyze model behavior. To enable or disable additional outputs, use theoptional argumentnout ofsimulate(). As an example, setnout=2 toenable reporting of model derivativesdA anddQ. Setnout=0 to disableadditional outputs (default).

The available output levels are as follows:

• nout >= 1:C, external concentration (µg/L)

• nout >= 2:f(T), temperature dependence (-)

• nout >= 3:f(I), light dependence (-)

• nout >= 4:f(Q), nutrient dependence (-)

• nout >= 5:f(Q, P), uptake flow reduction (-)

• nout >= 6:f(C), effect of chemical stressor (-)

• nout >= 7:dA, biomass derivative (µg)

• nout >= 8:dQ, internal phosphorous derivative (mg P/µg fresh wt)

• nout >= 9:dP, external phosphorous derivative (mg P L-1)

• nout >= 10:dDw, damage concentration derivative (µg L-1)

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• hmax = 0.1
  Maximum step length in time suitable for most simulations.

Model history and changes

• cvasi v1.5.0

  • Support for simulating flow-through conditions by introducing new parametersD andR_0 and adapting the ODEs according to theAlgae_Weber model.

  • ODE of external phosphorous concentrationP corrected, which containedan erroneous growth term before.

  • Response functions added to optional simulation outputs, order of outputlevels modified.

References

Weber D, Schaefer D, Dorgerloh M, Bruns E, Goerlitz G, Hammel K, Preuss TGand Ratte HT, 2012. Combination of a higher-tier flow-through system andpopulation modeling to assess the effects of time-variable exposure ofisoproturon on the green algae Desmodesmus subspictatus andPseudokirchneriella subcapitata. Environmental Toxicology andChemistry, 31(4), 899-908.doi:10.1002/etc.1765

See Also

Scenarios,Transferable

Other algae models:Algae-models,Algae_Simple(),Algae_Weber()

Algae model,SAM-X (Weber et al. 2012)

Description

The model is a mechanistic combined toxicokinetic-toxicodynamic (TK/TD) andgrowth model for algae. The model simulates the development of algal biomassunder laboratory and environmental conditions and was developed byWeber et al. (2012) as cited in EFSA TKTD opinion (2018). The growth of thealgae population is simulated on the basis of growth rates, which aredependent on environmental conditions (radiation, temperature, and phosphorus).The toxicodynamic sub-model describes the effects of growth-inhibitingsubstances through a corresponding reduction in the photosynthesis rate onthe basis of internal concentrations.

Usage

Algae_Weber()SamX()

Details

Deviating from the equations described by Weber et al., this model implementationuses a user-defined time-series to represent (environmental) concentrations.Therefore, state-variableC and its differential equation was removed andmodel outputC is identical to the exposure time-series. The implementationof Weber et al. (2012) was followed where units differ from EFSA (2018).

Value

an S4 object of typeAlgaeWeber

Functions

• SamX(): Alias using original model name.

State variables

The model has three state variables:

• A, Biomass (µg fresh wt/mL, cells/mL *10^4)

• Q, Mass of phosphorous internal (mg P/L, or µg P/mL)

• P, Mass of phosphorous external (mg P/L, or µg P/mL)

The original model by Weber et al. contains an additional state variableC which models the external stressor concentration. However, the modelimplementation in this packages uses a user-defined time-series to representenvironmental concentrations.Therefore, state variableC and accompanying parameters are not present here.

Model parameters

• Growth model

  • mu_max, Maximum growth rate (d-1)

  • Q_min, Minimum intracellular P (µg P/µg fresh wt)

  • Q_max, Maximum intracellular P (µg P/µg fresh wt)

  • v_max, Maximum P-uptake rate at non-limited growth (µg P/µg fresh wt/d)

  • k_s, Half-saturation constant for extracellular P (mg P/L)

  • m_max, Natural mortality rate (1/d)

  • I_opt, Optimum light intensity for growth (uE/m²/s)

  • T_opt, Optimum temperature for growth (°C)

  • T_max, Maximum temperature for growth (°C)

  • T_min, Minimum temperature for growth (°C)

  • D, Dilution rate (1/d)

  • R_0, Influx concentration of P (mg P/L)

• Concentration response (Toxicodynamics)

  • EC_50, Effect concentration of 50% inhibition of growth rate (µg/L)

  • b, slope of concentration effect curve at EC_50 (-)

Forcings

The Weber model requires two environmental properties as time-series input:

• T_act, temperature (°C), and

• I, irradiance (uE/m²/s).

The following constant default values are used for these properties:

• T_act = 23 °C

• I = 100 uE/m²/s

Forcings time-series are represented bydata.frame objects consisting of twocolumns. The first for time and the second for the environmental factor in question.

Entries of thedata.frame need to be ordered chronologically. A time-seriescan consist of only a single row; in this case it will represent constantenvironmental conditions. Seescenarios for more details.

Simulation output

Simulation results will contain the state variables Biomass (A), mass ofinternal phosphorous (Q), mass of external phosphorous (P) and the externalconcentration (C).

It is possible to amend the output ofsimulate() with additional modelquantities that are not state variables, for e.g. debugging purposes or toanalyze model behavior. To enable or disable additional outputs, use theoptional argumentnout ofsimulate(). As an example, setnout=2 toenable reporting of external concentration and model derivativedA.Setnout=0 to disable additional outputs. The default isnout=1.

The available output levels are as follows:

• nout >= 1:C, external concentration (µg/L)

• nout >= 2:f(T), temperature dependence (-)

• nout >= 3:f(I), light dependence (-)

• nout >= 4:f(Q), nutrient dependence (-)

• nout >= 5:f(Q, P), uptake flow reduction (-)

• nout >= 6:f(C), effect of chemical stressor (-)

• nout >= 7:dA, biomass derivative (µg)

• nout >= 8:dQ, internal phosphorous derivative (mg P/µg fresh wt)

• nout >= 9:dP, external phosphorous derivative (mg P L-1)

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• hmax = 0.1
  Maximum step length in time suitable for most simulations.

Parameter boundaries

Default values for parameter boundaries are set for all parameters by expertjudgement, for calibration purposes. Values can be access from the object, anddefaults overwritten.

Model history and changes

• cvasi v1.5.0

  • Unused state variableC and parameterk removed from documentationand code. External concentrationC added to simulation output by meansof optional output levelnout=1.

References

Weber D, Schaefer D, Dorgerloh M, Bruns E, Goerlitz G, Hammel K, Preuss TGand Ratte HT, 2012. Combination of a higher-tier flow-through system andpopulation modeling to assess the effects of time-variable exposure ofisoproturon on the green algae Desmodesmus subspictatus andPseudokirchneriella subcapitata. Environmental Toxicology andChemistry, 31(4), 899-908.doi:10.1002/etc.1765

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, Brock T, Duquesne S, Grilli S,Hernandez-Jerez AF, Bennekou SH,Klein M, Kuhl T, Laskowski R, Machera K,Pelkonen O, Pieper S, Smith RH, Stemmer M, Sundh I, Tiktak A,Topping CJ,Wolterink G, Cedergreen N, Charles S, Focks A, Reed M, Arena M, Ippolito A,Byers H andTeodorovic I, 2018. Scientific Opinion on the state of the art ofToxicokinetic/Toxicodynamic (TKTD)effect models for regulatory risk assessmentof pesticides for aquatic organisms. EFSA Journal, 16(8), 5377.doi:10.2903/j.efsa.2018.5377

See Also

Scenarios,Transferable

Other algae models:Algae-models,Algae_Simple(),Algae_TKTD()

Calibration set

Description

Acalibration set combines ascenario, observed data, and anoptional weighting factor into one object. Thecalibration set is used to fitmodel parameters to observed data usingcalibrate().

Usage

caliset(scenario, data, weight = 1.0, tag = NULL)

Arguments

Details

Acalibration set usually represents a single experiment or trial.Multiple experimental replicates can be combined into a singleset, if modelparameters are identical between trials.If model parameters were modified during a trial, e.g. a pump failure occurredor flow rates changed, this can be represented by using ascenario sequenceinstead of a basicscenario. Please refer tosequence() for details.

Weighting

An optional weighting factor can be used to scale the error term of awholeset or of individual data points when fitting parameters using e.g.calibrate().

The vector of weights must either be of length one or have the same lengthas the dataset. In the former case, the same weight will be applied to allvalues in the dataset. In the latter, individual weights are appliedfor each data point.

Value

caliset() returns acalibration set object

Examples

library(dplyr)# Get observed biomass during control experiment by Schmitt et al. (2013)observed <- schmitt2013 %>%  filter(trial == "T0") %>%  select(time, obs)# Create a scenario that represents conditions during experimentscenario <- metsulfuron %>%  set_param(c(k_phot_fix=TRUE, k_resp=0, Emax=1)) %>%  set_init(c(BM=12)) %>%  set_noexposure() %>%  set_bounds(list(k_phot_max=c(0, 0.5)))# Create a calibration setcs <- caliset(scenario, observed)# Fit parameter 'k_phot_max' to observed biomass growth from experimentcalibrate(  cs,  par=c(k_phot_max=1),  output="BM",  method="Brent" # Brent is recommended for one-dimensional optimization) -> fitfit$par

Dynamic Energy Budget (DEB) models

Description

Supported models:

• DEB_abj

• DEBtox

See Also

Other DEB models:DEB_abj(),DEBtox()

Other models:Algae-models,GUTS-RED-models,Lemna-models,Macrophyte-models

DEB_abj

Description

Creates aDEB abj scenario. Theabj model with type M acceleration islike modelstd, but acceleration occurs between birth and metamorphosis (V1-morph).Isomorphy is assumed before and after acceleration. Metamorphosis is beforepuberty and occurs at maturityE_Hj, which might or might not correspond withchanges in morphology. Theabj model is a one-parameter extension of modelstd(DEB Wiki).

Usage

DEB_abj()

Details

State variables

The following list describes the default names and standard units of the model'sstate variables:

• L, structural length (cm)

• E, energy reserve (J)

• H, energy invested in maturity (J)

• R, reproduction buffer (J)

• cV, internal concentration (C)

• Lmax, maximum structural length (cm)

All state variables are initialized with zero. Seeset_init() on how to setthe initial state.

Parameters

The following model parameters are required:

• p_M, vol-spec somatic maintenance (J/d.cm^3)

• v, energy conductance (cm/d)

• k_J, maturity maint rate coefficient (1/d)

• p_Am, surface-area specific maximum assimilation rate (J/d.cm^2)

• kap, allocation fraction to soma (-)

• E_G, spec cost for structure (J/cm^3)

• f, scaled functional response (-)

• E_Hj, maturity at metamorphosis (J)

• E_Hp, maturity at puberty (J)

• kap_R, reproduction efficiency (-)

• L_b, structural length at birth (cm)

• L_j, structural length at metamorphosis (cm)

• ke, elimination rate constant (d-1)

• c0, no-effect concentration sub-lethal (C)

• cT, tolerance concentration (C)

• MoA, mode of action switch (-)

Mode of Actions

Any combination of the following mode of actions (MoA) can be considered bythe model:

• MoA = 1: effect on feeding

• MoA = 2: effect on maintenance costs

• MoA = 4: effect on overhead costs for making an egg

• MoA = 8: hazard during oogenesis

• MoA = 16: energy conductance

To activate more than one MoA, simply add up the correspondingcodes. To disable all MoAs, set the parameter to zero.See alsoset_mode_of_action().

Effects

The state variablesL (structural length) andR (reproduction buffer) areset as effect endpoints by default. All state variables are available aspotential endpoints. The list of considered endpoints can be modifiedby usingset_endpoints().

To calculate effects, eachDEB scenario is simulated twice: One simulationwhich considers exposure to a toxicant and one simulation without exposure, i.e.a control. See alsoeffect().

Value

an S4 object of typeDebAbj

Simulation output

Simulation results will contain the state variables.It is possible to amend the output ofsimulate() with additional modelquantities that are not state variables, for e.g. debugging purposes or toanalyze model behavior. To enable or disable additional outputs, use theoptional argumentnout ofsimulate(). As an example, setnout=2 toenable reporting of the acceleration factor (MV) and the mobilization flux(pC). Setnout=0 to disable additional outputs (default).

The available output levels are as follows:

• nout >= 1:MV acceleration factor (-)

• nout >= 2:pC mobilization flux (J/d)

• nout >= 3:pA assimilation flux (J/d)

• nout >= 4:pJ energy invested in maturity flux (J/d)

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

See Also

Other DEB models:DEB-models,DEBtox()

Examples

# Create an abj scenario from scratch and simulate itDEB_abj() %>%  set_init(c(L=0.02,E=0.1,H=0.01)) %>%  set_param(c(p_M=3000,v=0.02,k_J=0.6,p_Am=300,kap=0.9,E_G=4000,f=1,              E_Hj=0.05,E_Hp=0.3,kap_R=0.9,ke=1,c0=0,cT=1,L_b=0.02,              L_j=0.04,MoA=0)) %>%  set_noexposure() %>%  set_times(0:10) %>%  simulate()# Print information about sample scenario 'americamysis'americamysis# Simulate 'americamysis' scenarioamericamysis %>% simulate()

DEBtox model

Description

Creates aDEBtox scenario as described by Jager (2020). Itrepresents a simplifiedDEBtox model based onDEBkiss. In theBYOMapplication [link], this model isreferred to asDEBtox 2019, version 4.7.It supports an optional feature of theERA special model variant, whichcan consider a referenceLm parameter to compare results of multipledatasets.

Usage

DEBtox()DEB_Daphnia()

Details

State variables

The following list describes the names and units of themodel's state variables:

• D, scaled damage ([C])

• L, body length (mm)

• R, cumulative reproduction (-)

• S, survival probability (-)

State variablesD,L, andR are initialized with zero. VariableSis initialized with one (1.0). Seeset_init() on how to setthe initial state manually.

Parameters

The following parameters are required:

• General

  • L0, body length at start (mm)

  • Lp, body length at puberty (mm)

  • Lm, maximum body length (mm)

  • rB, von Bertalanffy growth rate constant (1/d)

  • Rm, maximum reproduction rate (#/d)

  • f, scaled functional response (-)

  • hb, background hazard rate (d-1)

  • a, Weibull background hazard coefficient (-). Set to1 to disable.

• Extra parameters

  • Lf, body length at half-saturation feeding (mm)

  • Lj, body length at which acceleration stops (mm)

  • Tlag, lag time for start development (d)

• TK/TD parameters

  • kd, dominant rate constant (d-1)

  • zb, effect threshold energy budget ([C])

  • bb, effect strength energy-budget effects (1/[C])

  • zs, effect threshold survival ([C])

  • bs, effect strength survival (1/([C] d))

• Other parameters (formerly globals inBYOM)

  • FBV, dry weight egg as fraction of structural body weight (-)

  • KRV, part. coeff. repro buffer and structure (kg/kg) (for losses with reproduction)

  • kap, approximation for kappa (for starvation response)

  • yP, product of yVA and yAV (for starvation response)

  • Lm_ref, optional reference max length for scaling rate constants (mm).Set to zero to disable the reference length. Disabled by default.

  • len, a switch to control body length dynamics:1 organism can shrink,2 organism cannot shrink. Default value is1.

  • Tbp, optional brood-pouch delay (d). Set toNA or zero to disable.Default value is0.

  • MoA, mode of action switches (-). Default value is0.

  • FB, feedback on damage dynamics switches (-). Default value is0.

A referenceLm_ref is needed to properly compare different data sets,or when calibrating on more than one data set. IfLm differs, one would notwant to have different rate constants at the same length.

Mode of Action

Any combination of the following mode of actions (MoA) can be considered bythe model:

• MoA = 1: assimilation/feeding

• MoA = 2: costs for maintenance

• MoA = 4: costs for growth and reproduction

• MoA = 8: costs for reproduction

• MoA = 16: hazard for reproduction

To activate more than one mode of action, simply add up the correspondingcodes and set parameterMoA to the desired value. To disable all mode ofactions, set parameterMoA to zero. See alsoset_moa().

As an example, to consider effects on feeding and maintenance, set themode of action to three (3):

DEBtox() %>% set_param(c(MoA=3))

Feedbacks

Any combination of the following damage feedbacks can be considered bythe model:

• 1: surf:vol scaling uptake rate

• 2: surf:vol scaling elimination rate

• 4: growth dilution

• 8: losses with reproduction

To activate more than one feedback, simply add up the correspondingcodes. To disable all feedbacks, set the parameter to zero.

Effects

The state variablesL (body length),R (cumulative reproduction), andS (survival probability) are set as effect endpoints by default. All statevariables are available as potential endpoints. The list of consideredendpoints can be modified by usingset_endpoints().

To calculate effects, eachDEBtox scenario is simulated twice: One simulationwhich considers exposure to a toxicant and one simulation without exposure, i.e.a control. See alsoeffect().

Simulation output

The following intermediary model variables can be added to the modeloutput on demand. Simply set the optional parameternout to therequired output level and pass it tosimulate().

• nout >= 1:f, actual scaled response

• nout >= 2:fR, actual f considering starvation

• nout >= 3:kd, actual kd

• nout >= 4:s, stress level

• nout >= 5:h, hazard rate

• nout >= 6:sA, stress factor on assimilation/feeding

• nout >= 7:sM, stress factor on maintenance

• nout >= 8:sG, stress factor on growth costs

• nout >= 9:sR, stress factor on reproduction costs

• nout >= 10:sH, stress factor on hazard to reproduction

• nout >= 11:xu, damage feedback factor for surf:vol scaling uptake rate

• nout >= 12:xe, damage feedback factor for surf:vol scaling elimination rate

• nout >= 13:xG, damage feedback factor for growth dilution

• nout >= 14:xR, damage feedback factor for losses with repro

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• method = 'ode45'
  Selects the Dormand-Prince 4(5) method of the Runge-Kutta family, seedeSolve::rkMethod() for details.

Model history and changes

• cvasi v1.0.0

  • TheDEB_Daphnia() model implemented BYOM'sDEBtox 2019model version 4.5

• cvasi v1.2.0

  • The model equations were updated to conform with BYOM'sDEBtox 2019version 4.7. This introduced a new model parametera, the Weibullbackground hazard coefficient, and limited the maximum hazard rate to99% per hour.

  • The scenario constructor was renamed toDEBtox().

  • Additional intermediary model variables available as optional simulationoutput

Value

an S4 object of typeDebTox

Functions

• DEB_Daphnia(): Deprecated model variant ofDEBtox()

References

Jager T, 2020: Revisiting simplified DEBtox models for analysingecotoxicity data. Ecol Model 416.doi:10.1016/j.ecolmodel.2019.108904

Romoli et al., 2024: Environmental risk assessment with energy budgetmodels: a comparison between two models of different complexity.Environ Toxicol Chem 43(2):440-449.doi:10.1002/etc.5795

See Also

Other DEB models:DEB-models,DEB_abj()

Exposure time-series

Description

Creates an object that encapsulates an exposure time-series with itsmetadata, such as formatted datetime strings and file name where theseries was loaded from.no_exposure() is shorthand to create a time-seriesof constant zero exposure.

Usage

ExposureSeries(series, dates, file, meta, context)

Arguments

Value

an S4 object of typeExposureSeries

Slots

dates

original time points of time-series, e.g. time stamps of the form⁠2000-01-01 12:00⁠

file

character, file name where data originates from, may be empty

meta

list, contains metadata

context

list, contains contextual metadata, such as project ids

series

data.frame containing the actual time-series

See Also

no_exposure()

GUTS-RED models

Description

ReducedGeneral Unified Threshold models of Survival (GUTS) with stochasticdeath (SD) and individual tolerance (IT)

Details

The TKTD modelsGUTS-RED-SD andGUTS-RED-ITwere described by EFSA (2018).GUTS-RED models assume a one-compartment model which directly linksexternal concentration to the scaled damage. The scaled damage is given inunits of concentration, equal to the units of measurement in the externalmedium, e.g. ug/L. The damage dynamics is connected to an individual hazardstate variable, resulting in simulated mortality when an internal damagethreshold is exceeded. The death mechanisms stochastic death (SD) andindividual threshold (IT) are extreme cases of theGUTS theory.

ForSD models, the threshold parameter for lethal effects is fixed andidentical for all individuals of a group, meaning that the variance of thethreshold values is zero. Hence, the killing rate relates the probability ofa mortality event in proportion to the scaled damage. ForIT models,the thresholds for effects are distributed among individuals of a group.Mortality of an individual follows immediately once the individual's toleranceis exceeded. Meaning in model terms that the killing rate is set toinfinity (EFSA 2018).

State variables

The following list describes the default names and standard units ofGUTS-REDstate variables:

• D, scaled damage (conc)

• H, cumulative hazard (-)

The state variables are initialized with zero by default.

SD model parameters

• kd, dominant rate constant (time^-1)

• hb, background hazard rate (time^-1)

• z, threshold for effects (conc)

• kk, killing rate constant (time^-1)

IT model parameters

• kd, dominant rate constant (time^-1)

• hb, background hazard rate (time^-1)

• alpha, median of thresholds (conc)

• beta, shape parameter (-)

Effects

The effect endpointL (lethality) is available forGUTS-RED models.A value of zero (0.0) denotesno effect on organism survival. A value ofone (1.0) denotes a lethality rate of 100%, i.e. no survivors.

The survival probabilityS is available in the return value ofsimulate().

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

See Also

Other GUTS-RED models:GUTS_RED_IT(),GUTS_RED_SD()

Other models:Algae-models,DEB-models,Lemna-models,Macrophyte-models

GUTS-IT scenario

Description

FullGeneral Unified Threshold models of Survival (GUTS) with Individual Tolerancecompatible with theFull GUTS model as described by EFSA (2018), butsome parameter names may differ.

Usage

GUTS_IT(scaled_ci = FALSE, dose_metric = c("D", "Ci", "Cw"))

Arguments

Value

an S4 object of typeGutsIt-class

State variables

The following list describes the default names and standard units ofGUTSstate variables:

• Ci, (scaled) internal concentration (conc)

• D, (scaled) damage (*)

• H, cumulative hazard (-)

The state variables are initialized with zero by default.

IT model parameters

The set of parameters and their names follows the definition by Jager et al(2011). The actual number of required parameters depends on the selected modelvariant, i.e. if the internal concentration is scaled or not, as well as theselected dose metric. The full set of parameters is as follows

• ki, accumulation rate into body (time^-1)

• ke, elimination rate (time^-1)

• Kiw, scaling constant for external concentration (*)

• kr, damage recovery rate (time^-1)

• hb, background hazard rate (time^-1)

• alpha, median of thresholds (conc)

• beta, shape parameter (-)

Effects

The effect endpointL (lethality) is available forGUTS models.A value of zero (0.0) denotesno effect on organism survival. A value ofone (1.0) denotes a lethality rate of 100%, i.e. no survivors.

The survival probabilityS is available in the return value ofsimulate().

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

Jager T., Albert C., Preuss T.G., and Ashauer R., 2011: General Unified ThresholdModel of Survival - a Toxicokinetic-Toxicodynamic Framework for Ecotoxicology.Environ. Sci. Technol. 45(7), pp. 2529-2540.doi:10.1021/es103092a

See Also

GUTS-RED-IT

Other GUTS models:GUTS_SD()

GUTS-RED-IT scenario

Description

ReducedGeneral Unified Threshold models of Survival (GUTS) withindividual tolerance (IT).

Usage

GUTS_RED_IT(param, init)

Arguments

Value

an S4 object of typeGutsRedIt

Simulation output

The return value ofsimulate() will contain values for the state variables,as well as an additional columnS which represents the survival probabilityfor each time point.S is calculated as described in EFSA (2018) asS = (1- F(t)). The background hazard ratehb is already considered in statevariableH and therefore does not occur as an additional term to deriveS.

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Model history and changes

• cvasi v1.0.0

  • Model and parameters as described by EFSA PPR (2018).

• cvasi v1.5.0

  • Cumulative damage over time will be calculated on ODE level, instead onresults ofsimulate(), to avoid influence of selected output timeson predicted survival.

State variables

The following list describes the default names and standard units ofGUTS-REDstate variables:

• D, scaled damage (conc)

• H, cumulative hazard (-)

The state variables are initialized with zero by default.

IT model parameters

• kd, dominant rate constant (time^-1)

• hb, background hazard rate (time^-1)

• alpha, median of thresholds (conc)

• beta, shape parameter (-)

Effects

The effect endpointL (lethality) is available forGUTS-RED models.A value of zero (0.0) denotesno effect on organism survival. A value ofone (1.0) denotes a lethality rate of 100%, i.e. no survivors.

The survival probabilityS is available in the return value ofsimulate().

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

See Also

Other GUTS-RED models:GUTS-RED-models,GUTS_RED_SD()

GUTS-RED-SD scenario

Description

ReducedGeneral Unified Threshold models of Survival (GUTS) with stochasticdeath (SD).

Usage

GUTS_RED_SD(param, init)

Arguments

Value

an S4 object of typeGutsRedSd

Simulation output

The return value ofsimulate() will contain values for the state variables,as well as an additional columnS which represents the survival probabilityfor each time point.S is calculated as described in EFSA (2018) asS = exp(-H). The background hazard ratehb is already considered in statevariableH and therefore does not occur as an additional term to deriveS.

State variables

The following list describes the default names and standard units ofGUTS-REDstate variables:

• D, scaled damage (conc)

• H, cumulative hazard (-)

The state variables are initialized with zero by default.

SD model parameters

• kd, dominant rate constant (time^-1)

• hb, background hazard rate (time^-1)

• z, threshold for effects (conc)

• kk, killing rate constant (time^-1)

Effects

The effect endpointL (lethality) is available forGUTS-RED models.A value of zero (0.0) denotesno effect on organism survival. A value ofone (1.0) denotes a lethality rate of 100%, i.e. no survivors.

The survival probabilityS is available in the return value ofsimulate().

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

See Also

Other GUTS-RED models:GUTS-RED-models,GUTS_RED_IT()

GUTS-SD scenario

Description

FullGeneral Unified Threshold models of Survival (GUTS) with stochasticdeath (SD). The model was defined by Jager et al. (2011). It iscompatible with theFull GUTS model as described by EFSA (2018), butsome parameter names may differ.

Usage

GUTS_SD(scaled_ci = FALSE, dose_metric = c("D", "Ci", "Cw"))

Arguments

Value

an S4 object of typeGutsSd-class

State variables

The following list describes the default names and standard units ofGUTSstate variables:

• Ci, (scaled) internal concentration (conc)

• D, (scaled) damage (*)

• H, cumulative hazard (-)

The state variables are initialized with zero by default.

SD model parameters

The set of parameters and their names follows the definition by Jager et al(2011). The actual number of required parameters depends on the selected modelvariant, i.e. if the internal concentration is scaled or not, as well as theselected dose metric. The full set of parameters is as follows

• ki, accumulation rate into body (time^-1)

• ke, elimination rate (time^-1)

• Kiw, scaling constant for external concentration (*)

• kr, damage recovery rate (time^-1)

• kk, killing rate constant (time^-1)

• hb, background hazard rate (time^-1)

• z, threshold for effects (*)

Effects

The effect endpointL (lethality) is available forGUTS models.A value of zero (0.0) denotesno effect on organism survival. A value ofone (1.0) denotes a lethality rate of 100%, i.e. no survivors.

The survival probabilityS is available in the return value ofsimulate().

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

Jager T., Albert C., Preuss T.G., and Ashauer R., 2011: General Unified ThresholdModel of Survival - a Toxicokinetic-Toxicodynamic Framework for Ecotoxicology.Environ. Sci. Technol. 45(7), pp. 2529-2540.doi:10.1021/es103092a

See Also

GUTS-RED-SD

Other GUTS models:GUTS_IT()

Lemna models

Description

Overview of supportedLemna models

Details

• Lemna_Schmitt() by Schmittet al. (2013)

• Lemna_SETAC() by Kleinet al. (2021)

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

See Also

Macrophyte-models

Other Lemna models:Lemna_SETAC(),Lemna_Schmitt()

Other models:Algae-models,DEB-models,GUTS-RED-models,Macrophyte-models

Lemna model v1.3 (Klein et al. 2021)

Description

The model was described and published by the SETAC Europe Interest GroupEffect Modeling (Klein et al. 2021). It is based on theLemna modelby Schmitt (2013). The model is a mechanistic combinedtoxicokinetic-toxicodynamic (TK/TD) and growth model for the aquaticmacrophytesLemna spp.. The model simulates the development of Lemna biomassunder laboratory and environmental conditions. Growth of the Lemna populationis simulated on basis of photosynthesis and respiration rates which arefunctions of environmental conditions. The toxicodynamic sub-model describesthe effects of growth-inhibiting substances by a respective reduction in thephotosynthesis rate based on internal concentrations.

Usage

Lemna_SETAC()

Value

an S4 object of typeLemnaSetac

State variables

The model has two state variables:

• BM, Biomass (g dw)

• M_int, Mass of toxicant in plant population (ng)

The units of the state variablesBM andM_int are to be interpretedasper vessel in laboratory tests, and asper square meter for field populations.The same interpretation applies to all parameters relating biomass and toxicant mass toother entities.

Model parameters

• Growth model

  • k_photo_fixed, Model switch for unlimited growth conditions (TRUE/FALSE)

  • k_photo_max, Maximum photosynthesis rate (d-1)

  • k_loss, Reference loss rate (d-1)

  • BM_threshold, Lower biomass abundance threshold, (g dw)

  • BM_min, Reservoir for biomass recovery, (g dw)

• Temperature response of photosynthesis

  • T_opt, Optimum growth temperature (°C)

  • T_min, Minimum growth temperature (°C)

  • T_max, Maximum growth temperature (°C)

• Temperature response of biomass loss rate

  • Q10, Temperature coefficient (-)

  • T_ref, Reference temperature for response=1 (°C)

• Irradiance reponse of photosynthesis

  • alpha, Slope of irradiance response (m2 d kJ-1)

  • beta, Intercept of irradiance response (-)

• Nutrient response of photosynthesis

  • N_50, Half-saturation constant of Nitrogen (mg N L-1)

  • P_50, Half-saturation constant of Phosphorus (mg P L-1)

• Density dependence of photosynthesis

  • BM_L, Carrying capacity (g dw)

• Concentration response (Toxicodynamics)

  • EC50_int, Internal concentration resulting in 50% effect (ug L-1)

  • E_max, Maximum inhibition (-)

  • b, Slope parameter (-)

• Internal concentration (Toxicokinetics)

  • P, Permeability (cm d-1)

  • r_A_DW, Area per dry-weight ratio (cm2 g-1)

  • r_FW_DW, Fresh weight per dry weight ratio (-)

  • r_FW_V, Fresh weight density (g cm-3)

  • r_DW_FN, Dry weight per frond ratio (g dw)

  • K_pw, Partitioning coefficient plant:water (-)

  • k_met, Metabolisation rate (d-1)

Forcings

External concentrations, aliasexposure, have to be provided asug L-1.

Besides exposure, the model requires four environmental properties asinput:

• tmp, ambient temperature (°C)

• irr, irradiance (kJ m-2 d-1)

• P, Phosphorus concentration (mg P L-1)

• N, Nitrogen concentration (mg N L-1)

The following constant default values are used for these properties:

• tmp = 12 °C

• irr = 15,000 kJ m-2 d-1

• P = 0.3 mg L-1

• N = 0.6 mg L-1

Forcings time-series are represented bydata.frame objects consisting of twocolumns. The first for time and the second for the environmental factor in question.

Entries of thedata.frame need to be ordered chronologically. A time-seriescan consist of only a single row; in this case it will represent constantenvironmental conditions. Seescenarios for more details.

Effects

Supported effect endpoints includeBM (biomass) andr (averagegrowth rate during simulation). The effect on biomass is calculated fromthe last state of a simulation. Be aware that endpointr is incompatiblewith biomass transfers.

Simulation output

For reasons of convenience, the return value ofsimulate() contains bydefault two additional variables derived from simulation results:the internal concentrationC_int as well as the number of frondsFrondNo.These can be disabled by setting the argumentnout = 0.

The available output levels are as follows:

• nout >= 1:C_int, internal concentration (mass per volume)

• nout >= 2:FrondNo, frond number (-)

• Response functions

  • nout >= 3:f_loss, respiration dependency function (-)

  • nout >= 4:f_photo, photosynthesis dependency function (-)

  • nout >= 5:fT_photo, temperature response of photosynthesis (-)

  • nout >= 6:fI_photo, irradiance response of photosynthesis (-)

  • nout >= 7:fP_photo, phosphorus response of photosynthesis (-)

  • nout >= 8:fN_photo, nitrogen response of photosynthesis (-)

  • nout >= 9:fBM_photo, density response of photosynthesis (-)

  • nout >= 10:fCint_photo, concentration response of photosynthesis (-)

• Environmental variables

  • nout >= 11:C_int_unb, unbound internal concentration (mass per volume)

  • nout >= 12:C_ext, external concentration (mass per volume)

  • nout >= 13:Tmp, temperature (deg C)

  • nout >= 14:Irr, irradiance (kJ m-2 d-1)

  • nout >= 15:Phs, Phosphorus concentration (mg P L-1)

  • nout >= 16:Ntr, Nitrogen concentration (mg N L-1)

• Derivatives

  • nout >= 17:dBM, biomass derivative (g dw m-2 d-1)

  • nout >= 18:dM_int, mass of toxicant in plants derivative (mass per m2 d-1)

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• hmax = 0.1
  Maximum step length in time suitable for most simulations.

Model history and changes

• cvasi v1.0.0

  • Model and parameters as described by Klein et al. (2022) report version 1.1

• cvasi v1.5.0

  • Default value of parameterbeta modified due to typo in previous reportversions, now conforms with Klein et al. (2025), report version 1.2

  • New value:beta=0.25, old value:beta=0.025

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

References

Klein J., Cedergreen N., Heine S., Reichenberger S., Rendal C.,Schmitt W., Hommen U., 2021:Refined description of the Lemna TKTD growth modelbased on Schmitt et al. (2013) - equation system and default parameters.Report of the working groupLemna of the SETAC Europe Interest Group EffectModeling. Version 1.3, uploaded in July 2025.https://www.setac.org/group/effect-modeling.html

Schmitt W., Bruns E., Dollinger M., and Sowig P., 2013:Mechanistic TK/TD-model simulating the effect of growth inhibitors onLemna populations. Ecol Model 255, pp. 1-10.doi:10.1016/j.ecolmodel.2013.01.017

See Also

Lemna-models,Macrophyte-models,Transferable,Scenarios

Other Lemna models:Lemna-models,Lemna_Schmitt()

Other macrophyte models:Lemna_Schmitt(),Macrophyte-models,Magma

Lemna model (Schmitt et al. 2013)

Description

The model is a mechanistic combined toxicokinetic-toxicodynamic (TK/TD) andgrowth model for the aquatic macrophytesLemna spp.The model simulates the development ofLemna biomass under laboratory andenvironmental conditions and was developed by Schmittet al. (2013). Growthof theLemna population is simulated on basis of photosynthesis and respirationrates which are functions of environmental conditions.The toxicodynamic sub-model describes the effects of growth-inhibitingsubstances by a respective reduction in the photosynthesis rate based oninternal concentrations. This is the historical version of the Lemna model.For current uses, we recommend the Lemna (SETAC) model, which is a more recentversion of the Schmitt model.

Usage

Lemna_Schmitt(param, init)Lemna_SchmittThold(param, init)

Arguments

Details

Constructors to ease creation of scenarios based on theLemna model bySchmittet al. (2013).A variant of thisLemna model,Lemna_SchmittThold(), provides an additionalcumulative exposure threshold parameter. The Lemna biomass stops growingif the integral of exposure over time exceeds the threshold. The integralof exposure is internally accounted for by an additional state variableAUC (Area Under Curve).

Value

an S4 object of typeLemnaSchmitt

Functions

• Lemna_SchmittThold(): model variant with cumulative exposure threshold

State variables

The following list describes the default names and standard units of the model'sstate variables:

• BM, g_dw/m2, dry weight biomass per square meter

• E, -, effect [0,1]

• M_int, ug, internal toxicant mass

• AUC, ug/L, cumulative exposure (only forLemnaThreshold model)

Biomass (BM) and internal toxicant mass (M_int) are initialized to zero bydefault. Seeset_init() on how to set the initial states.

Model parameters

The following model parameters are required:

• Fate and biomass

  • k_phot_fix, logical, TRUE then k_phot_max is not changed by environmental factors, else FALSE

  • k_phot_max, 1/d, maximum photosynthesis rate

  • k_resp, 1/d, respiration rate

  • k_loss, 1/d, rate of loss (e.g. flow rate)

  • mass_per_frond, g_dw/frond, dry weight per frond

  • BMw2BMd, g_fw/g_dw, Fresh weight/dry weight

• Effect

  • Emax, -, maximum effect [0,1]

  • EC50, ug/L, midpoint of effect curve

  • b, -, slope of effect curve

• Toxicokinetics

  • P_up, cm/d, Permeability for uptake

  • AperBM, cm2/g_dw, A_leaf / d_leaf = 1/d_leaf (for circular disc, d=0.05 cm)

  • Kbm, -, Biomass(fw) : water partition coefficient

  • P_Temp, logical, TRUE to enable temperature dependence of cuticle permeability, else FALSE

  • MolWeight, g/mol, Molmass of molecule (determines Q10_permeability)

• Temperature dependence

  • Tmin, deg C, minimum temperature for growth

  • Tmax, deg C, maximum temperature for growth

  • Topt, deg C, optimal temperature for growth

  • t_ref, deg C, reference temperature for respiration rate

  • Q10, -, temperature dependence factor for respiration rate

• Light dependence

  • k_0, 1/d, light dependence: intercept of linear part

  • a_k, (1/d)/(kJ/m2.d), light dependence: slope of linear part

• Phosphorus dependence (Hill like dep.)

  • C_P, mg/L, phosphorus concentration in water

  • CP50, mg/L, phosphorus conc. where growth rate is halfed

  • a_p, -, Hill coefficient

  • KiP, mg/L, p-inhibition constant for very high p-conc.

• Nitrogen dependence (Hill like dep.)

  • C_N, mg/L, nitrogen concentration in water

  • CN50, mg/L, n-conc. where growth rate is halfed

  • a_N, -, Hill coefficient

  • KiN, mg/L, n-inhibition constant for very high p-conc.

• Density dependence

  • BM50, g_dw/m2, cut off BM

TheLemna_SchmittThold model requires the following additional parameter:

• threshold, ug/L, cumulative exposure threshold

Forcings

Besides exposure, the model requires four environmental properties astime-series input:

• temp, temperature (°C)

• rad, global irradiation (kJ m-2 d-1)

The following constant default values are used for these properties:

• temp = 12 °C

• rad = 15,000 kJ m-2 d-1

Forcings time-series are represented bydata.frame objects consisting of twocolumns. The first for time and the second for the environmental factor in question.

Entries of thedata.frame need to be ordered chronologically. A time-seriescan consist of only a single row; in this case it will represent constantenvironmental conditions. Seescenarios for more details.

Effects

Supported effect endpoints includeBM (biomass) andr (averagegrowth rate during simulation). The effect on biomass is calculated fromthe last state of a simulation. Be aware that endpointr is incompatiblewith frond transfers.

Parameter boundaries

Default values for parameter boundaries are set for all parameters by expertjudgement, for calibration purposes. Values can be access from the object, anddefaults overwritten.

Simulation output

Simulation results will contain two additional columns besides state variables:

• C_int, ug/L, internal concentration of toxicant

• FrondNo, -, number of fronds

It is possible to amend the output ofsimulate() with additional modelquantities that are not state variables, for e.g. debugging purposes or toanalyze model behavior. To enable or disable additional outputs, use theoptional argumentnout ofsimulate(), see examples below.nout=1enables reporting of internal concentration (C_int),nout=14 enables alladditional outputs, andnout=0 will disable additional outputs.

The available output levels are as follows:

• nout >= 1:C_int, internal concentration (ug/L)

• nout >= 2:FrondNo, number of fronds (-)

• nout >= 3:C_int_u, unbound internal concentration (ug/l)

• Growth and TK/TD

  • nout >= 4:BM_fresh, fresh weight biomass (g_fw/m2)

  • nout >= 5:k_photo_eff, current photosynthesis rate (1/d)

  • nout >= 6:k_resp_eff, current respiration rate (1/d)

  • nout >= 7:f_Eff, toxic effect factor (-)

  • nout >= 8:P_up_eff, current permeability for uptake (cm/d)

• Environmental variables

  • nout >= 9:actConc, current toxicant concentration in surrounding medium (ug/L)

  • nout >= 10:actTemp, current environmental temperature (deg C)

  • nout >= 11:actRad, current environmental radiation (kJ/m2.d)

• Derivatives

  • nout >= 12:⁠d BM/dt⁠, current change in state variable BM

  • nout >= 13:⁠d E/dt⁠, current change in effect

  • nout >= 14:⁠d M_int/dt⁠, current change in internal toxicant mass

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• hmax = 0.1
  Maximum step length in time suitable for most simulations.

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

References

Schmitt W., Bruns E., Dollinger M., and Sowig P., 2013:Mechanistic TK/TD-model simulating the effect of growth inhibitors onLemna populations. Ecol Model 255, pp. 1-10.doi:10.1016/j.ecolmodel.2013.01.017

See Also

Lemna-models,Macrophyte-models,Transferable,Scenarios

Other Lemna models:Lemna-models,Lemna_SETAC()

Other macrophyte models:Lemna_SETAC(),Macrophyte-models,Magma

Macrophyte models

Description

Population models of standard test macrophytes, such asLemna spp.

Details

Available macrophyte models:

• Lemna

• Magma

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

See Also

Scenarios

Other macrophyte models:Lemna_SETAC(),Lemna_Schmitt(),Magma

Other models:Algae-models,DEB-models,GUTS-RED-models,Lemna-models

Magma model (Witt et al., submitted)

Description

TheMagma model interprets the Tier 2C version of theLemna model byKlein et al. (2021), as a generic macrophyte model.It is mathematically equivalent to the Tier 2C version of the modelby Klein et al. (2021) with the recommended Tier 2C settingsk_photo_fixed=TRUEandk_resp=0.

Usage

Magma(growth = c("exp", "log"))Myrio()Myrio_log()

Arguments

Details

In particular, the growth model is a simple exponential growth model,which is considered to be the typical situation for a laboratory macrophytestudy. Instead of frond numbers as for Lemna, the biomass is also returned astotal shoot length (TSL) in simulation results. Consequently, the model hasthe additional parameterr_DW_TSL (dry weight per total shoot length ratio)instead ofr_DW_FN (dry weight per frond number ratio). A model variantwith an option for logistic growth is provided as well.

Value

an S4 object of typeMagma

State variables

The model has two state variables:

• BM, Biomass (g dw)

• M_int, Mass of toxicant in plant population (ng)

Model parameters

The growth model can either simulate exponential growth (the default) orlogistic growth. For logistic growth, an additional parameterD_L describingthe limit density or carrying capacity needs to be provided.

• Growth model

  • mu_control, Maximum photosynthesis rate (d-1), default:0.47

  • (optional)D_L, Limit density (g dw)

• Concentration response (Toxicodynamics)

  • EC50_int, Internal concentration resulting in 50% effect (ug L-1)

  • E_max, Maximum inhibition (-), default:1

  • b, Slope parameter (-)

• Internal concentration (Toxicokinetics)

  • P, Permeability (cm d-1)

  • r_A_DW, Area per dry-weight ratio (cm2 g-1), default:1000

  • r_FW_DW, Fresh weight per dry weight ratio (-), default:16.7

  • r_FW_V, Fresh weight density (g cm-3), default:1

  • r_DW_TSL, Dry weight per total shoot length ratio (g dw cm-1)

  • K_pw, Partitioning coefficient plant:water (-), default:1

  • k_met, Metabolisation rate (d-1), default:0

Environmental factors

None.

Parameter boundaries

Default values for parameter boundaries are set for all parameters by expertjudgement, for calibration purposes. Values can be modified usingset_bounds().

Simulation output

Simulation results will contain the state variables biomass (BM) andmass of internal toxicant (M_int).

It is possible to amend the output ofsimulate() with additional modelquantities that are not state variables, for e.g. debugging purposes or toanalyze model behavior. To enable or disable additional outputs, use theoptional argumentnout ofsimulate(). As an example, setnout=2 toenable reporting of total shoot length (TSL) and internal concentration(C_int). Setnout=0 to disable additional outputs. The default isnout=1.

The available output levels are as follows:

• nout >= 1:TSL, total shoot length (cm)

• nout >= 2:C_int, internal concentration (ug L-1)

• nout >= 3:f_photo, photosynthesis dependency function (-)

• nout >= 4:C_int_unb, unbound internal concentration (ug L-1)

• nout >= 5:C_ext, external concentration (ug L-1)

• nout >= 6:dBM, biomass derivative (g dw d-1)

• nout >= 7:dM_int, mass of toxicant in plants derivative (ng d-1)

Solver settings

The arguments to ODE solverdeSolve::ode() control how model equationsare numerically integrated. The settings influence stability of the numericalintegration scheme as well as numerical precision of model outputs. Generally, thedefault settings as defined bydeSolve are used, but alldeSolve settingscan be modified incvasi workflows by the user, if needed. Please referto e.g.simulate() on how to pass arguments todeSolve incvasiworkflows.

Some default settings ofdeSolve were adapted for this model by expertjudgement to enable precise, but also computationally efficient, simulationsfor most model parameters. These settings can be modified by the user,if needed:

• hmax = 0.1
  Maximum step length in time suitable for most simulations.

Effects

Supported effect endpoints includeBM (biomass) andr (averagegrowth rate during simulation). The effect on biomass is calculated fromthe last state of a simulation. Be aware that endpointr is incompatiblewith biomass transfers.

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

References

Witt et al., submitted

Klein J., Cedergreen N., Heine S., Reichenberger S., Rendal C.,Schmitt W., Hommen U., 2021:Refined description of the Lemna TKTD growth modelbased on Schmitt et al. (2013) - equation system and default parameters.Report of the working groupLemna of the SETAC Europe Interest Group EffectModeling. Version 1.1, uploaded on 09 May 2022.https://www.setac.org/group/effect-modeling.html

See Also

Macrophyte-models,Lemna-models,Transferable,Scenarios

Other macrophyte models:Lemna_SETAC(),Lemna_Schmitt(),Macrophyte-models

Magma scenario class

Description

This entry documents the class definition used forMagma-type scenarios.For details regarding the model, please refer to theMagma model manual.

Slots

growth_model

character, selects the growth model, such asexponentialorlogistic growth.

See Also

Macrophyte-models

Effect scenario classes

Description

TheEffectScenario class is the base for all of the basic scenariotypes and models. It contains slots for data and settings that arerequired by most models such as a vector of model parameters and a vectorof initial states. For each particular model, the class's slots arefilled with certain default or fixed values. Some models derive from thisclass and add slots to store additional data.

Details

Certain behaviors that are required to model complex processes cannot berepresented by a single EffectScenario. As an example, the parameters of a scenarioare generally fixed during the simulated time period. In order to represent achange in parameter values, the original scenario wouldneed to split into two scenariosA andB which differ by parameter valuesand simulated time period. By combining these scenarios to ascenario sequence,the sequence would be treated as a single, complex scenario. Seesequence() for more information.

Parameters

Most parameters are represented by numerical types but other typesare possible depending on model. Please refer to the model descriptionwhich parameters are required and in which unit. Some or all parameters maybe required to start a simulation. If required parameters are missing,simulation will fail with an error message.

Initial state

Theinitial state represents the starting values of state variables whenstarting a simulation. A scenario's default initial state may be insufficientto get sensible results. It is advisable to set an initial state explicitlywhen creating a new scenario, seeset_init().

In theory, a scenario's state variables can be renamed by modifying the namesof the initial state vector. However, this is stronglydiscouraged as this will affect other routines such aseffect() andepx()and may render results useless.

Exposure

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

Exposure time-series are generally represented by adata.frame containing twocolumns. The first column representing time, the second representing theexposure level. The ordering of columns is mandatory. The column namesare essentially irrelevant but sensible names may help documenting thescenario and its data. The rows must be ordered chronologically. A time-seriescan consist of only a single row; in this case it will represent constantexposure. Exposure time-series are set to a scenario usingset_exposure().

Handling time-series is a costly task for the ODE solver due to consistencychecks and interpolation between time steps. How the solver interpolatesthe time-series can be controlled by certain arguments to functionssuch assimulate() andeffect(). Please refer tosimulate() for a briefoverview anddeSolve::forcings for a detailed description.

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

Environmental forcings

Forcings generally refer to model parameters that change over time as partof an external function such as environmental temperature and exposure levels.Due to the importance of exposure in regulatory assessments, this R packageexplicitly distinguishes between environmental forcings and exposure. However,the same restrictions and features apply to both of them.

Forcing time-series are handled the same way as exposure time-series, i.e.they are represented by adata.frame containing two columns. The first columnrepresenting time, the second representing the parameter that is a function oftime. The ordering of columns is mandatory. The rows must be orderedchronologically. Forcings time-series are set usingset_forcings().Please refer to theExposure section for more information on how time-seriesare handled.

Output times

A scenario's simulated time period is defined by its minimum and maximum outputtime. Simulation results will only be returned for the defined output timeseven though the ODE solver may use smaller time steps between output times.Output times can be explicitly set usingset_times(). The number anddistance of output times may have influence on the precision of simulationresults and numerical stability, cf.simulate().

Be aware thatset_exposure() will overwrite previously defined output timesif not requested otherwise.

Effects

Generally, all state variables can be used as effect endpoints but models mayprovide additional endpoints. Useset_endpoints() to enable or disableendpoints for a scenario.

Some scenarios or models require control runs to calculate effects underexposure. Generally, control simulations will run automaticallywhere needed.

Moving exposure windows

The time frame relevant for effects may be much shorter than the assessedexposure time-series for certain organisms. This fact can be representedby moving exposure windows which divide a long time period in a number ofconsecutive windows of the same length. Each window is simulated individually and effects arecalculated. By default, methods such aseffect() will only return themaximum effect of all considered windows but detailed results can be presentedon demand.

To use moving exposure windows, the exposure time-series must be regular,i.e. must have an equidistant step length in time. The length of the windowis defined as the number of time steps of the exposure time-series. As anexample, assume the time-series has daily granularity and a moving windowof seven days length is required. In this case, the moving window must havea length of seven (7) time steps. If the exposure time-series had hourly granularity,the same window would need to have a length of 168 (=7*24) time steps. Pleaserefer toset_window() for details.

Slots

name

character, unique model name

tag

character, an optional identifier

param

list of parameter key-value pairs

param.bounds

namedlist of parameter boundaries

param.req

character vector of required parameters

forcings

list ofdata.frames representing forcing time-series

forcings.req

character vector or required model forcings data, e.g. temperature

init

list of initial model states

times

numeric vector of output times, beginning and end also definethe simulated period

endpoints

character vector of endpoints to calculate results for

exposure

data.frame with two columns representing an exposure time-series

control

list of named numerical vectors, contains the control valuesfor all relevant moving windows

control.req

logical, ifTRUE then control values are required tocalculate effects

window.length

numeric, maximum length of the simulated period, ifwindow.length is shorter than the exposure pattern, then all possibleexposure sub-patterns are evaluated for effect calculation. This is alsoreferred to as a moving window approach.

window.interval

numeric, interval determining distance between movingwindows during effect calculation. First window starts at first time pointin exposure pattern.

See Also

Other scenario-related:Transferable

Biomass transfer class

Description

By inheriting from classTransferable, a scenario's behavior can beextended to support transfer and reset of biomass at dedicated points duringsimulation.

Slots

transfer.times

numeric, vector of custom time points at which transfers occur,e.g.c(2,5,14)

transfer.interval

numeric, length of regular interval until biomass transfer to newmedium, regular transfers always occur relative to time point zero

transfer.biomass

numeric, amount of biomass transferred to new medium

transfer.comp.biomass

character state variable which describesbiomass

transfer.comp.scaled

character vector of state variable which willbe scaled 1:1 when biomass is modified, e.g. internal toxicant mass

Biomass transfer

Models supporting biomass transfer can be instructed to move a fixed amountof biomass to a new medium after a period of time. This feature replicatesa procedure occurring in e.g.Lemna effect studies and may be necessary torecreate study results.

The biomass transfer feature assumes that always a fixed amount ofbiomass is transferred. Transfers can occur at any fixed point in time orin regular intervals. During a transfer, the biomass is reset to thetransferred amount and additional compartments can be scaled 1:1 accordingly,to e.g. reflect the change in internal toxicant mass when biomass is modified.Transfer settings can be modified usingset_transfer().

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

See Also

set_transfer()

Other scenario-related:Scenarios

Examples

# Simulation without biomass transfersmetsulfuron %>%  set_noexposure() %>%  set_notransfer() %>%  simulate()# With biomass transfer every 7 days, biomass is reset to 50 *g/m²* on transfermetsulfuron %>%  set_noexposure() %>%  set_transfer(interval=7, biomass=50) %>%  simulate()

A DEB abj scenario of Americamysis bahia

Description

Species parameters were collected from the AddMyPet database entry onAmericamysis bahia (Opossum shrimp). The exposure series consists of aconstant exposure resulting in medium effects on length and reproduction.

Usage

americamysis

Format

An object of classDebAbj of length 1.

Source

https://www.bio.vu.nl/thb/deb/deblab/add_my_pet/entries_web/Americamysis_bahia/Americamysis_bahia_res.html

See Also

DEB_abj()

Batch simulation of multiple exposure levels

Description

Usage

batch(  scenario,  exposure,  id_col = "trial",  format = c("long", "wide"),  times_from = c("scenario", "exposure"),  select = NULL)

Arguments

Details

A convenience function to simulate a single base scenario with one or moreexposure levels. The functions aims at reproducing the setup and result formatof common effect studies.

Simulating ascenario is generally limited to assessing a single exposureseries. However, laboratory experiments commonly examine the effects ofmultiple exposure levels on a biological system.Abatch simulation approach involves running multiple simulations withvarying exposure ortreatment conditions. To illustrate: if the objective isto examine the impact of a chemical on cell growth, multiple scenarios needto be simulated to reproduce the cell growth dynamics under varyingconcentrations of the assessed chemical. Each simulation run will represent aspecific exposure level, ranging from low to high concentrations of thechemical.

To simulate the conditions of such a laboratory experiment, the scenarios andexposure levels can either be created and simulated individually, or thebatch() function can be used for ease of use.

Exposure series

The set of exposure levels can be represented by one of the following types:

• A (named) list: Each element represents an exposure level or exposureseries. An exposure level can be represented by a constant numeric, adata.frame with two columns, or an ExposureSeries object. The names ofthe list elements specify the study ID.

• Or alternatively, adata.frame with three columns: One column for time,one for the exposure level, and one character column to specify thestudy IDs.

Each exposure level will be simulated using the base scenario. If the exposurelevels are provided as a named list, the names will also appear in the returnvalue ofsimulate(). This behavior can be used, for example, to define uniquestudy IDs for particular exposure levels.

Exposure IDs

The list of exposure levels can be supplied as a named list. The nameswill be used as unique (study) IDs, so that the simulation results belongingto any exposure level can be identified in the output.If no IDs are defined by the user, generic IDs of the form'trial{n}' willbe assigned, with{n} being replaced by consecutive integers starting at one.

If the batch is passed on tosimulate()', the IDs will be contained in itsreturn value, e.g. as a dedicated column (long format) or as part of thecolumn names (wide format).

Output format

The return value ofsimulate() is by default in long format, i.e. it willcontain one row for each output time and exposure level. It is possible topivot the tabular data to wide format, by setting the argumentformat = 'wide'.

In wide format, the output columns of each exposure level are pastednext to each other. If more than one column is pivoted per exposure level,then the exposure or study ID is added as a suffix to column names.If the output per exposure level contains only a single column (besides timeand the exposure ID itself), then original column name is dropped and onlyexposure IDs are used. See the examples section for reference.

Select output columns

Often, only a single output column is of interest in batch simulations,such as the number of surviving individuals. To ease the interpretation andhandling of the output of batch simulations, the columns contained in theoutput of each simulated exposure level can be filtered. One or more columnscan be selected. By default, no filtering of output columns is conducted.

As an example, to create an overview of survival probabilities (S) in theGUTS-RED-IT example scenariominnow_it:

minnow_it %>%  batch(exposure=list(0, 5, 10), select="S", format="wide") %>%  simulate()

Value

a simulation batch object

Examples

# Simulate a batch experiment with three constant exposure levels of# 0.0, 2.0, and 5.0 µmol/Lsimulate(batch(minnow_it, list(0, 2, 5)))# Alternatively, in tidyr style syntaxtrials_list1 <- list(0, 2, 5)minnow_it %>%  batch(trials_list1) %>%  simulate()# Assign unique IDs to each exposure leveltrials_list2 <- list(Control=0, TrialA=2, TrialB=5)minnow_it %>%  batch(trials_list2) %>%  simulate()# Alternatively, define multiple exposure levels in a single data.frametrials_table <- data.frame(time=c(0, 0, 0),                           conc=c(0, 2, 5),                           trial=c("Control", "TrialA", "TrialB"))minnow_it %>%  batch(trials_table) %>%  simulate()# Limit simulation output to column 'S' (survival probability)minnow_it %>%  batch(trials_list2, select="S") %>%  simulate()# Return data in wide-format, unique IDs will be used as column namesminnow_it %>%  batch(trials_list2, select="S", format="wide") %>%  simulate()

Cache control simulations

Description

Usage

cache_controls(x, ...)

Arguments

Details

Handling of cached control simulations has been modified and is solelymanaged by package functions.cache_controls() is no longer needed andwill raise an error if called.

Value

nothing

Fit model parameters to experimental data

Description

The functioncalibrate() performs the calibration (fitting) of modelparameters to observed data. The data can originate from one or more experiments ortrials. Experimental conditions, such as model parameters and exposurelevel, can differ between trials; fitting can be performed on all datasetsat the same time.

Usage

## S4 method for signature 'EffectScenario'calibrate(x, output, data, ...)## S4 method for signature 'list'calibrate(  x,  par,  output,  err_fun = "sse",  log_scale = FALSE,  verbose = TRUE,  ode_method = NULL,  ...)

Arguments

Details

Fitting of model parameters can be performed in two ways:

1. A singlescenario is fitted to a single dataset.The dataset must represent a time-series of an output variable of themodel, e.g. observed biomass over time (effect data). The dataset can representresults of one or more experimental replicates under identical conditions.

2. One or more datasets of observed data are fitted each to a scenario whichdescribes the experimental conditions during observation, such as exposurelevel and environmental properties. Each combination of dataset and scenariois represented by acalibration set. During fitting,allcalibration sets are evaluated and a total error term is calculatedover all observed and predicted values.

Observed data

Experimental, or effect, data must be supplied as adata.frame in long formatwith at least two columns: the first column containsnumeric timestamps andthe remaining columns must contain the observed quantity. The observed quantitiymust match in unit and meaning with the model output defined by argumentoutput.

As an example, the simulation result ofLemna_Schmitt model contains theoutput columnbiomass (BM), amongst others. To fit model parameters of saidLemna_Schmitt scenario based on observed biomass, the observed data mustrepresent biomass as well. 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

The error function quantifies the deviations between simulated and observed data.The decision for an error function can have influence on the result of thefitting procedure. Two error functions are pre-defined by the package andcan be selected by the user, but custom error functions can be used as well.

Available pre-defined error functions:

• "sse": Sum of squared errors

By default, the sum of squared errors is used as the error function whichgets minimized during fitting. A custom error function must accept four vectorizedarguments and return a numeric of length one, i.e. the total error value.The arguments to the error function will all have the same length and aredefined as follows:

• First argument: all observed data points

• Second argument: all simulated data points

• Third argument: optional weights for each data point

• Fourth argument: a list of optional caliset tags

You can choose to ignore certain arguments, such as weights and tags, in yourcustom error function. An example of a custom error function which returnsthe sum of absolute errors looks as follow:

my_absolute_error <- function(observed, predicted, weights, tags) {  sum(abs(observed - predicted))}

As tags are optional, the fourth argument may be a list containingNULL values.The fourth argument can be used to pass additional information to the errorfunction: For example, the tag may identify the study from where the dataoriginates from and the error function could group and evaluate the dataaccordingly.

Value

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

Methods (by class)

• calibrate(EffectScenario): Fit singlescenario to a (tox_data) dataset

Examples

# Create an artificial data set of observed frond numbers.# It assumes exponential growth with an effective growth rate of 0.38trial <- data.frame(time=0:14,                   fronds=12 * exp(0:14 * 0.38))plot(trial)# Create a Lemna scenario that represents unrestricted, exponential growth.scenario <- Lemna_Schmitt() %>%  set_param(c(k_phot_max=1, k_resp=0, EC50=1, b=1, P_up=1)) %>%  set_init(c(BM=12)) %>%  set_noexposure()# Fit scenario parameter 'k_phot_max' to observed frond numbers:fit <- calibrate(  scenario,  par="k_phot_max",  data=trial,  output="BM")# The fitted value of 'k_phot_max' matches the effective growth rate which# was used to create the artificial data set:fit$par

Parameter confidence intervals from fit

Description

Calculates parameter confidence intervals for a fit returned bycalibrate().The fit must provide a validHessian matrix.

Usage

ci_from_hessian(fit, dof, level = 0.95)

Arguments

Value

name list of numeric vectors of length two, the elementsrepresenting the lower and upper confidence limit, respectively.

Diagnostics of solvers

Description

Prints several diagnostics of the simulation to the console, e.g. number ofsteps taken, the last step size, etc. The information is provided bydeSolve::diagnostics().

Usage

diagnostics(obj, ...)## Default S3 method:diagnostics(obj, ...)## S3 method for class 'cvasi_simulate'diagnostics(obj, ...)

Arguments

See Also

deSolve::diagnostics()

A DEBtox scenario of Daphnia magna

Description

Species and substance parameters were collected from test runs of theoriginalDEBtox Daphnia model.

Usage

dmagna

Format

An object of classDebTox of length 1.

See Also

DEBtox()

Calculate a dose response curve

Description

Returns adata.frame with points on the dose response curve for the giveneffect scenario.

Usage

dose_response(  scenario,  range = c(1, 99),  n = 20,  strategy = c("exponential", "decadic", "vanilla"),  verbose = FALSE,  ...)

Arguments

Details

Derives a dose response curve from ascenario. The result willcover the requested range of effect levels. The tested multiplication factorscan be chosen by different strategies, i.e. avanilla approach using afixed set of factors, ordecadic andexponential approachesemploying logarithmic and exponential factor scaling, respectively.

Value

data.frame with two columns, i.e.mf andeffect

Examples

# basic dose response curveminnow_sd %>% dose_response()# modify the minimum number of points on the curveminnow_sd %>% dose_response(n=10)# select a subset of the effect rangeminnow_sd %>% dose_response(range=c(10,20))# use an alternative strategy for the selection of multiplication factorsminnow_sd %>% dose_response(strategy="decadic")# provide additional output how multiplication factors were selectedminnow_sd %>% dose_response(verbose=TRUE)

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 modelendpoints, 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

Details

By default, only the maximum effect in all moving exposure windows willbe returned. If argumentmax_only=FALSE is set, the returned table willbe converted to long-format and will contain effect levels for eachassessed exposure window.

Calculation

Effects are calculated similarly torelative errors, i.e. the differencebetween control and treatment scenarios is divided by the absolute valueof the control. Effects are usually in the interval⁠[0,1]⁠, but valueslarger than one or smaller than zero can occur. As a special case, if theendpoint 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 of1.0 and the treatment scenario achieves a biomass of 0.9, the effect willbe 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 dropsbelow 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 theeffect will be negative.

Output formatting

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

Computational efficiency

Calculations can be sped up by providing adata.frame of pre-calculatedcontrol scenarios for each assessed time window. As control scenarios areby definition independent of any exposure multiplication factor, they canbe reused for repeated calculations, e.g. to derive effect profiles ordose-response relationships.

Value

atibble, by default containing scenarios, effect levels, and theexposure window where the maximum effect level occurred. The number of columnsdepends on the enabled effect endpoints and function arguments.

By default, the first column, namedscenarios, contains the original scenarioobjects that were the basis of the calculation. For each effect endpoint, itwill be followed by one column with the maximum effect level and two columnscontaining start and end time of the associated exposure window. If exposurewindows are disabled, the columns will just contain the start and end time ofthe simulation. The effect level column will have the name of the effectendpoint, start and end time will additionally have the suffixes.dat.startand.dat.end, respectively.

Methods (by class)

• effect(EffectScenario): Default for all genericscenarios

• effect(ScenarioSequence): For scenariosequences

Effect profiles (EPx values)

Description

Derives one or more EPx/LPx values for the supplied effect scenarios, i.e. itcalculates the multiplication factors of an exposure profile that causex% 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

Details

To estimate EPx values, abinary search on multiplication factors is conducted.The algorithm can achieve arbitrary precision in terms of effects. Thesame approach is implemented in themorse package in theMFx() function.Convergence is often achieved in less than 10 iterations per effect level andendpoint.

Internally, a knowledge base of all tried factors and resulting effect levels iskept to speed up convergence if more than one endpoint or effect level wasrequested. The algorithm will automatically sweep the range of multiplicationfactors as needed but hard cutoff values are implemented to avoid infinite loops;the algorithm will halt with an error message if tried factors aresmaller than1e-30 or greater than1e30.

Numerical precision

The precision of reportedEPx values is controlled by the argumenteffect_tolerance and is given as the upper absolute error threshold ofeffects that is deemed acceptable. The default value of0.001 ensures thata derivedEPx will result in an effect of x% ± 0.1. Decreasing theeffect_tolerance will result in additional model iterations and longerruntime. Setting an extremely small tolerance value may lead to a breakdownof the algorithm due to the occurrence of extremely small, quasi-randomnumerical errors in simulation results.

Value

The originaltibble 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 columnscenario will containthe suppliedEffectScenario objects.

Examples

minnow_sd %>% epx()minnow_sd %>% epx(level=c(10,23,42))# displays infos about tested multiplication factorsminnow_sd %>% epx(verbose=TRUE)# return results as a table in wide formatminnow_sd %>% epx(long_format=TRUE)

Calculate EPx values for a series of moving time window

Description

Callsepx() to calculate the EPx value (i.e. the multiplication factors ofan exposure profile that cause x% of effect) for moving windows with lengthwindow_length that move timesteps defined bywindow_interval.

Usage

epx_mtw(  x,  level = c(10, 50),  factor_cutoff = 1000,  window_length = 7,  window_interval = 1,  ...)

Arguments

Value

a tibble with five columns

• window.start

• window.end

• endpoint

• level

• EPx

Examples

metsulfuron %>%  set_window(length=7, interval=1) %>%  epx_mtw()

Explore parameter space

Description

The function is aimed at getting an idea of how the parameter spaceof a model behaves, so that parameter identifiability problems and correlationsbetween parameters can be explored. Therefore, the function samples a largenumber of parameter sets by randomly drawing from each parameter's 95%confidence interval (generated bylik_profile()). It thenchecks how many of the parameter sets are within acceptable limits by comparingthe likelihood ratio of a parameter set vs. the original parameter set againsta chi-square distribution as degrees of freedom (df) the total number of profileparameters (outer rim) or one df (inner rim). If needed, the function resamplesuntil at leastnr_accept parameters sets are within the inner rim

Usage

explore_space(  x,  par,  res,  output,  data,  sample_size = 1000,  max_iter = 30,  nr_accept = 100,  sample_factor = 1.2,  individual = FALSE,  log_scale = FALSE,  data_type = c("continuous", "count"),  max_runs = deprecated(),  ...)

Arguments

Value

a list containing a plot to explore the parameter space, and thedata.framesupporting it

See Also

plot.param_space

Examples

library(dplyr)# Example with Lemna model - physiological params# Before applying the function, a model needs to be calibrated and its parameters profiled# Inputs for likelihood profiling# observations - control runobs <- schmitt2013 %>%  filter(trial == "T0")# parameters after calibrationparams <- c(  k_phot_max = 5.663571,  k_resp = 1.938689,  Topt = 26.7)# set parameter boundaries (if different from defaults)bounds <- list(  k_resp = list(0, 10),  k_phot_max = list(0, 30),  Topt = list(20, 30))# update metsulfuronmyscenario <- metsulfuron %>%  set_init(c(BM = 1.2, E = 1, M_int = 0)) %>%  set_param(list(    k_0 = 5E-5,    a_k = 0.25,    BM50 = 17600,    mass_per_frond = 0.1  )) %>%  set_noexposure() %>%  set_param(params) %>%  set_bounds(bounds)# Likelihood profilingres <- lik_profile(  x = myscenario,  data = obs,  output = "FrondNo",  par = params,  refit = FALSE,  type = "fine",  method = "Brent")# plotplot(res)# parameter space explorerset.seed(1) # for reproducibilityres_space <- explore_space(  x = myscenario,  data = obs,  par = params,  res = res,  output = "FrondNo",  sample_size = 1000,  max_iter = 20,  nr_accept = 100)plot(res_space)

Fit growth parameters

Description

Usage

fit_growth(x, data, ...)## S4 method for signature 'ANY,ANY'fit_growth(x, data, ...)## S4 method for signature 'LemnaSetac,missing'fit_growth(x, data, par, log_scale = TRUE, verbose = FALSE, ...)## S4 method for signature 'LemnaSchmitt,missing'fit_growth(x, data, par, log_scale = TRUE, verbose = FALSE, ...)## S4 method for signature 'Magma,missing'fit_growth(x, data, par, log_scale = TRUE, verbose = FALSE, ...)

Arguments

Value

a list

Methods (by class)

• fit_growth(x = ANY, data = ANY): Default handler

• fit_growth(x = LemnaSetac, data = missing): Fit growth parameters ofLemna_SETAC scenarios

• fit_growth(x = LemnaSchmitt, data = missing): Fit growth parameters ofLemna_Schmitt scenarios

• fit_growth(x = Magma, data = missing): Fit growth parameters ofMagma scenarios

Examples

# Use experimental data from control trial ('T0') to fit growth ratectrl <- schmitt2013[schmitt2013$trial == "T0" ,]# Set up a scenario, provide dummy parameter values where necessarysc <- Lemna_Schmitt() %>%  set_init(c(BM=0.0012)) %>%  set_param(c(EC50=1, b=1, P_up=1))# Run fitting routinefit_growth(sc, data=ctrl, verbose=TRUE)

Fit TK/TD parameters

Description

Usage

fit_tktd(x, data, ...)## S4 method for signature 'LemnaSetac,missing'fit_tktd(x, data, par, log_scale = TRUE, verbose = FALSE, ...)## S4 method for signature 'LemnaSchmitt,missing'fit_tktd(x, data, par, log_scale = TRUE, verbose = FALSE, ...)## S4 method for signature 'Magma,missing'fit_tktd(x, data, par, log_scale = TRUE, verbose = FALSE, ...)

Arguments

Details

Data

The function can be used in three basic ways: Fit parameters of

1. a singlescenario to a data set

2. a list ofcalisets

3. a list ofcalisets in a chain offit functions

For option 1), scenario and data are supplied separately. In this case,supported types of argumentdata aredata.frames andtox_data objects.Anydata.frame must have a format that is compatible with thetox_data()function.

In option 2), all conditions are fully described by a list of calibration sets.The user is responsible to set up allcaliset objects to their needs.

Option3) is for convenience purposes and allows the chaining of fit functions.The latter alternative accepts the return value of e.g.fit_growth()as argumentx and the fitted parameter values are applied to allcalibration sets in argumentdata.

Value

a list

Methods (by class)

• fit_tktd(x = LemnaSetac, data = missing): Fit TK/TD parameters ofLemna_SETAC scenarios

• fit_tktd(x = LemnaSchmitt, data = missing): Fit TK/TD parameters ofLemna_Schmitt scenarios

• fit_tktd(x = Magma, data = missing): Fit TK/TD parameters ofMagma scenarios

Examples

# Use experimental data from control trial ('T0') to fit growth ratectrl <- schmitt2013[schmitt2013$trial == "T0" ,]# Set up a scenario, provide dummy parameter values where necessarysc <- Lemna_Schmitt() %>%  set_init(c(BM=0.0012)) %>%  set_param(c(EC50=1, b=1, P_up=1))# Run fitting routinefit_growth(sc, data=ctrl, verbose=TRUE)# Use fitted growth parameter to adapt scenariosc2 <- sc %>% set_param(c(k_phot_max=0.43925))# Use experimental ecotox data for various concentrations of 'metsulfuron-methyl'trials <- schmitt2013[schmitt2013$trial != "T0" ,]# Fit remaining TK/TD parametersfit_tktd(sc2, data=trials, verbose=TRUE)

A Lemna_SETAC scenario with variable environment

Description

A mechanistic combined toxicokinetic-toxicodynamic (TK/TD) and growthmodel for the aquatic macrophytes Lemna spp. as published byKleinet al. (2021).

Usage

focusd1

Format

An object of classLemnaSetac of length 1.

Details

The scenario will simulate a period of 365 days, a startpopulation of 80 g/m² dry weight, variable environmental conditions, and acomplex, time-varying exposure pattern.

The scenario setup was published by Hommenet al. (2015). Exposure patternand substance specific parameters are of exemplary characterand represent the herbicidemetsulfuron-methyl. The parameters werederived by Schmitt et al. (2013) based on literaturedata.

References

Hommen U., Schmitt W., Heine S., Brock Theo CM., Duquesne S., Manson P., Meregalli G.,Ochoa-Acuña H., van Vliet P., Arts G., 2015: How TK-TD and Population Models forAquatic Macrophytes Could Support the Risk Assessment for Plant ProtectionProducts. Integr Environ Assess Manag 12(1), pp. 82-95.doi:10.1002/ieam.1715

Klein J., Cedergreen N., Heine S., Reichenberger S., Rendal C.,Schmitt W., Hommen U., 2021: Refined description of theLemna TKTD growth modelbased onSchmitt et al. (2013) - equation system and default parameters.Report of the working groupLemna of the SETAC Europe Interest Group EffectModeling. Version 1.1, uploaded on 09 May 2022.https://www.setac.org/group/effect-modeling.html

Schmitt W., Bruns E., Dollinger M., Sowig P., 2013: Mechanistic TK/TD-modelsimulating the effect of growth inhibitors onLemna populations. Ecol Model255, pp. 1-10.doi:10.1016/j.ecolmodel.2013.01.017

See Also

Lemna-models

Examples

# Simulate the example scenariofocusd1 %>% simulate()

Generic to calculate effects for a particular scenario

Description

Generic to calculate effects for a particular scenario

Usage

fx(scenario, ...)## S4 method for signature 'ANY'fx(scenario, ...)## S4 method for signature 'ScenarioSequence'fx(scenario, ...)## S4 method for signature 'Lemna'fx(scenario, ...)## S4 method for signature 'Magma'fx(scenario, ...)## S4 method for signature 'Algae'fx(scenario, ...)## S4 method for signature 'GutsSd'fx(scenario, ...)## S4 method for signature 'GutsIt'fx(scenario, ...)## S4 method for signature 'GutsRedSd'fx(scenario, ...)## S4 method for signature 'GutsRedIt'fx(scenario, ...)

Arguments

Value

numeric named vector

Methods (by class)

• fx(ANY): Use state variables at end of simulation

• fx(ScenarioSequence): Wrapper forsequences

• fx(Lemna): Effect at end of simulation ofLemna-models

• fx(Magma): Effect at end of simulation ofMagma scenarios

• fx(Algae): Effect at end of simulation ofAlgae-models

• fx(GutsSd): Calculates lethality ofGUTS-SD scenarios

• fx(GutsIt): Calculates lethality ofGUTS-IT scenarios

• fx(GutsRedSd): Calculates lethality ofGUTS-RED-SD scenarios

• fx(GutsRedIt): Calculates lethality ofGUTS-RED-IT scenarios

Get model name

Description

Returns the unique model name that is associated with a scenario, e.g.GUTS-RED-IT. The function supports vectorized arguments.

Usage

get_model(x)

Arguments

Value

vector ofcharacter

Examples

# returns `GUTS-RED-IT`get_model(minnow_it)

Get scenario parameters

Description

For scenariosequences, only the parameters of the first scenarioin the sequence is returned. To access parameters of a specific scenario inthe sequence, useget_param() on the individual scenario object.

Usage

get_param(x)## S4 method for signature 'list'get_param(x)## S4 method for signature 'EffectScenario'get_param(x)## S4 method for signature 'ScenarioSequence'get_param(x)## S4 method for signature 'ParameterSet'get_param(x)

Arguments

Value

(list of) list(s) with key-value pairs

Methods (by class)

• get_param(list): Returns a list of parameter lists (if applicable)

• get_param(EffectScenario): Returns a list parameters for a singlescenario

• get_param(ScenarioSequence): Returns a list of parameter lists, one for each scenario in the sequence

• get_param(ParameterSet): Returns a list of parameters for a singleparameter_set

See Also

set_param()

Examples

minnow_it %>% get_param()

Get scenario tag

Description

Returns the user-defined, custom tag of a scenario, if available.Tags can be helpful to quickly distinguish scenarios by e.g. a user-specifiedstring. The function supports vectorized inputs. If morethan one scenario is supplied in argumentx, then a list of tags isreturned.

Usage

get_tag(x)## S4 method for signature 'list'get_tag(x)## S4 method for signature 'EffectScenario'get_tag(x)## S4 method for signature 'ScenarioSequence'get_tag(x)## S4 method for signature 'ParameterSet'get_tag(x)

Arguments

Value

(list of) tag(s), returnsNA if no tag was set

Methods (by class)

• get_tag(list): Returns a list of tags (if applicable)

• get_tag(EffectScenario): Returns the tag of a singlescenario

• get_tag(ScenarioSequence): Returns a list of tags, one for each scenario in the sequence

• get_tag(ParameterSet): Returns the tag of a singleparameter_set

See Also

set_tag()

Examples

# returns `fathead minnow`get_tag(minnow_it)# update or set a tagmyscenario <- GUTS_RED_IT() %>% set_tag("My Custom Tag")# returns `My Custom Tag`get_tag(myscenario)

Get output times

Description

Get output times

Usage

get_times(x)

Arguments

Value

(list of) times vector

See Also

set_times()

Examples

# Create a scenariomyscenario <- GUTS_RED_IT() %>% set_times(0:5)# Returns the defined output timesget_times(myscenario)

Importmorse model parameters

Description

Loads GUTS model parameters which were fitted by the morse package.

Usage

import_morse(  fit,  find_sd = TRUE,  find_it = TRUE,  reset_hb = FALSE,  params = c("estim", "all"),  mcmc_size,  find.SD = deprecated(),  find.IT = deprecated(),  reset.hb = deprecated(),  mcmc.size = deprecated(),  file = deprecated())morse(...)

Arguments

Value

list ofparameter_set objects

Functions

• morse(): deprecated alias

Examples

# import all parameter fitstry(import_morse("path/to/morse_fit.RData"))# import parameters for a specific modeltry(import_morse("path/to/morse_fit.RData", find_it=TRUE, find_sd=FALSE))# modify model objectstry(models %>% set_param(import_morse("path/to/morse_fit.RData")))

SWASH project exposure profile import

Description

Read all TOXSWA files within a SWASH project directory.

Usage

import_swash(swash_dir, ...)

Arguments

Value

a list of imported exposure series, seeimport_toxswa() for details

ImportTOXSWA exposure series

Description

Read one or moreTOXSWA exposure series fromTOXSWA's.out files. By default, theconcentration dissolved in water (ConLiqWatLay) at the end of the simulated waterbody(i.e. at the maximum of thex dimension) is returned. The unit of the timescale as well as of the imported model output variable can be scaled as needed.

Usage

import_toxswa(  files,  alias = NA,  output_var = "ConLiqWatLay",  output_unit = "ug/L",  time_unit = "days",  substance = NULL,  split = TRUE)

Arguments

Details

The numerical time scale is shifted to always start at time zero (0.0).Numerical columns of the returneddata.frame objects will be of typeunits::units. Please be aware that the use ofunits objects may not besupported by all functions in this package. However,set_times() andset_exposure() can handleunits objects safely.

Incomplete list of alternativeTOXSWA v5.5.3 output variables:

• ConLiqWatLay: Concentration dissolved in water (g/m3)

• ConLiqSed: Concentration in pore water sediment (g/m3)

• ConSysWatLay: Total concentration in water (g/m3)

• CntSorSusSol: Content sorbed to suspended solids (g/kg)

• CntSorSed: Content sorbed to sediment (g/kg)

Value

list ofdata.frame objects with exposure series. Eachdata.frame has atleast three columns:

• time: numerical time scale, always starts at zero

• timestamp: time as datetime objects such asPOSIXct

• one or more additional columns for each imported substance

Test if argument is a LemnaThreshold scenario

Description

Usage

is_LemnaThreshold(x)

Arguments

Value

vector oflogical values

See Also

is_lemna()

Test if argument is a DEB scenario

Description

Test if argument is a DEB scenario

Usage

is_deb(x)is_DEB(x)

Arguments

Value

vector oflogical values

Functions

• is_DEB(): Deprecated alias.

Test if argument is a GUTS scenario

Description

Test if argument is a GUTS scenario

Usage

is_guts(x)is_GUTS(x)is_guts_it(x)is_GUTS_IT(x)is_guts_sd(x)is_GUTS_SD(x)

Arguments

Value

vector oflogical values

Functions

• is_GUTS(): Deprecated alias.

• is_guts_it(): Test if argument is a GUTS-IT scenario

• is_GUTS_IT(): Deprecated alias.

• is_guts_sd(): Test if argument is a GUTS-SD scenario

• is_GUTS_SD(): Deprecated alias.

Examples

# returns `TRUE`is_guts(minnow_it)is_guts(GUTS_RED_IT())# returns `c(TRUE,TRUE,TRUE)`is_guts(c(minnow_it, minnow_it, minnow_it))# returns `FALSE`is_guts_sd(minnow_it)

Test if argument is a Lemna scenario

Description

Test if argument is a Lemna scenario

Usage

is_lemna(x)is_Lemna(x)

Arguments

Value

vector of logical values

Functions

• is_Lemna(): Deprecated alias.

Test if argument is an effect scenario

Description

Supports vectorized arguments.

Usage

is_scenario(x)

Arguments

Value

vector oflogical values

Examples

# returns `TRUE`is_scenario(minnow_it)# returns `FALSE`is_scenario(list())

Likelihood profiling

Description

The aim of the function is two-fold: 1) estimate a 95% confidencearound each parameter of a calibrated model, and 2) see if perhaps a local minimum was found ratherthan a global minimum. To achieve this, the likelihood profiling goes throughevery parameter one by one. For each parameter,the model is sequentially refit with the parameter value set toincreasingly lower and higher values, and the likelihood of the model given thedata calculated (usinglog_lik()). The likelihood is then comparedto the likelihood of the original model (using a likelihood ratio). This leadsto the development of a likelihood profile, from which a plot a 95%confidence interval for the parameter is derived.

The idea of the function is a variable stepwise algorithm:When the likelihood ratio changes very little (less thanl_crit_min), the stepsize isincreased (up to a maximum, specified byf_step_max). When the lik.ratio changes too much (more thanl_crit_max), the algorithm tries againwith a smaller stepsize (also bound to a minimum:f_step_min). Note thatthe stepsize is used as a fraction of the parameter value that is tried.To prevent very small stepsizes when the value goes towards zero (as canbe the case for effect thresholds), an absolute minimumstepsize (f_step_abs), which is specified as a fraction of the bestparameter value (Xhat) (unless it is zero, then the algorithm takessomething small).

Note that the likelihood of the model given the data can be calculated acrossall datasets provided in the calibration setx, or calculated separately foreach individual dataset before being combined into one likelihood (by adjustingthe optional parameterindividual). The latterhas the advantage that different datasets can be given different weights inthe likelihood calculation (using the "weight" slot of thecaliset objects,x).Further, for continuous data (e.g. biomass), the likelihood considers the variance (standarddeviation) in the log likelihood calculation, which can vary between datasetswhen the likelihood is calculated for each dataset separately before combininginto an overall likelihood. The latter could be relevant when factors might leadto variability between datasets (e.g. different labs, different animal culture,...)

To conduct the likelihood calculations on separate datasets, the parameterindividualwhich by default is 'FALSE' can be set to 'TRUE'. Then, then log likelihoodsare calculated for each dataset individually (or in subgroups, using the "tag" names of thecaliset object, if provided, to group datasets with the same "tag"before calculating the log likelihood). Subsequently, the loglikelihoods for the subsets are combined into an overall likelihood (consideringtheset weights provided in the "weight" slot of thecaliset object).Note that for eachset only 1 weight can be provided (i.e. not individualweights for each datapoint within theset), and thatset with the same tagshould have identical weight.

The function was inspired by a MatLab BYOM v.6.8 procedure, created byTjalling Jager. For details, please refer to BYOM (http://debtox.info/byom.html)as well as Jager (2021).

Usage

lik_profile(  x,  par,  output,  data = NULL,  bounds = NULL,  refit = TRUE,  type = c("coarse", "fine"),  individual = FALSE,  break_prof = FALSE,  log_scale = FALSE,  data_type = c("continuous", "count"),  ...)

Arguments

Value

A list containing, for each parameter profiled, the likelihoodprofiling results as a dataframe;the 95% confidence interval; the original parameter value; the likelihood plot object; andthe recalibrated parameter values (in case a lower optimum was found)

References

Jager T, 2021: Robust Likelihood-Based Optimization and Uncertainty Analysisof Toxicokinetic-Toxicodynamic Models. Integrated Environmental Assessment andManagement 17:388-397.doi:10.1002/ieam.4333

Examples

# Example with Lemna model - physiological paramslibrary(dplyr)# observations - control runobs <- schmitt2013 %>%  filter(trial == "T0")# update metsulfuronmyscenario <- metsulfuron %>%  set_param(c(k_phot_fix = TRUE, Emax = 1)) %>%  set_init(c(BM = 0.0012)) %>%  set_noexposure() %>%  set_bounds(list(k_phot_max=c(0, 1)))fit <- calibrate(  x = myscenario,  par = c(k_phot_max = 1),  data = obs,  output = "FrondNo",  method = "Brent")# Likelihood profilingres <- lik_profile(  x = myscenario,  data = obs,  output = "FrondNo",  par = fit$par,  bounds = list(    k_phot_max = list(0, 30)  ),  refit = FALSE,  type = "fine",  method = "Brent")# plotplot(res)

Start and stop logging

Description

Start and stop logging

Usage

log_enable(file = NULL, append = TRUE, envir = parent.frame())log_disable()

Arguments

Value

no return value

Log R environment properties

Description

Log R environment properties

Usage

log_envir()

Value

no return value

Calculate log likelihood

Description

Calculates the sum of log likelihoods of each observation giventhe model parameterization.

Current implementations enable log likelihood calculations for:

1. continuous data, considering a normal distribution around the predictionfor each datapoint,

2. count data, considering a multinomial distribution for data reporting thenumber of survivors over time.

The log likelihood calculation for count data was inspired by a MatLab BYOM v.6.8procedure, created by Tjalling Jager. For details, please refer to BYOM(http://debtox.info/byom.html) as well as Jager (2021).

Usage

log_lik(  obs,  pred,  data_type = c("continuous", "count"),  log_scale = FALSE,  npars = NULL)

Arguments

Value

the log likelihood value

References

Jager T, 2021. Robust Likelihood-Based Optimization and Uncertainty Analysisof Toxicokinetic-Toxicodynamic Models. Integrated Environmental Assessment andManagement 17:388-397.doi:10.1002/ieam.4333

Examples

# simple example for continuous data ###### observationsobs <- c(12, 38, 92, 176, 176, 627, 1283, 2640)# intercept, a, and slope, b, of a Poisson regression fitted through obspars <- c(a = 2, b = 0.73)# predictions with the Poisson regressionpred <- c(15.43, 32.15, 66.99, 139.57, 290.82, 605.94, 1262.52, 2630.58)# example plotplot(seq(1:length(obs)), obs)lines(seq(1:length(obs)), pred)log_lik(  obs = obs,  pred = pred,  npars = length(pars),)# example with count data and GUTS model #####library(dplyr)# observational datadt <- ringtest_c %>% filter(replicate == "E")myexposure <- dt %>% select(time, conc)obs <- dt %>%  mutate(S=Nsurv / max(Nsurv)) %>%  select(time, S)# GUTS modelGUTS_RED_IT() %>%  set_param(c(hb = 0)) %>%  set_exposure(myexposure) -> myscenario# fitfit <- calibrate(  x = myscenario,  par = c(kd=1.2, alpha=9.2, beta=4.3),  data = obs,  output = "S")# updatemyscenario <- myscenario %>% set_param(fit$par)# simulatepred <- myscenario %>% simulate()pred <- pred$S #* max(obs$S)obs <- obs$S# calc likelihoodlog_lik(obs,    pred,    data_type = "count")

Add a log message

Description

Message will only appear in the console or in log file if logging wasenabled usinglog_enable().

Usage

log_msg(...)

Arguments

Value

no return value

Examples

log_msg("this message will not appear")log_enable()log_msg("this message will appear")log_msg("a number of ","elements to ",42," concatenate")

Log scenario properties

Description

Log scenario properties

Usage

log_scenarios(x, header = TRUE)

Arguments

Value

unmodified argumentx

Lemna model fitted tometsulfuron effect data

Description

Data set for the parametrisation of a mechanistic combinedtoxicokinetic-toxicodynamic (TK/TD) and growth model for the aquaticmacrophytes Lemna spp. as published by Schmittet al. (2013).The growth model was parameterised by Schmitt et al. based on thesedata while toxicokinetic and toxicodynamic parameters were determined byfitting the model using substance specific effect data of theherbicidemetsulfuron-methyl.

Usage

metsulfuron

Format

An object of classLemnaSchmitt of length 1.

Details

The scenario is based on theLemna_Schmitt model.

References

Schmitt W., Bruns E., Dollinger M., and Sowig P., 2013:Mechanistic TK/TD-modelsimulating the effect of growth inhibitors on Lemna populations. Ecol Model 255,pp. 1-10.doi:10.1016/j.ecolmodel.2013.01.017

See Also

Lemna-models,schmitt2013

A fitted GUTS-RED-IT scenario of the fathead minnow

Description

The example scenario consists of a fittedGUTS-RED-ITmodel and a constant exposure series. Model parameters were derived from atypical four-day acute fish toxicity study of thefathead minnow byGeigeret al. (1988).The study evaluated the effect ofchlorpyrifos concentrations in water onsurvival offathead minnows.

Usage

minnow_it

Format

An object of classGutsRedIt of length 1.

Details

The toxicity dataset used for parameter calibration is also referred to asGUTS Ring-test dataset C by EFSA (2018). Fitted parameters were estimatedusing themorse package.

The exposure series of the example scenario is a constant concentration of 1.0 µmol/Lover a period of four days with a daily time step.

Source

https://mosaic.univ-lyon1.fr/guts

References

Geiger D.L., Call D.J., and Brooke L.T., 1988:Acute toxicities of organicchemicals to fathead minnows (Pimephales promelas): Volume IV, pp. 195-197.University of Wisconsin-Superior, Center for Lake Superior Environmental Studies.ISBN 9780961496838.

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

See Also

GUTS-RED-models

Examples

# Print scenario parametersminnow_it# Run the example scenariominnow_it %>% simulate()

A fitted GUTS-RED-SD scenario of the fathead minnow

Description

The example scenario consists of a fittedGUTS-RED-SDmodel and a constant exposure series. Model parameters were derived from atypical four-day acute fish toxicity study of thefathead minnow byGeigeret al. (1988).The study evaluated the effect ofchlorpyrifos concentrations in water onsurvival offathead minnows.

Usage

minnow_sd

Format

An object of classGutsRedSd of length 1.

Details

The toxicity dataset used for parameter calibration is also referred to asGUTS Ring-test dataset C by EFSA (2018). Fitted parameters were estimatedusing themorse package.

The exposure series of the example scenario is a constant concentration of 1.0 µmol/Lover a period of four days with a daily time step.

Source

https://mosaic.univ-lyon1.fr/guts

References

Geiger D.L., Call D.J., and Brooke L.T., 1988:Acute toxicities of organicchemicals to fathead minnows (Pimephales promelas): Volume IV, pp. 195-197.University of Wisconsin-Superior, Center for Lake Superior Environmental Studies.ISBN 9780961496838.

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

See Also

GUTS-RED-models

Examples

# Print scenario parametersminnow_sd# Run the example scenariominnow_sd %>% simulate()

Zero exposure

Description

Creates anExposureSeries with zero concentration. When settingthe zero exposure, pay attention not to accidentally reset the output timesof your scenario as the zero exposure series contains only a single time point.See the examples.

Usage

no_exposure()

Value

an S4 object of typeExposureSeries

See Also

set_noexposure()

Examples

# Set exposure to zero, but keep the original output timesminnow_it %>%  set_noexposure() %>%  simulate()

Print information about numerical solver result

Description

Usage

num_info(obj)## Default S3 method:num_info(obj)## S3 method for class 'cvasi_simulate'num_info(obj)## S3 method for class 'cvasi_fit'num_info(obj)

Arguments

Details

Prints information on the status of a return value fromsimulate(), e.g.if it was successful and what, if any, issues occurred. Also provides tipson solving frequently occurring issues.

The function requires certain metadata which is created bydeSolve::ode()and is passed through to the result ofsimulate(). The metadata may be lostif thedata.frame returned bysimulate() is converted or cast to other types.

See Also

diagnostics()

Examples

# A simulation without any issuesminnow_it %>% simulate() %>% num_info()# A simulation which terminated early due to the solver# taking too many numerical stepsrs <- suppressWarnings(minnow_it %>% simulate(hmax=1e-80))num_info(rs)# Print deSolve diagnostics for additional informationdiagnostics(rs)

Set of model parameters

Description

Set of model parameters

Usage

parameter_set(model, param = list(), tag = NA_character_)

Arguments

Value

an S4 object of typeParameterSet

Slots

model

character, a string containing a model name, e.g."GUTS-RED-IT"

tag

character, an optional identifier

param

namedlist of model parameters

Examples

# create a parameter set and assign itps <- parameter_set("GUTS-RED-IT", list(kd=0.12, hb=0.3))GUTS_RED_IT() %>% set_param(ps)# multiple scenarios can be modified at oncec(GUTS_RED_IT(), GUTS_RED_IT()) %>%  set_param(ps)# model names must match, otherwise an error will be raisedtry(GUTS_RED_SD() %>% set_param(ps))

Disable parallelization for debugging

Description

In certain cases it might be beneficial to disable parallel executionof e.g. effect profile calculations. By disabling, all processes runsequentially and instantly pass messages to the console which would bedelayed during parallel processing. This makes it easier to pinpointproblems within the data or algorithm.

Usage

pll_debug(state = TRUE)

Arguments

Value

no return value

S3 plotting functions

Description

These functions overloadbase::plot() to provide simple plottingroutines to display various time-series and scenario objects.

Usage

## S3 method for class 'cvasi_drc'plot(x, y, scale_x = c("auto", "log10", "none"), ...)## S3 method for class 'cvasi_simulate'plot(x, y, ...)## S3 method for class 'lik_profile'plot(x, y, ...)plot_lik_profile(x)

Arguments

Value

(ggplot2) plot object

Methods (by class)

• plot(cvasi_drc): Plot dose response curves

• plot(cvasi_simulate): Plot return value ofsimulate()

• plot(lik_profile): Plot likelihood profiles.

Functions

• plot_lik_profile(): Alias ofplot.lik_profile() for backwards-compatibility.

Plot profiled parameter space

Description

The function provides bivariate parameter space plots indicatingparameter draws (from the 95% confidence intervals per parameter obtainedthrough likelihood profiling) that fall within the inner rim (in green, i.e.parameter sets which are not significantly different from the original, basedon a chi-square test). The original parameter set is also indicated (in orange),and, if different from the original set, the best fit parameter set is indicated(in red).

Usage

## S3 method for class 'param_space'plot(x, y, ...)plot_param_space(x)

Arguments

Value

plot object

Functions

• plot_param_space(): Alias ofplot.param_space() for backwards-compatibility.

Plot EPx values

Description

Usage

plot_epx(  EPx_ts,  exposure_ts,  draw = TRUE,  time_col = "time",  conc_col = "conc",  epx_x_title = "Start time",  conc_y_title = "Exposure conc.")

Arguments

Value

a grid of ggplots

Examples

ti <- 0:21expo <- abs(0.01*ti + rnorm(length(ti), 0, 0.05))exposure <- data.frame(time = ti, conc = expo)metsulfuron_epx_mtw <- metsulfuron %>%set_exposure(exposure) %>%epx_mtw(level = 10, factor_cutoff = 1000)metsulfuron_epx_mtwplot_epx(EPx_ts = metsulfuron_epx_mtw,exposure_ts = exposure, conc_y_title = "env. concentration [µg/L]")

Creates a PPC plot for a single dataset

Description

Usage

plot_ppc(  rs_mean,  rs_range,  col_number = 2,  obs_mean = NULL,  obs_full = NULL,  xy_lim = NULL,  study = NULL)

Arguments

Details

A sample of parameters representing the uncertainty within the datasetis passed to the function. All parameter combinations and exposure patternsare simulated and the range of predicted frond numbers is derived for asingle study. The uncertainty is displayed by a Posterior Predictive Plot(PPC). The data (rs_mean, obs_mean and obs_full) must have thefollowing format (col1 = time, col2 = data of interest, col3 = trial name).Data for uncertainties (rs_range) must have the format: col1 = time,col2 = lower boundaries, col3 = upper boundaries, col4 = trial. The usershould take care of the input data and consider whether control data anddata at time zero should be included in the model check.

Value

a ggplot2 plot object

Create PPC plot for one or more datasets

Description

Usage

plot_ppc_combi(table, xy_lim = NULL)

Arguments

Details

The function expects a data.frame with five mandatory and one optionalcolumn. The mandatory columns are as follows:

• pred: mean of predictions e.g. frond number for lemna

• max: maximum of predictions

• min: minimum of predictions

• obs: observations

• PPC: color codeThe optional column is to be namedstudy and contains a study identifier.If more than one study identifier is present in the table, individualstudies will be plotted in different colors and a legend will be displayed.The function is called by plot_ppc where the column names are defined(see rs_ppc object).

Value

a ggplot2 plot object

Creates a prediction plot for one effect scenario

Description

Usage

plot_scenario(model_base, plot_col = 2, trial_number = NULL)

Arguments

Details

This function has been deprecated and replaced by the genericplot().

Sometimes it is helpful if the user can plot results of one effectscenario. This is for instance the case for test simulations or predictionsfor one profile. This function runs the simulation for one effect scenarioand plots the results. Function plots the time (column 1) and the predictions(column 2, can be changed by the user plot_col)

Value

plot of the results for one⁠effect scenario⁠

Examples

# Please use `plot()` insteadmetsulfuron %>%  simulate() %>%  plot()

Creates plot of model results (uncertainties optional)

Description

Usage

plot_sd(  model_base,  treatments,  rs_mean,  rs_range = NULL,  obs_mean = NULL,  obs_full = NULL,  x_breaks = NULL,  y_lim = NULL,  grid_labels = NULL,  grid_ncol = 2,  plot_col = 2,  y_title = NULL,  ...)

Arguments

Details

All parameter combinations and exposure patterns are simulated and the meanof predictions is derived for a single study. The uncertainty ispassed to the function due to computation time. Results are displayed byplotting the time series including the uncertainty interval. Observation datacan be optionally displayed. Data should be provided in long format. Functionplots the time (column 1) and the predictions (column 2, can be changed bythe user plot_col)

Value

a ggplot2 plot object

Examples

set.seed(124)exposure <- data.frame(  time = 0:21,  conc = rnorm(n = 22, mean = 0.1, sd = 0.06),  trial = "T1")forcings <- list(temp = 12, rad = 15000)param <- list(EC50 = 0.3, b = 4.16, P_up = 0.0054)inits <- list(BM = 0.0012, E = 1, M_int = 0)scenario <- Lemna_Schmitt() %>%  set_forcings(forcings) %>%  set_param(param) %>%  set_init(inits)sim_result <- simulate_batch(  model_base = scenario,  treatments = exposure,  param_sample = NULL)plot_sd(  model_base = scenario,  treatments = exposure,  rs_mean = sim_result)

Pull metadata from scenarios

Description

The method pulls available metadata from scenario objects and returns atable with additional columns. If the argument already was adata.frameobject, the columns are appended. May overwrite existing columns of thesame name.

Usage

pull_metadata(x, model = TRUE, exposure = TRUE)

Arguments

Value

adata.frame

Examples

metsulfuron %>%  pull_metadata()

EFSA Ringtest Dataset C

Description

This dataset is part of EFSA'sGUTS ringtest to compare results from softwareimplementations ofGUTS-RED models (EFSA 2018). The ringtestfocused onGUTS-RED-IT andGUTS-RED-SD models.

Usage

ringtest_c

Format

An object of classdata.frame with 30 rows and 4 columns.

Details

Dataset C in this ringtest came from the work of Geiger et al. (1988) on effects ofDiazinon onfathead minnow. The dataset contains four columns, identifying the controland treatment levels, the concentrations in these treatments, the timepoint of measurementand the number of survivors.

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

Geiger DL, Call DJ, and Brooke LT, 1988: Acute Toxicities of Organic Chemicals toFathead Minnow (Pimephales promelas), Vol IV. Center for Lake Superior EnvironmentalStudies, University of Wisconsin-Superior, Superior, WI, USA.

https://cran.r-project.org/web/packages/GUTS/vignettes/ringTest.html

See Also

GUTS-RED-models

EFSA Ringtest Dataset A SD

Description

This dataset is part of EFSA'sGUTS ringtest to compare results from softwareimplementations ofGUTS-RED models (EFSA 2018). The ringtestfocused onGUTS-RED-IT andGUTS-RED-SD models.

Usage

ringtest_it

Format

An object of classdata.frame with 42 rows and 4 columns.

Details

Dataset A IT for the GUTS ring test is a Hypothetical data set constructed with IT.

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

https://cran.r-project.org/web/packages/GUTS/vignettes/ringTest.html

See Also

GUTS-RED-models

EFSA Ringtest Dataset A SD

Description

This dataset is part of EFSA'sGUTS ringtest to compare results from softwareimplementations ofGUTS-RED models (EFSA 2018). The ringtestfocused onGUTS-RED-IT andGUTS-RED-SD models.

Usage

ringtest_sd

Format

An object of classdata.frame with 42 rows and 4 columns.

Details

Dataset A SD for the GUTS ring test is a Hypothetical data set constructed with SD.

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

https://cran.r-project.org/web/packages/GUTS/vignettes/ringTest.html

See Also

GUTS-RED-models

A Weber scenario of algae exposed to isoproturon

Description

The scenario recreates the conditions of algae speciesR. subcapitata exposedto isoproturon in a flow-through reactor experiment, see Weber et al. (2012)publication. Scenario parameters and exposure series were set according toreported values to represent conditions in reactor A, as depicted inFigure 4A in Weber et al.

Usage

rsubcapitata

Format

An object of classAlgaeWeber of length 1.

References

Weber D, Schaefer D, Dorgerloh M, Bruns E, Goerlitz G, Hammel K, Preuss TGand Ratte HT, 2012. Combination of a higher-tier flow-through system andpopulation modeling to assess the effects of time-variable exposure ofisoproturon on the green algae Desmodesmus subspictatus andPseudokirchneriella subcapitata. Environmental Toxicology andChemistry, 31, 899-908.doi:10.1002/etc.1765

See Also

Algae_Weber

A Lemna effect study data set with multiple treatment levels

Description

Data was collected from Schmitt et al. (2013). The study observed the number ofLemna fronds during the study period of 14 days. The organisms were exposedto multiple concentrations of the sulfonyl urea herbicidemetsulfuron-methyl.

Usage

schmitt2013

Format

An object of classdata.frame with 56 rows and 4 columns.

Details

The number of Lemna fronds was recorded at the beginning of the experiment (t=0)and after 3, 5, 7, 10, 12, and 14 days. The exposure tometsulfuron-methylwas only present during the first seven days, which was followed by a recoveryperiod of another seven days without exposure to the substance.

The tabular dataset consists of four columns:

• First column: time (days)

• Second column: observed number of fronds (-)

• Third column: trial id (-)

• Fourth column: metsulfuron-methyl concentration (ug/L)

An examplescenario with parameters fitted to the experimental data setas conducted by Schmitt et al. is available asmetsulfuron.

References

Schmitt W., Bruns E., Dollinger M., and Sowig P., 2013:Mechanistic TK/TD-modelsimulating the effect of growth inhibitors on Lemna populations. Ecol Model 255,pp. 1-10.doi:10.1016/j.ecolmodel.2013.01.017

See Also

Lemna-models,metsulfuron

Sequence of scenarios

Description

Scenario sequences can be used to implement changes in model parametersover time, which otherwise would remain constant for the duration of a simulation.A sequence of scenarios is treated as a single scenario and each scenariois simulated one after the other. If scenarion in a sequence was simulated,scenarion+1 will start off in the model state wheren had ended.

Usage

sequence(seq, breaks = NULL)

Arguments

Details

Sequences are generally treated the same as scenarios: Sequences can besimulated, as well as effects and EPx can be derived.

Requirements

All scenarios in a sequence must fulfill the following requirements:

• All scenarios must have identical state variables

• Theoutput times of all scenarios must represent a continuous time serieswithout gaps or overlaps

Using thebreaks argument, the function can split up the scenarios'output times at the given break points. The break points must be withinthe interval defined by the superset of all output times in the sequence.

Value

an S4 object of typeScenarioSequence

See Also

sequence.extract

Examples

# Create a scenario with background mortality onlyscen1 <- minnow_it %>%  set_noexposure() %>%  set_times(0:10)# Modify a scenario parameter, e.g. set background mortality to zeroscen2 <- scen1 %>% set_param(c(hb=0))# Create a sequence of scenarios, scenario #1 will be simulated for the# time period [0, 4], and #2 for [4, 10]sq <- sequence(list(scen1, scen2), breaks=c(4))# Simulate the sequence: the mortality stops after t=4.0, due to scenario #2# being simulated after t=4.0, which disabled the background mortalitysimulate(sq)# Effect endpoints can also be calculatedeffect(sq)

Extract and replace elements of a sequence

Description

The array accessor generics allow extracting and replacing scenarios withinam existing sequence.[ and[[ work identical to

Usage

## S4 method for signature 'ScenarioSequence,numeric,missing,missing'x[i]## S4 method for signature 'ScenarioSequence,numeric'x[[i]]## S4 replacement method for signature 'ScenarioSequence,numeric,missing,EffectScenario'x[[i, j]] <- value## S4 method for signature 'ScenarioSequence'length(x)

Arguments

Value

various

Functions

• x[i: Returns a list of scenarios from the sequence.

• x[[i: Returns a single scenario from the sequence.

• `[[`(x = ScenarioSequence, i = numeric, j = missing) <- value: Replaces a single scenario in the sequence.

• length(ScenarioSequence): Returns the number of scenarios in the sequence.

Examples

# create a sequenceseq <- sequence(list(minnow_it, minnow_it), breaks=3)seq[1]       # first element, as a list of scenariosseq[c(1)]    # the sameseq[c(1, 2)] # both elements as a list of scenariosseq[[1]]     # first element as a scenario# replacing single elementsseq[[1]] <- minnow_sd %>% set_times(1:3)

Set boundaries of model parameters

Description

Modifies the boundaries of model parameters for one or morescenario orcaliset objects.

Usage

set_bounds(x, bounds)## S4 method for signature 'EffectScenario,list'set_bounds(x, bounds)## S4 method for signature 'CalibrationSet,list'set_bounds(x, bounds)## S4 method for signature 'list,list'set_bounds(x, bounds)## S4 method for signature 'ScenarioSequence,list'set_bounds(x, bounds)

Arguments

Value

scenario orcaliset with modified parameter boundaries

Examples

metsulfuron %>%   set_bounds(list(k_phot_max = c(0, 30),                   k_resp = c(0, 10)))

Set effect endpoints

Description

Effect endpoints calculated by functions such aseffect() andepx()can be enabled and disabled. If an endpoint is not required for an assessment,it should be disabled for reasons of computational efficiency. Please referto the model description for a list of available endpoints.

Usage

set_endpoints(x, endpoints)

Arguments

Value

ModifiedEffectScenario objects

Examples

# Only enable reproduction (R) endpoint for americamysis scenarioamericamysis %>%  set_endpoints("R") %>%  effect()# Enable endpoints length (L) and reproduction (R)americamysis %>%  set_endpoints(c("L","R")) %>%  effect()

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 atoxicant in water. Other interpretations are possible depending on modelassumptions.

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,NoExposureSeries'set_exposure(scenarios, series, ...)## 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, ...)## S4 method for signature 'ScenarioSequence,ANY'set_exposure(scenarios, series, ...)

Arguments

Details

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

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

Computational efficiency

Handling time-series is a costly task for the ODE solver due to consistencychecks and interpolation between time steps. How the solver interpolatesthe time-series can be controlled by optional arguments to functionssuch assimulate() andeffect(). Please refer tosimulate() for a briefoverview anddeSolve::forcings for a detailed description.

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

Output times

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

Multiple exposure series and scenarios

The functions supports modifying multiple scenarios at once: bycalling it with lists ofscenario andExposureSeriesobjects. The cartesian product of all scenarios and exposure series willbe returned, iff the parameterexpand = TRUE is set.

As an example for theexpand mode, two scenariosA andB and oneexposure seriesg will result in two scenariosAg andBg, bothusing exposure seriesg. Two scenariosA andB as well as twoexposure seresg andh will result in four scenariosAg,Ah,Bg,andBh.

Value

list ofEffectScenario objects

Examples

# Set a data.frame as exposure seriesdf <- data.frame(time=c(0, 1, 2, 3), conc=c(1, 1, 0, 0))Lemna_Schmitt() %>% set_exposure(df)# Create and set an ExposureSeries objectes1 <- ExposureSeries(df)Lemna_Schmitt() %>% set_exposure(es1)# By default, the time points of the exposure series will also be used as# as output times. To avoid overriding existing output times, set reset_times=FALSELemna_Schmitt() %>%  set_times(0:10) %>%  set_exposure(es1, reset_times=FALSE)# Setting two series with one function call, creates two scenarioses2 <- ExposureSeries(data.frame(time=5:10, conc=1))Lemna_Schmitt() %>% set_exposure(c(es1, es2))

Set time-dependent parameters

Description

Parameters which change their value over time are referred to asforcings.If and what parameters can vary over time depends on the model in question.In many cases,forcings represent time-series of environmental properties.

Usage

set_forcings(x, ...)## S4 method for signature 'EffectScenario'set_forcings(x, ...)## S4 method for signature 'list'set_forcings(x, ...)

Arguments

Details

Forcing time-series are always represented by adata.frame containing two columns. The first column representing time,the second representing the parameter that is a function of time. Theordering of columns is mandatory. The column names are essentially irrelevantbut may help documenting the scenario and its data. The rows must beordered chronologically. A time-series can consist of only a single row; inthis case it will represent constant conditions.

Handling forcing time-series is a costly task for the ODE solver due to consistencychecks and interpolation between timesteps. How the solver interpolatesthe forcing time-series can be controlled by certain arguments to functionssuch assimulate() andeffect(). Please refer tosimulate() for a briefoverview anddeSolve::forcings for a detailed description.

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

Value

Modifiedscenarios

Examples

# constant values will be automatically converted to a data.frameLemna_Schmitt() %>% set_forcings(temp=20) -> lemnalemna@forcings# setting multiple forcings at oncedf <- data.frame(t=0:14, temp=rnorm(15, mean=20)) # random temperature seriesLemna_Schmitt() %>% set_forcings(temp=df, rad=15000) -> lemnalemna@forcings# forcings can also be supplied as a named listLemna_Schmitt() %>% set_forcings(list(temp=20, rad=15000)) -> lemnalemna@forcings

Set initial state

Description

Theinitial state represents the starting values of a scenario's statevariables when starting a simulation. A scenario's default initial statemay be insufficient to get sensible results.

Usage

set_init(x, init)## S4 method for signature 'EffectScenario'set_init(x, init)## S4 method for signature 'ScenarioSequence'set_init(x, init)## S4 method for signature 'vector'set_init(x, init)

Arguments

Details

In theory, a scenarios's state variables can be renamed by modifying the namesof the initial state vector. However, this is stronglydiscouraged as this will affect other routines such aseffect() andepx()and may render results useless.

Value

modifiedEffectScenario objects

Examples

# Set initial biomass to 1.0metsulfuron %>% set_init(c(BM=1.0)) %>% simulate()

Set mode of action

Description

Updates the model parameterMoA to a certain value

Usage

set_mode_of_action(x, code)set_moa(x, code)

Arguments

Value

modifiedscenarios

Functions

• set_moa(): Shorthand version

Examples

# Set MoA=8, i.e. hazard during oogenesisamericamysis %>%  set_mode_of_action(8) %>%  effect(method="ode45")# alternative approach using the parameter directlyamericamysis %>%  set_param(c(MoA=8)) %>%  effect(method="ode45")

Set zero exposure

Description

The scenarios current exposure is replaced by a constant exposure time-seriesof value zero(0.0). Output times are unaffected.

Usage

set_noexposure(x)

Arguments

Value

vector ofscenarios

Examples

# Derive effect size in sample scenario without toxicant exposureminnow_it %>%  set_noexposure() %>%  effect()

Set scenario parameters

Description

Modifies the parameters of one or morescenario objects.

Usage

set_param(x, param)## S4 method for signature 'EffectScenario,vector'set_param(x, param)## S4 method for signature 'EffectScenario,ParameterSet'set_param(x, param)## S4 method for signature 'list,ParameterSet'set_param(x, param)## S4 method for signature 'list,vector'set_param(x, param)## S4 method for signature 'ScenarioSequence,ANY'set_param(x, param)## S4 method for signature 'CalibrationSet,ANY'set_param(x, param)

Arguments

Details

Most parameters are represented by numerical types but other typesare possible depending on model. Please refer to the model descriptionwhich parameters are required and in which unit. Some or all parameters maybe required to start a simulation. If required parameters are missing,simulation will fail with an error message.

Value

Vector of modified objects

Examples

Lemna_Schmitt() %>% set_param(c(Emax=1,EC50=0.12))

Set a tag

Description

Sets the user-defined, custom tag of a scenario. Tagscan be helpful to quickly distinguish scenarios by e.g. a user-specifiedstring.

Usage

set_tag(x, tag)

Arguments

Details

The function supports vectorized inputs.If argumentsx andtag are vectors, then tags are assigned to scenarioson a 1:1 basis. If the length of both vectors do not match, an error is raised.

Value

(vector of) modifiedscenarios

See Also

get_tag()

Examples

# set a custom tagmyscenario <- GUTS_RED_SD() %>% set_tag("My Custom Tag")# returns `My Custom Tag`get_tag(myscenario)# the tag also appears in the scenario overviewmyscenario

Set output times

Description

Minimum and maximum output times define the simulated period for a scenario.Simulation results will be returned for each output time, seesimulate().

Usage

set_times(x, times)

Arguments

Details

Be aware that output times may be modified byset_exposure(). Precision ofsimulation results may be influenced by chosen output times, seesimulate()for more information.

Value

Vector of modifiedscenarios

See Also

simulate(),get_times()

Examples

# Set simulated period to [2,4] with output intervals of length 1minnow_it %>% set_times(c(2,3,4))# Decrease output interval length to 0.1minnow_it %>% set_times(seq(2, 4, 0.1))

Set transfer events

Description

Atransfer refers to an event where a certain amount of biomassis moved to a new medium after a period of time. Effectively, this resetsthe scenario's state variable representing biomass and re-scales all statevariables which are correlated with biomass, such as adsorbed chemical mass.This feature replicates a procedure occurring e.g. inLemna effect studiesand may be necessary to recreate study results.

Usage

set_transfer(x, interval, times, biomass, scaled_comp)## S4 method for signature 'ANY'set_transfer(x, interval, times, biomass, scaled_comp)## S4 method for signature 'Transferable'set_transfer(x, interval, times, biomass, scaled_comp)set_notransfer(x)

Arguments

Details

If a transfer occurs, simulation results of that time point will report the model statebefore the transfer. Be aware that if transfers are defined using theinterval argument, the transfers will always occur relative to time pointzero (t = 0). As an example, setting a regular transfer of seven days,interval = 7, will result at transfers occurring at time points which areinteger multiplicates of seven, such ast=0,t=7,t=14 and so forth.The starting and end times of a scenario do not influecewhen a regulartransfer occurs, onlyif it occurs.

Transferred biomass

At each transfer, a defined amount of biomass is transferred to a new medium.This is modeled by interrupting the simulation at a transfer time point, modifyingthe biomass levelBM, and scaling affected compartments according to newbiomass levels. Scaling of compartments depending on biomass, such asinternal toxicant mass, is necessary to correctly reflect mass balances andconcentrations over time.

Transferred biomass is set using thebiomass parameter. Is is either asingle numerical value in which case the same biomass level is set at eachtransfer. Or it is a vector of numerical values with the same length as thetimes parameter in which case a custom biomass level can be set for eachtransfer. Multiple biomass levels can only be set in conjunction withcustom transfer time points.

Some scenario types define default values for transferred biomass basedon common study set ups.

Regular and custom transfer time points

Transfers can occur either in regular intervals of time or at selected, customtime points. For regular intervals, the parameterinterval is set to a singlenumeric value which has the same unit as the scenario's time dimension. As anexample: if a scenario uses the unit ofdays for time, the transfer intervalis also specified indays:

Transfers occurring at custom time points are set by passing a numerical vectorto the parametertimes. The time points' units must match with the unit oftime in the scenario. A custom transfer time pointmust not occur at thestarting time point of a simulation.

Affected compartments

Some compartments depend on biomass to correctly reflect mass balances andconcentrations over time, such asinternal toxicant mass. These compartmentsneed to be scaled linearly to reflect the change in biomass levels.The parameterscaled_comp accepts a character vector of compartment nameswhich are scaled at each transfer. This parameter should only be used withcustom, user-defined models. If no compartment needs to be scaled, set oruse the default value ofcharacter(0).

Value

Modifiedscenario objects

Functions

• set_notransfer(): Disable biomass transfers

See Also

Lemna-models

Examples

# Simulate biomass transfer of 50 *g/m²* at a regular interval of 7 *days*metsulfuron %>%  set_transfer(interval=7, biomass=50) %>%  simulate()# Simulate irregular biomass transfers occuring at days 5, 10, and 12metsulfuron %>%  set_transfer(times=c(5, 10, 12), biomass=50) %>%  simulate()# Simulate irregular transfers with changing amounts of transferred biomassmetsulfuron %>%  set_transfer(times=c(5, 10, 12), biomass=c(50, 20, 10)) %>%  simulate()# Disable all biomass transfersmetsulfuron %>%  set_notransfer() %>%  simulate()

Set window length

Description

Exposure windows are defined as a period of time at the scale of the exposure series.As an example: if an exposure series has an hourly time step, a window lengthof24 will consider the exposure within 24 hours intervals for effectcalculation. The same applies for the window interval, i.e. the period betweenconsidered exposure windows. Setlength=-1 to disable moving windows.

Usage

set_window(x, length, interval)set_nowindow(x)

Arguments

Value

modifiedEffectScenario objects

Functions

• set_nowindow(): Disable moving windows

Examples

# Calculate the maximum effect for all windows of 10 days lengthmetsulfuron %>%  set_window(length=10, interval=1) %>%  effect()# Disable moving exposure windowsmetsulfuron %>%  set_nowindow() %>%  effect()

Simulate an effect scenario

Description

The suppliedEffectScenario is passed on to the ODE solver for numericalintegration. Internally,simulate() is split up into several functionsdedicated to particular models, e.g. one for GUTS and one for Lemna typemodels. The package will take care of using the correct functionfor each model whensimulate() is called.

Usage

simulate(x, ...)## S4 method for signature 'EffectScenario'simulate(x, ...)## S4 method for signature 'Transferable'simulate(x, ...)## S4 method for signature 'ScenarioSequence'simulate(x, ...)## S4 method for signature 'SimulationBatch'simulate(x, ...)

Arguments

Details

Simulation results are returned as a time-series for each statevariable. Some models provide additional properties describing the model state,e.g. the internal concentration of a toxicant within the organism. Referto the respectivescenario for more information.

Additional arguments tosimulate() will be passed on todeSolve::ode()which enables control of the numerical integration parameters.

Output times and windows

The minimum and maximum of given time points define the simulatedperiod. However, the simulation can also be limited toa subset of time points by enabling a moving exposure window, seeset_window().

Results will be returned for each output time point. Precision of the numeric solvermay be affected by chosen output times in certain cases. Hence, small deviationsin results should be expected if different output times are set. This effectcan be mitigated by either defining are sufficiently small time step for the solverusing argumenthmax or by decreasing the error tolerancesatol andrtol.These arguments are passed to the solver, see e.g.deSolve::lsoda() for details.

Optional output variables

Some models support adding intermediary model variables to the return valueofsimulate(). Analyzing the additional outputs may be helpful to understandmodel behavior and support finding potential issues in model parameterization.

Optional outputs are enabled by setting the parameternout to a value greaterthan zero. Ifnout is set ton, then the firstn optional output columnswill be returned along the normal simulation result.

Which optional outputs are available depends on the model/scenario at hand.Please refer to the model documentation for details.As an example, theGUTS-RED-IT model supports adding theexternal toxicant concentration to the output by settingnout=1:

minnow_it %>% simulate(nout=1)

Numerical precision and stability

Each model was assigned a default ODE solver which handles most of theoccurring inputs well. In most cases, this will be an explicit numericalscheme of the Runge-Kutta family with variable step width. For certain extremeparameters settings, such as very high uptake/permeability of the contaminantor exposure series which represent step functions, the numerical approximationmight deteriorate and yield invalid results. In this case try to decrease theallowed max step width by setting the argumenthmax with various values.Start withhmax=1 and decrease the value by orders of 10. It is notpossible or desirable to reducehmax to extremely small values, as theODE solver will require more CPU time and simulation will become inefficient.

Oftentimes, it will be computational more efficient to adapt the solver'serror tolerancesatol andrtol than reducing the step widthhmax to achievestable numerics. Start by decreasing deSolve's default values byorders of ten until the simulation yields acceptable results, see e.g.deSolve::lsoda() for more information on error tolerances.

As an alternative to adapting solver parameters, it might be worthwhile totry other numerical schemes which can handle stiff ODEs, such as Radau, LSODA,or LSODES. To change solvers, set themethod argument.To select e.g. the Radau scheme, setmethod="radau". For LSODA, setmethod="lsoda".Radau performs better than LSODA in some cases, as the latter method can returnbiologically nonsensical results without raising an error. SeedeSolve::ode()for details on available ODE solvers.

Value

Adata.frame with the time-series of simulation results

Examples

# base R syntaxsimulate(minnow_sd)# tidy syntax with the same resultminnow_sd %>% simulate()# Extend the simulated time frame to the interval [0, 10]minnow_sd %>%  set_times(seq(0, 10)) %>%  simulate()# Use an alternative exposure profile, but keep the original output timesminnow_sd %>%  set_exposure(data.frame(t=0, c=10), reset_times=FALSE) %>%  simulate()#### Precision of results# A large number of output times forces smaller solver time stepsminnow_it %>%  set_times(seq(0, 10, 0.001)) %>%  simulate() %>%  tail()# Defining only two output times allows the ODE solver to make larger steps# in time during numerical integration. However, results can become# imprecise.minnow_long <- minnow_it %>% set_times(c(0, 10))minnow_long %>% simulate()# Numerical precision of results can be increased by limiting the solver's# maximum step length in time using argument `hmax`.minnow_long %>% simulate(hmax=0.005)# A similar numerical precision can be achieved by switching to an alternative# numerical integration scheme, such as the Radau scheme, without limiting# the step length.minnow_long %>% simulate(method="radau")# Reducing the step length even further may increase numerical precision, but# may exceed the solver's allowed number of integration steps per output interval.# The following simulation will be aborted with a solver error:try(  minnow_long %>% simulate(hmax=0.001))# However, the solver's maximum number of allowed steps can be increased,# if needed, using the argument `maxsteps`:minnow_long %>% simulate(hmax=0.001, maxsteps=10^5)

Batch simulation using multiple exposure series

Description

Usage

simulate_batch(model_base, treatments, param_sample = deprecated(), ...)

Arguments

Details

A convenience function to simulate a single base scenario with one or moreexposure series. This aims at reproducing the setup and results of commoneffect studies.

A scenario contains only one exposure series. However, laboratory experimentscommonly examine the effects of multiple exposure levels on a biological system.A batch simulation approach would involve running multiple simulations withvarying exposure or treatment conditions. To illustrate, if the objective isto examine the impact of a substance on cell growth, the simulation modelcould be designed to replicate the cell growth dynamics under varyingconcentrations of the substance. Each simulation run would represent aspecific exposure level, ranging from low to high concentrations of thechemical. To simulate such a laboratory experiment, the simulate_batchfunction can be used. All exposure series are saved in the treatment argument.The first column contains the time, the second column the concentration, andthe third column the trial name (exposure level, e.g. 'T1', 'T2', 'T3').

Value

adata.frame with simulation results

Examples

t1 <- data.frame(time=0:10, conc=0, trial="control")  # 1st treatment levelt2 <- data.frame(time=0:10, conc=1, trial="T1")       # 2nd treatment leveltreatments <- rbind(t1, t2)metsulfuron %>%  simulate_batch(treatments)

Calls ODE solver for a particular model

Description

Please refer to theModeling Howto vignette on how to implement custommodels by overloading thesolver function.

Usage

solver(scenario, ...)## S4 method for signature 'ANY'solver(scenario, ...)## S4 method for signature 'LemnaSetac'solver(scenario, ...)## S4 method for signature 'Magma'solver(scenario, ...)## S4 method for signature 'LemnaSchmitt'solver(scenario, ...)## S4 method for signature 'AlgaeWeber'solver(scenario, method = "lsoda", hmax = 0.1, nout = 1, ...)## S4 method for signature 'AlgaeTKTD'solver(scenario, method = "lsoda", hmax = 0.1, ...)## S4 method for signature 'AlgaeSimple'solver(scenario, method = "lsoda", hmax = 0.1, ...)## S4 method for signature 'DebAbj'solver(scenario, ...)## S4 method for signature 'DebTox'solver(scenario, method = "ode45", ...)## S4 method for signature 'DebDaphnia'solver(scenario, ...)## S4 method for signature 'GutsSd'solver(scenario, ...)## S4 method for signature 'GutsIt'solver(scenario, ...)## S4 method for signature 'GutsRedSd'solver(scenario, ...)## S4 method for signature 'GutsRedIt'solver(scenario, ...)

Arguments

Details

Some solvers may set reasonable default values for e.g. maximum steplength in time (hmax), but not all do. Please check the model documentation fordetails.

Value

data.frame with simulation results

Methods (by class)

• solver(ANY): Default solver, raises an error

• solver(LemnaSetac): Numerically integrates Lemna_SETAC scenarios

• solver(Magma): Numerically integratesMagma scenarios

• solver(LemnaSchmitt): Numerically integrates Lemna_Schmitt scenarios

• solver(AlgaeWeber): numerically integrates Algae_Weber scenarios

• solver(AlgaeTKTD): numerically integrates Algae_TKTD scenarios

• solver(AlgaeSimple): numerically integrates Algae_Simple scenarios

• solver(DebAbj): Numerically integrates DEB_abj scenarios

• solver(DebTox): Numerically integratesDEBtox scenarios

• solver(DebDaphnia): (deprecated) Numerically integratesDEBtox_Daphnia scenarios

• solver(GutsSd): Numerically integrates GUTS-SD scenarios

• solver(GutsIt): Numerically integrates GUTS-IT scenarios

• solver(GutsRedSd): Numerically integrates GUTS-RED-SD scenarios

• solver(GutsRedIt): Numerically integrates GUTS-RED-IT scenarios

Survival rate

Description

Derives the survival rate of individuals forReduced GUTS models. Function was replaced by output ofsimulate() andwill be removed in a later version.

Usage

survival(scenario, ...)

Arguments

Details

The survival rate describes the survival probability at eachtime point. The function simulates theGUTS scenario and appends a columnsurvival to the simulation result. A value of one (1.0) denotes thatall individuals survive. A value of zero (0.0) denotes that no individualssurvived.

Only available forReduced GUTS models, seeGUTS-RED-models.The equations were described by EFSA (2018).

Value

adata.frame containing simulation results

References

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues),Ockleford C, Adriaanse P, Berny P, et al., 2018:Scientific Opinion on thestate of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models forregulatory risk assessment of pesticides for aquatic organisms. EFSA Journal 2018;16(8):5377, 188 pp.doi:10.2903/j.efsa.2018.5377

See Also

GUTS-RED-models

Examples

# calculate survival rateminnow_it %>% survival()# plot survival over time based on a random exposure profileminnow_sd %>%  set_exposure(data.frame(t=1:100, c=runif(100)*10)) %>%  survival() -> dfplot(df$time, df$survival, "l")

Createcalisets fromtox_data

Description

This is a convenience function which eases the creation ofcalisetsfrom a base scenario and atox_data object. The scenariowill be used as is. If exposure series are defined by thetox_dataobject, then these will be assigned to the scenario(s) accordingly.

Usage

td2cs(scenario, data, output_var = NULL)

Arguments

Value

list ofcalisets

Examples

# Import trial data from Schmitt et al. (2013), including exposuremydata <- tox_data(schmitt2013)# Example trial contained in data set: trial 'T0.32'mydata@data[["T0.32"]]        # observed quantitiesmydata@exposure[["T0.32"]]    # associated exposure series# Create list of calisets from full data setlst <- td2cs(Lemna_SETAC(), mydata)# Example caliset representing conditions of trial 'T0.32'lst[[2]]

Prepare ecotox study data for fitting

Description

Takes ecotox study data inlong-form tabular format and prepares it forparameter fitting. It supports extracting (optional) exposure concentration fromtabular data (useful for e.g. studies of acute toxicity) or exposure seriescan also provided as individual time-series.

Usage

tox_data(data, exposure = NULL)

Arguments

Value

aToxData object

Tabular format

The long-form tabular data must have at least two and at most four columns.The position of the columns define what they represent, the column namesare ignored:

• First column: time

• Second column: observed quantity, e.g. number of individuals

• (optional) Third column: Trial or treatment ID

• (optional) Fourth column: Concentration

The first two columns, time and observed quantity, must always be present.The third column, trial ID, is used to split the table by treatment sothat trials can later be handled individually. The fourth column, concentration,can be used to also define the exposure level during the experiments.

Explicit exposure series

As an alternative to defining concentrations along observed data, exposurecan also be passed as a list of exposure levels and series withargumentexposure. It can be used to provide exposure series for eachtrial. The following object types are supported to define exposure:

• Numerical constants

• Tabular data, e.g.data.frames

• exposure series objects

If exposure is constant over time, exposure can be defined using a singleconstant value. More complex exposure time-series can be defined using e.g.data.frames. Tabular data must have two columns with the first columnrepresenting time and the second column representing exposure/concentrations.

Examples

library(dplyr)mydata <- schmitt2013 %>% tox_data()