initial commit v0.9

.Rbuildignore

@@ -0,0 +1,12 @@
+^lemna\.Rproj$
+^\.Rproj\.user$
+^README\.Rmd$
+^LICENSE\.md$
+^data-raw$
+^dev$
+# any outputs in package directory that may have been created during testing
+^\w*\.png$
+^\w*\.csv$
+^[a-zA-Z0-9_]*\.r$
+^doc$
+^Meta$

.gitignore

@@ -0,0 +1,15 @@
+.Rproj.user
+.Rhistory
+.Rdata
+.httr-oauth
+.DS_Store
+# any outputs in package directory that may have been created during testing
+/*.png
+/*.csv
+/*.r
+/doc/
+/Meta/
+/inst/doc
+/inst/Meta
+/src-i386/
+/src-x64/

DESCRIPTION

@@ -0,0 +1,38 @@
+Package: lemna
+Title: Lemna Ecotox Effect Model
+Version: 0.9.0
+Authors@R: c(
+    person("Nils", "Kehrein", , "[email protected]", c("aut", "cre")),
+    person("SETAC Europe IG Effect Modeling", role="ccp")
+    )
+Description: An 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>.
+URL: https://github.com/nkehrein/lemna
+BugReports: https://github.com/nkehrein/lemna/issues
+License: MIT + file LICENSE
+Encoding: UTF-8
+LazyData: true
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.1.2
+Suggests: 
+    knitr,
+    rmarkdown,
+    testthat (>= 3.0.0),
+    dplyr,
+    tidyr,
+    future,
+    furrr,
+    RColorBrewer,
+    microbenchmark
+Config/testthat/edition: 3
+Imports: 
+    deSolve,
+    ggplot2,
+    gridExtra
+Depends: 
+    R (>= 3.60)
+VignetteBuilder: knitr

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2021
+COPYRIGHT HOLDER: Nils Kehrein

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2021 Nils Kehrein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NAMESPACE

@@ -0,0 +1,17 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(effect,default)
+S3method(effect,lemna_scenario)
+S3method(lemna,default)
+S3method(lemna,lemna_scenario)
+S3method(plot,lemna_result)
+export(effect)
+export(lemna)
+export(new_lemna_scenario)
+export(param_defaults)
+export(param_new)
+importFrom(stats,approx)
+importFrom(stats,approxfun)
+importFrom(utils,read.csv)
+importFrom(utils,tail)
+useDynLib(lemna, .registration = TRUE)

R/data.R

@@ -0,0 +1,150 @@
+#' A Lemna scenario fitted to metsulfuron-methyl effect data
+#'
+#' 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 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.
+#'
+#' # Literature
+#'   - 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}
+#'
+#' @examples
+#' # 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
+"metsulfuron"
+
+#' Observed frond numbers reported by Schmitt *et al.* (2013)
+#'
+#' 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.
+#'
+#' The dataset was presented in Schmitt *et al.* (2013),
+#' cf. Figure 2, and was included in this package by courtesy of the authors.
+#'
+#' # Literature
+#'   - 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}
+"schmitt77"
+
+#' Observed frond numbers reported by Hommen *et al.* (2015)
+#'
+#' 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.
+#'
+#' The dataset was presented in Hommen *et al.* (2015)],
+#' cf. Figure 3, and was included in this package by courtesy of the authors.
+#'
+#' # Literature
+#'   - 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 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}
+
+"hommen212"
+
+#' A Lemna scenario using FOCUS D1 Ditch environmental conditions
+#'
+#' 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.
+#'
+#' 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*.
+#'
+#' # Literature
+#'   - 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 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}
+#'
+#' @examples
+#' # Simulate the example scenario
+#' lemna(focusd1)
+"focusd1"
+
+#' A Lemna scenario using FOCUS D2 Ditch environmental conditions
+#'
+#' 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.
+#'
+#' 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*.
+#'
+#' # Literature
+#'   - 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 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}
+#'
+#' @examples
+#' # Simulate the example scenario
+#' lemna(focusd2)
+"focusd2"
+
+#' A Lemna scenario using FOCUS R3 Stream environmental conditions
+#'
+#' 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.
+#'
+#' 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*.
+#'
+#' # Literature
+#'   - 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 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}
+#'
+#' @examples
+#' # Simulate the example scenario
+#' lemna(focusr3)
+"focusr3"

R/effect.R

@@ -0,0 +1,96 @@
+#' Effects on biomass
+#'
+#' 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
+#'
+#' @param init initial state of the model variables
+#' @param times numeric vector, output times for which model results are returned
+#' @param param named list, Lemna model parameters
+#' @param envir named list, contains time series data for each of the five
+#'   environmental variables
+#' @param duration optional `numeric`, length of the simulated period to consider
+#'   for effect calculation, period starts at the beginning of the simulation
+#' @param ... additional parameters passed on to [lemna()] and [deSolve::ode()]
+#' @return `numeric`, effect on biomass in percent (%) \[0,100\]
+#' @export
+#'
+#' @examples
+#' # 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)
+effect <- function(...) {
+  UseMethod("effect")
+}
+
+# Default method to derive effects, all available info is given in the generic
+#' @describeIn effect All scenario parameters supplied as arguments
+#' @importFrom utils tail
+#' @export
+effect.default <- function(init, times, param, envir, duration, ...) {
+  if(!missing(duration)) {
+    if(max(times) - min(times) < duration)
+      stop("duration is longer than simulated period")
+
+    t_start <- min(times)
+    times <- times[times <= t_start + duration]
+    # make sure that the end of simulation hits the right time point
+    if(max(times) < t_start + duration) {
+      times <- c(times, t_start + duration)
+    }
+  }
+
+  # simulate with exposure
+  out <- lemna(init=init, times=times, param=param, envir=envir, ...)
+  # simulate control w/o exposure
+  envir$conc <- 0
+  ctrl <- lemna(init=init, times=times, param=param, envir=envir, ...)
+
+  # effect on biomass
+  BM_exp <-  tail(out$BM, 1)
+  BM_ctrl <- tail(ctrl$BM, 1)
+  BM_efx <- ifelse(BM_ctrl == 0, 0, 1 - BM_exp / BM_ctrl)
+
+  # effect on growth rate
+  t_length <- max(times) - min(times)
+  r_exp <-  log(BM_exp / out$BM[1]) / t_length
+  r_ctrl <- log(BM_ctrl / ctrl$BM[1]) / t_length
+  r_efx <- ifelse(r_ctrl == 0, 0, min(1, 1 - r_exp / r_ctrl))
+
+  c(
+    BM = BM_efx * 100,
+    r  = r_efx * 100
+  )
+}
+
+# Special case to derive effects for a Lemna scenario
+#
+# The method just pass its information to [effect.default()]
+#' @param x a `lemna_scenario` object
+#' @describeIn effect Scenario parameters supplied as a `lemna_scenario` object
+#' @export
+effect.lemna_scenario <- function(x, init, times, param, envir, duration, ...) {
+  # Overwrite settings from scenario?
+  if("init" %in% names(x) & missing(init)) {
+    init <- x$init
+  }
+  if("times" %in% names(x) & missing(times)) {
+    times <- x$times
+  }
+  if("param" %in% names(x) & missing(param)) {
+    param <- x$param
+  }
+  if("envir" %in% names(x) & missing(envir)) {
+    envir <- x$envir
+  }
+
+  effect.default(init=init, times=times, param=param, envir=envir, duration=duration, ...)
+}

R/lemna-package.R

@@ -0,0 +1,7 @@
+#
+# Export compiled library to package namespace
+#
+## usethis namespace: start
+#' @useDynLib lemna, .registration = TRUE
+## usethis namespace: end
+NULL