| Title: | Lemna Ecotox Effect Model |
|---|---|
| Description: | The reference implementation of model equations and default parameters for the toxicokinetic-toxicodynamic (TKTD) model of the Lemna (duckweed) aquatic plant. Lemna is a standard test macrophyte used in ecotox effect studies. The model was described and published by the SETAC Europe Interest Group Effect Modeling. It is a refined description of the Lemna TKTD model published by Schmitt et al. (2013) <doi:10.1016/j.ecolmodel.2013.01.017>. |
| Authors: | Nils Kehrein [aut, cre], SETAC Europe IG Effect Modeling [ccp] |
| Maintainer: | Nils Kehrein <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.1 |
| Built: | 2025-02-12 05:36:43 UTC |
| Source: | https://github.com/nkehrein/lemna |
Two endpoints are calculated which describe the effects on biomass:
BM, percent effect on biomass at the last time step of the simulation
r, percent effect on the average growth rate of biomass
effect(...) ## Default S3 method: effect(init, times, param, envir, duration, ...) ## S3 method for class 'lemna_scenario' effect(x, init, times, param, envir, duration, ...)effect(...) ## Default S3 method: effect(init, times, param, envir, duration, ...) ## S3 method for class 'lemna_scenario' effect(x, init, times, param, envir, duration, ...)
... |
additional parameters passed on to |
init |
initial state of the model variables |
times |
numeric vector, output times for which model results are returned |
param |
named list, Lemna model parameters |
envir |
named list, contains time series data for each of the five environmental variables |
duration |
optional |
x |
a |
numeric, effect on biomass in percent (%) [0,100]
effect(default): All scenario parameters supplied as arguments
effect(lemna_scenario): Scenario parameters supplied as a lemna_scenario object
# effects in sample scenario effect(metsulfuron) # effects with modified environmental data myenvir <- metsulfuron$envir myenvir$tmp <- 20 # increase to 20°C myenvir$conc <- 0.3 # constant exposure of 0.3 ug/L effect(metsulfuron, envir=myenvir) # calculate effects for the first seven days effect(metsulfuron, duration=7)# effects in sample scenario effect(metsulfuron) # effects with modified environmental data myenvir <- metsulfuron$envir myenvir$tmp <- 20 # increase to 20°C myenvir$conc <- 0.3 # constant exposure of 0.3 ug/L effect(metsulfuron, envir=myenvir) # calculate effects for the first seven days effect(metsulfuron, duration=7)
The dataset consists of a named list which contains vectors describing
initial state, parameters, output times, and environmental variables of the
Lemna model. The scenario represents conditions of the FOCUS D1 Ditch
exposure scenario.
focusd1focusd1
An object of class lemna_scenario of length 4.
The scenario will simulate a period of 365 days with hourly outputs, a start population of 80 g/m² dry weight, variable environmental conditions, and a complex, time-varying exposure pattern.
The scenario setup was published by Hommen et al. (2015). Exposure pattern and substance specific parameters are of exemplary character and represent the herbicide metsulfuron-methyl.
Hommen U., Schmitt W., Heine S., Brock Theo C.M., Duquesne S., Manson P., Meregalli G., Ochoa-Acuña H., van Vliet P., Arts G., 2015: How TK-TD and Population Models for Aquatic Macrophytes Could Support the Risk Assessment for Plant Protection Products. Integr Environ Assess Manag 12(1), pp. 82-95. doi:10.1002/ieam.1715
# Simulate the example scenario lemna(focusd1)# Simulate the example scenario lemna(focusd1)
The dataset consists of a named list which contains vectors describing
initial state, parameters, output times, and environmental variables of the
Lemna model. The scenario represents conditions of the FOCUS D2 Ditch
exposure scenario.
focusd2focusd2
An object of class lemna_scenario of length 4.
The scenario will simulate a period of 365 days with hourly outputs, a start population of 100 g/m² dry weight, variable environmental conditions, and a complex, time-varying exposure pattern.
The scenario setup was published by Hommen et al. (2015). Exposure pattern and substance specific parameters are of exemplary character and represent the herbicide metsulfuron-methyl.
Hommen U., Schmitt W., Heine S., Brock Theo C.M., Duquesne S., Manson P., Meregalli G., Ochoa-Acuña H., van Vliet P., Arts G., 2015: How TK-TD and Population Models for Aquatic Macrophytes Could Support the Risk Assessment for Plant Protection Products. Integr Environ Assess Manag 12(1), pp. 82-95. doi:10.1002/ieam.1715
# Simulate the example scenario lemna(focusd2)# Simulate the example scenario lemna(focusd2)
The dataset consists of a named list which contains vectors describing
initial state, parameters, output times, and environmental variables of the
Lemna model. The scenario represents conditions of the FOCUS R3 Stream
exposure scenario.
focusr3focusr3
An object of class lemna_scenario of length 4.
The scenario will simulate a period of 365 days with hourly outputs, a start population of 100 g/m² dry weight, variable environmental conditions, and a complex, time-varying exposure pattern.
The scenario setup was published by Hommen et al. (2015). Exposure pattern and substance specific parameters are of exemplary character and represent the herbicide metsulfuron-methyl.
Hommen U., Schmitt W., Heine S., Brock Theo C.M., Duquesne S., Manson P., Meregalli G., Ochoa-Acuña H., van Vliet P., Arts G., 2015: How TK-TD and Population Models for Aquatic Macrophytes Could Support the Risk Assessment for Plant Protection Products. Integr Environ Assess Manag 12(1), pp. 82-95. doi:10.1002/ieam.1715
# Simulate the example scenario lemna(focusr3)# Simulate the example scenario lemna(focusr3)
The data consists of observed frond numbers from experimental studies for various time points and exposure concentrations. The Lemna population was exposed to constant concentrations of metsulfuron-methyl for two days, followed by twelve days of recovery.
hommen212hommen212
An object of class tbl_df (inherits from tbl, data.frame) with 25 rows and 3 columns.
The dataset was presented in Hommen et al. (2015)], cf. Figure 3, and was included in this package by courtesy of the authors.
Hommen U., Schmitt W., Heine S., Brock Theo C.M., Duquesne S., Manson P., Meregalli G., Ochoa-Acuña H., van Vliet P., Arts G., 2015: How TK-TD and Population Models for Aquatic Macrophytes Could Support the Risk Assessment for Plant Protection Products. Integr Environ Assess Manag 12(1), pp. 82-95. doi:10.1002/ieam.1715
The function numerically integrates the Lemna model using the supplied
parameters, environmental factor time series, output time points, and other
settings. Numerical integration is handled by deSolve::lsoda() by default
which is well suited to handle stiff and non-stiff numerical problems.
lemna(...) ## Default S3 method: lemna( init = c(BM = 0, M_int = 0), times, param, envir, ode_mode = c("r", "c"), nout = 2, ... ) ## S3 method for class 'lemna_scenario' lemna(x, init, times, param, envir, ...)lemna(...) ## Default S3 method: lemna( init = c(BM = 0, M_int = 0), times, param, envir, ode_mode = c("r", "c"), nout = 2, ... ) ## S3 method for class 'lemna_scenario' lemna(x, init, times, param, envir, ...)
... |
additional parameters passed on to |
init |
initial state of the model variables |
times |
numeric vector, output times for which model results are returned |
param |
named list, Lemna model parameters |
envir |
named list, contains time series data for each of the five environmental variables |
ode_mode |
character, switch controls if ODE functions implemented in R or C are used, defaults to R |
nout |
numeric, controls the number of additional output variables of the
model, such as |
x |
a |
data.frame with simulation results
lemna(default): All scenario parameters supplied as arguments
lemna(lemna_scenario): Scenario parameters supplied as a lemna_scenario object
The model has two state variables:
BM, Biomass (g dw m-2)
M_int, Mass of toxicant in plant population (mass per m2, e.g. ug m-2)
The function will only return results for the requested time points. The solver may make additional time steps which are not returned, depending on the solver settings such as numerical tolerance. The number of output times and the distance between them can have influence on the numerical precision of results. Please refer to the manual of the deSolve package for more information on that topic.
The list of available model parameters, their units, and suggested default
values is documented in param_defaults().
The model requires a time series for each of the five environmental variables
For ease of use, a time series can be represented by either a constant
numeric value, a data.frame containing a time series, a character
string with a path to a CSV file containing a time series, or a function
returning a value for a certain time point.
The five environmental variables are as follows:
conc, Exposure concentration (mass per volume, e.g ug L-1)
tmp, Temperature (deg C)
irr, Irradiance (kJ m-2 d-1)
P, Phosphorus concentration (mg P L-1)
N, Nitrogen concentration (mg N L-1)
A data.frame containing a time series must consist of exactly two columns:
The first column contains the time in days, the second column the environmental
factor in question. The data.frame must contain at least one row. Time
points are not required to coincide with the solver's output times but
the user should take care that the solver's time step length is sufficiently
small so that it can consider the relevant dynamics of the time series.
This problem can be avoided by calling the model ODEs implemented in C, see
argument ode_mode.
If a string is passed as an environmental factor, the function will interpret
the string as a file path and will try to load the contents of a CSV file.
The same requirements as for a data.frame apply to a time series loaded
from a file.
When using the pure R code ODE, it is also possible to pass a function as an environmental factor. The function must accept exactly one argument which represents time and must return a single scalar value. Using a function in combination with the compiled code solver will raise an error.
The model can be simulated using pure R code (the default) or an implementation that uses the compiled code feature of deSolve. Compiled code is almost always significantly faster than pure R. The solver for compiled ODEs also handles environmental variables better than the pure R version. For optimal performance, the time series of environmental variables should always be as short as possible and as long as needed.
To use the compiled code feature, set the argument ode_mode = "c".
For reasons of convenience, the return value contains by default two additional
variables derived from simulation results: the internal concentration C_int
as well as the number of fronds FrondNo. These can be disabled by setting
the argument nout = 0.
The compiled code model can return up to 18 additional variables which represent intermediary variables, environmental variables, and derivatives calculated within the model equations. Please refer to the model description of Klein et al. for more information on these variables and how they influence model behavior.
The available output levels are as follows:
nout >= 1
C_int, internal concentration (mass per volume)
nout >= 2
FrondNo, frond number (-)
nout >= 4
f_loss, respiration dependency function (-)
f_photo, photosynthesis dependency function (-)
nout >= 10
fT_photo, temperature response of photosynthesis (-)
fI_photo, irradiance response of photosynthesis (-)
fP_photo, phosphorus response of photosynthesis (-)
fN_photo, nitrogen response of photosynthesis (-)
fBM_photo, density response of photosynthesis (-)
fCint_photo, concentration response of photosynthesis (-)
nout >= 16
C_int_unb, unbound internal concentration (mass per volume)
C_ext, external concentration (mass per volume)
Tmp, temperature (deg C)
Irr, irradiance (kJ m-2 d-1)
Phs, Phosphorus concentration (mg P L-1)
Ntr, Nitrogen concentration (mg N L-1)
nout >= 18
dBM, biomass derivative (g dw m-2 d-1)
dM_int, mass of toxicant in plants derivative (mass per m2 d-1)
Klein J., Cedergreen N., Heine S., Kehrein N., Reichenberger S., Rendal C., Schmitt W., Hommen U., 2022: Refined description of the Lemna TKTD growth model based on Schmitt et al. (2013) – equation system and default parameters, implementation in R. Report of the working group Lemna of the SETAC Europe Interest Group Effect Modeling. Version 1.1, uploaded on 09 May 2022. https://www.setac.org/group/SEIGEffectModeling
# Simulate the metsulfuron example scenario lemna(metsulfuron) # Create a simple plot of the number of fronds lemna(metsulfuron) -> result plot(result$time, result$FrondNo) # Create a nicer plot using a dedicated plotting routine plot(result) # Simulate the example scenario for a period of 30 days lemna(metsulfuron, times=0:30) -> result30 plot(result30) ## ## Create a custom Lemna scenario from scratch ## # Initial state: 12 fronds, no toxicant mass myinit <- c(BM=0.0012, M_int=0) # Output times: simulate 7 days with a ~2 hour time step mytime <- seq(0, 7, 0.1) # Default model parameters + TKTD parameters of a hypothetical substance myparam <- param_defaults(list( EC50_int = 0.1, # 50% effect level (ug L-1) b = 0.7, # slope parameter (-) P = 0.01 # permeability (cm d-1) )) # Custom environmental variables myenvir <- list( # exposure step function: # 3 days no exposure, followed by 4 days of 10 ug L-1 conc = data.frame(t=c(0,3,4,7), conc=c(0,0,10,10)), tmp = 18, # constant temperature of 18 °C irr = 15000, # constant irradiance of 15,000 kJ m-2 d-1 N = 0.6, # constant Nitrogen concentration of 0.6 mg L-1 P = 0.3 # constant Phosphorus concentration of 0.3 mg L-1 ) # Simulate the custom scenario and plot results lemna(init=myinit, times=mytime, param=myparam, envir=myenvir) -> result_custom plot(result_custom) # Simulate again, forcing the solver to use smaller time steps of hmax=0.001. # The resulting curves are almost identical for this example. lemna(init=myinit, times=mytime, param=myparam, envir=myenvir, hmax=0.001) -> result_custom2 library(ggplot2) ggplot(result_custom, aes(time, FrondNo)) + geom_line() + geom_line(data=result_custom2, color="red", style="dashed") # Combine all settings into a scenario object and simulate it scenario <- new_lemna_scenario( init = myinit, param = myparam, times = mytime, envir = myenvir ) lemna(scenario)# Simulate the metsulfuron example scenario lemna(metsulfuron) # Create a simple plot of the number of fronds lemna(metsulfuron) -> result plot(result$time, result$FrondNo) # Create a nicer plot using a dedicated plotting routine plot(result) # Simulate the example scenario for a period of 30 days lemna(metsulfuron, times=0:30) -> result30 plot(result30) ## ## Create a custom Lemna scenario from scratch ## # Initial state: 12 fronds, no toxicant mass myinit <- c(BM=0.0012, M_int=0) # Output times: simulate 7 days with a ~2 hour time step mytime <- seq(0, 7, 0.1) # Default model parameters + TKTD parameters of a hypothetical substance myparam <- param_defaults(list( EC50_int = 0.1, # 50% effect level (ug L-1) b = 0.7, # slope parameter (-) P = 0.01 # permeability (cm d-1) )) # Custom environmental variables myenvir <- list( # exposure step function: # 3 days no exposure, followed by 4 days of 10 ug L-1 conc = data.frame(t=c(0,3,4,7), conc=c(0,0,10,10)), tmp = 18, # constant temperature of 18 °C irr = 15000, # constant irradiance of 15,000 kJ m-2 d-1 N = 0.6, # constant Nitrogen concentration of 0.6 mg L-1 P = 0.3 # constant Phosphorus concentration of 0.3 mg L-1 ) # Simulate the custom scenario and plot results lemna(init=myinit, times=mytime, param=myparam, envir=myenvir) -> result_custom plot(result_custom) # Simulate again, forcing the solver to use smaller time steps of hmax=0.001. # The resulting curves are almost identical for this example. lemna(init=myinit, times=mytime, param=myparam, envir=myenvir, hmax=0.001) -> result_custom2 library(ggplot2) ggplot(result_custom, aes(time, FrondNo)) + geom_line() + geom_line(data=result_custom2, color="red", style="dashed") # Combine all settings into a scenario object and simulate it scenario <- new_lemna_scenario( init = myinit, param = myparam, times = mytime, envir = myenvir ) lemna(scenario)
This function can be used by external packages to access the ODE implemented in C without the surrounding sanity checks and data loading procedures. All parameters will be passed on to the solver.
lemna_desolve(...)lemna_desolve(...)
... |
parameters passed on to |
result from deSolve::ode()
The dataset consists of a named list which contains vectors describing
initial state, parameters, output times, and environmental variables of the
Lemna model.
metsulfuronmetsulfuron
An object of class lemna_scenario of length 4.
The scenario will simulate a period of 14 days with daily outputs, a start population of 12 fronds, unlimited growth conditions, and an exposure pattern represented by a step-function.
The scenario setup was published by Schmitt et al. (2013). A mechanistic combined toxicokinetic-toxicodynamic (TK/TD) and growth model for the aquatic macrophytes Lemna spp. was parameterized by the authors based on literature data. TK/TD parameters were determined by calibrating the model using substance specific effect data of metsulfuron-methyl.
Schmitt W., Bruns E., Dollinger M., Sowig P., 2013: Mechanistic TK/TD-model simulating the effect of growth inhibitors on Lemna populations. Ecol Model 255, pp. 1-10. doi:10.1016/j.ecolmodel.2013.01.017
# Simulate the example scenario lemna(metsulfuron) # Simulate a longer time period of 21 days lemna(metsulfuron, times=0:21) # Print the scenario's exposure series metsulfuron$envir$conc # Print all environmental variables metsulfuron$envir# Simulate the example scenario lemna(metsulfuron) # Simulate a longer time period of 21 days lemna(metsulfuron, times=0:21) # Print the scenario's exposure series metsulfuron$envir$conc # Print all environmental variables metsulfuron$envir
Lemna scenario constructor
new_lemna_scenario( init = c(BM = 0, M_int = 0), times = c(), param = list(), envir = list() )new_lemna_scenario( init = c(BM = 0, M_int = 0), times = c(), param = list(), envir = list() )
init |
initial state of the model variables |
times |
numeric vector, output times for which model results are returned |
param |
named list, Lemna model parameters |
envir |
named list, contains time series data for each of the five environmental variables |
a lemna_scenario object
Returns the default Lemna model parameters as reported by Klein et al. (2022).
param_defaults(values) param_new(values)param_defaults(values) param_new(values)
values |
optional named numeric |
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_min, Threshold density for setting dBM/dt to zero (g dw m-2)
T_opt, Optimum growth temperature (deg C)
T_min, Minimum growth temperature (deg C)
T_max, Maximum growth temperature (deg C)
Q10, Temperature coefficient (-)
T_ref, Reference temperature for response=1 (°C)
alpha, Slope of irradiance response (m2 d kJ-1)
beta, Intercept of irradiance response (-)
N_50, Half-saturation constant of Nitrogen (mg N L-1)
P_50, Half-saturation constant of Phosphorus (mg P L-1)
BM_L, Carrying capacity (g dw m-2)
EC50_int, Internal concentration resulting in 50% effect (mass per volume)
E_max, Maximum inhibition (-)
b, Slope parameter (-)
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)
named list
param_new(): A parameter set without default values
Klein J., Cedergreen N., Heine S., Kehrein N., Reichenberger S., Rendal C., Schmitt W., Hommen U., 2022: Refined description of the Lemna TKTD growth model based on Schmitt et al. (2013) – equation system and default parameters, implementation in R. Report of the working group Lemna of the SETAC Europe Interest Group Effect Modeling. Version 1.1, uploaded on 09 May 2022. https://www.setac.org/group/SEIGEffectModeling
# Returns default model parameters, some parameters are not defined (NA) param_defaults() # Overwrite one of the default parameters param_defaults(list(k_photo_max = 0.42)) # Provide values for substance specific TKTD parameters param_defaults(list( EC50_int = 23, # 50% effect level (mass per volume) b = 1, # slope parameter (-) P = 0.42 # permeability (cm d-1) )) # Returns a list of required model parameters with all values set to NA param_new()# Returns default model parameters, some parameters are not defined (NA) param_defaults() # Overwrite one of the default parameters param_defaults(list(k_photo_max = 0.42)) # Provide values for substance specific TKTD parameters param_defaults(list( EC50_int = 23, # 50% effect level (mass per volume) b = 1, # slope parameter (-) P = 0.42 # permeability (cm d-1) )) # Returns a list of required model parameters with all values set to NA param_new()
Creates up to four plots in a gridded layout depicting
Exposure (i.e. external) concentration, as well as damage (internal concentration, C_int)
if available
Internal toxicant mass (M_int)
Population size as biomass (BM)
Population size as number of fronds (FrondNo) if available
## S3 method for class 'lemna_result' plot(x, y, munit = "ug/m2", cunit = "ug/L", legend = TRUE, ...)## S3 method for class 'lemna_result' plot(x, y, munit = "ug/m2", cunit = "ug/L", legend = TRUE, ...)
x |
|
y |
unused parameter |
munit |
character, unit of internal mass, defaults to |
cunit |
character, unit of exposure, defaults to |
legend |
logical, if |
... |
unused parameter |
a gridded plot
# Simulate a sample scenario and plot results result <- lemna(metsulfuron) plot(result) # Hide the legend of the concentration plot plot(result, legend=FALSE) # Simulate and plot a scenario with changing environmental conditions plot(lemna(focusd1))# Simulate a sample scenario and plot results result <- lemna(metsulfuron) plot(result) # Hide the legend of the concentration plot plot(result, legend=FALSE) # Simulate and plot a scenario with changing environmental conditions plot(lemna(focusd1))
The data consists of observed frond numbers from experimental studies for various time points and exposure concentrations. The Lemna population was exposed to constant concentrations of metsulfuron-methyl for seven days, followed by seven days of recovery.
schmitt77schmitt77
An object of class tbl_df (inherits from tbl, data.frame) with 49 rows and 3 columns.
The dataset was presented in Schmitt et al. (2013), cf. Figure 2, and was included in this package by courtesy of the authors.
Schmitt W., Bruns E., Dollinger M., Sowig P., 2013: Mechanistic TK/TD-model simulating the effect of growth inhibitors on Lemna populations. Ecol Model 255, pp. 1-10. doi:10.1016/j.ecolmodel.2013.01.017