improved documentation, typos fixed

.Rbuildignore

@@ -9,4 +9,5 @@
 ^\w*\.csv$
 ^[a-zA-Z0-9_]*\.r$
 ^doc$
+^docs$
 ^Meta$

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: lemna
 Title: Lemna Ecotox Effect Model
-Version: 0.9.0
+Version: 0.9.1
 Authors@R: c(
     person("Nils", "Kehrein", , "[email protected]", c("aut", "cre")),
     person("SETAC Europe IG Effect Modeling", role="ccp")

NEWS.md

@@ -0,0 +1,9 @@
+# lemna 0.9.1
+
+* Documentation improved and typos fixed
+* `lemna_desolve()` added which allows direct access to the ODE solver
+
+# lemna 0.9.0
+
+* Initial release
+

R/data.R

@@ -15,7 +15,7 @@
 #' model using substance specific effect data of metsulfuron-methyl.
 #'
 #' @references
-#' Schmitt W, Bruns E, Dollinger M, Sowig P. 2013. Mechanistic TK/TD-model
+#' 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}
 #'
@@ -44,7 +44,7 @@
 #' cf. Figure 2, and was included in this package by courtesy of the authors.
 #'
 #' @references
-#' Schmitt W, Bruns E, Dollinger M, Sowig P. 2013. Mechanistic TK/TD-model
+#' 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"
@@ -60,11 +60,10 @@
 #' cf. Figure 3, and was included in this package by courtesy of the authors.
 #'
 #' @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 for
+#' 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}
+#'   Products. Integr Environ Assess Manag 12(1), pp. 82-95. \doi{10.1002/ieam.1715}
 
 "hommen212"
 
@@ -84,11 +83,10 @@
 #' and represent the herbicide *metsulfuron-methyl*.
 #'
 #' @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 for
+#' 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}
+#'   Products. Integr Environ Assess Manag 12(1), pp. 82-95. \doi{10.1002/ieam.1715}
 #'
 #' @examples
 #' # Simulate the example scenario
@@ -111,11 +109,10 @@
 #' and represent the herbicide *metsulfuron-methyl*.
 #'
 #' @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 for
+#' 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}
+#'   Products. Integr Environ Assess Manag 12(1), pp. 82-95. \doi{10.1002/ieam.1715}
 #'
 #' @examples
 #' # Simulate the example scenario
@@ -138,11 +135,10 @@
 #' and represent the herbicide *metsulfuron-methyl*.
 #'
 #' @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 for
+#' 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}
+#'   Products. Integr Environ Assess Manag 12(1), pp. 82-95. \doi{10.1002/ieam.1715}
 #'
 #' @examples
 #' # Simulate the example scenario

R/lemna.R

@@ -5,36 +5,36 @@
 #' settings. Numerical integration is handled by [deSolve::lsoda()] by default
 #' which is well suited to handle stiff and non-stiff numerical problems.
 #'
-#' ## Initial state
+#' @section State variables:
 #' The model has two state variables:
-#' - Biomass, `BM` (g dw m-2)
-#' - Mass of toxicant in plant population, `M_int` (mass per m2, e.g. ug m-2)
+#' - `BM`, Biomass  (g dw m-2)
+#' - `M_int`, Mass of toxicant in plant population  (mass per m2, e.g. ug m-2)
 #'
-#' ## Output times
+#' @section Output times:
 #' 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.
 #'
-#' ## Parameters
+#' @section Parameters:
 #' The list of available model parameters, their units, and suggested default
 #' values is documented in [param_defaults()].
 #'
-#' ## Environmental variables
+#' @section Environmental variables:
 #' 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:
-#' - Exposure concentration, `conc` (mass per volume, e.g ug L-1)
-#' - Temperature, `tmp` (°C)
-#' - Irradiance, `irr` (kJ m-2 d-1)
-#' - Phosphorus concentration, `P` (mg P L-1)
-#' - Nitrogen concentration, `N` (mg N L-1)
+#' - `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
@@ -55,7 +55,7 @@
 #' represents time and must return a single scalar value. Using a function
 #' in combination with the compiled code solver will raise an error.
 #'
-#' ## R vs. compiled code
+#' @section R vs. compiled code:
 #' 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
@@ -65,7 +65,7 @@
 #'
 #' To use the compiled code feature, set the argument `ode_mode = "c"`.
 #'
-#' ## Additional outputs
+#' @section Simulation output:
 #' 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
@@ -77,6 +77,31 @@
 #' 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)
 #'
 #' @param init initial state of the model variables
 #' @param times numeric vector, output times for which model results are returned
@@ -94,6 +119,15 @@
 #' @importFrom utils read.csv
 #' @importFrom deSolve ode
 #' @export
+#'
+#' @references
+#' Klein J., Cedergreen N., Heine S., Reichenberger S., Rendal C.,
+#'   Schmitt W., Hommen U., 2021: Refined description of the *Lemna* TKTD growth model
+#'   based on *Schmitt et al.* (2013) – equation system and default parameters.
+#'   Report of the working group *Lemna* of the SETAC Europe Interest Group Effect
+#'   Modeling. Version 1, uploaded on 22. Sept. 2021.
+#'   <https://www.setac.org/group/SEIGEffectModeling>
+#'
 #' @examples
 #' # Simulate the metsulfuron example scenario
 #' lemna(metsulfuron)
@@ -288,26 +322,23 @@ lemna.lemna_scenario <- function(x, init, times, param, envir, ...) {
   lemna.default(init=init, times=times, param=param, envir=envir, ...)
 }
 
-#' Full access to ODE solver
+#' Access to the ODE solver
 #'
 #' 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. This structure may help
-#' avoiding CMD CHECK messages.
+#' All parameters will be passed on to the solver.
 #'
-#' @param nout optional `numerical`, number of additional output variables,
-#'    defaults to two
-#' @param ... additional parameters passed on to [deSolve::ode()]
+#' @param ... parameters passed on to [deSolve::ode()]
 #' @return result from [deSolve::ode()]
 #' @export
-lemna_desolve <- function(nout=2, ...) {
+lemna_desolve <- function(...) {
   # set names of additional output variables
   outnames <- c("C_int", "FrondNo", "f_loss", "f_photo", "fT_photo", "fI_photo",
                 "fP_photo", "fN_photo", "fBM_photo", "fCint_photo", "C_int_unb",
                 "C_ext", "Tmp", "Irr", "Phs", "Ntr", "dBM", "dM_int")
 
   ode(dllname="lemna", initfunc="lemna_init", func="lemna_func",
-     initforc="lemna_forc", nout=nout, outnames=outnames, ...)
+     initforc="lemna_forc", outnames=outnames, ...)
 }
 
 # Prepare environmental factor time series

R/param.R

@@ -5,50 +5,59 @@
 #' ## Model parameters
 #'
 #' ### Growth model
-#' - Model switch for unlimited growth conditions, `k_photo_fixed` (TRUE/FALSE)
-#' - Maximum photosynthesis rate, `k_photo_max` (d-1)
-#' - Reference loss rate, `k_loss` (d-1)
-#' - Lower biomass abundance threshold, `BM_threshold` (g dw m-2)
-#' - Reservoir for biomass recovery, `BM_min` (g dw m-2)
+#' - `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 m-2)
+#' - `BM_min`, Reservoir for biomass recovery (g dw m-2)
 #'
 #' ### Temperature response of photosynthesis
-#' - Optimum growth temperature, `T_opt` (°C)
-#' - Minimum growth temperature, `T_min` (°C)
-#' - Maximum growth temperature, `T_max` (°C)
+#' - `T_opt`, Optimum growth temperature (deg C)
+#' - `T_min`, Minimum growth temperature (deg C)
+#' - `T_max`, Maximum growth temperature (deg C)
 #'
 #' ### Temperature response of biomass loss rate
-#' - Temperature coefficient, `Q10` (-)
-#' - Reference temperature for response=1, `T_ref` (°C)
+#' - `Q10`, Temperature coefficient (-)
+#' - `T_ref`, Reference temperature for response=1 (°C)
 #'
 #' ### Irradiance reponse of photosynthesis
-#' - Slope of irradiance response, `alpha` (m2 d kJ-1)
-#' - Intercept of irradiance response, `beta` (-)
+#' - `alpha`, Slope of irradiance response (m2 d kJ-1)
+#' - `beta`, Intercept of irradiance response (-)
 #'
 #' ### Nutrient response of photosynthesis
-#' - Half-saturation constant of Nitrogen, `N_50` (mg N L-1)
-#' - Half-saturation constant of Phosphorus, `P_50` (mg P L-1)
+#' - `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
-#' -  Carrying capacity, `BM_L` (g dw m-2)
+#' - `BM_L`, Carrying capacity (g dw m-2)
 #'
 #' ### Concentration response (Toxicodynamics)
-#' - Internal concentration resulting in 50% effect, `EC50_int` (ug L-1)
-#' - Maximum inhibition c, `E_max` (-)
-#' - Slope parameter, `b` (-)
+#' - `EC50_int`, Internal concentration resulting in 50% effect (mass per volume)
+#' - `E_max`, Maximum inhibition (-)
+#' - `b`, Slope parameter (-)
 #'
 #' ### Internal concentration (Toxicokinetics)
-#' - Permeability, `P` (cm d-1)
-#' - Area per dry-weight ratio, `r_A_DW` (cm2 g-1)
-#' - Fresh weight per dry weight ratio, `r_FW_DW` (-)
-#' - Fresh weight density, `r_FW_V` (g cm-3)
-#' - Dry weight per frond ratio, `r_DW_FN` (g dw)
-#' - Partitioning coefficient plant:water, `K_pw` (-)
-#' - Metabolisation rate, `k_met` (d-1)
+#' - `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)
 #'
 #' @param values optional named numeric `vector`, values will override any
 #'   defaults
 #' @return named `list`
 #' @export
+#'
+#' @references
+#' Klein J., Cedergreen N., Heine S., Reichenberger S., Rendal C.,
+#'   Schmitt W., Hommen U., 2021: Refined description of the *Lemna* TKTD growth model
+#'   based on *Schmitt et al.* (2013) – equation system and default parameters.
+#'   Report of the working group *Lemna* of the SETAC Europe Interest Group Effect
+#'   Modeling. Version 1, uploaded on 22. Sept. 2021.
+#'   <https://www.setac.org/group/SEIGEffectModeling>
+#'
 #' @examples
 #' # Returns default model parameters, some parameters are not defined (NA)
 #' param_defaults()
@@ -75,9 +84,9 @@ param_defaults <- function(values) {
     BM_min = 0,            # reservoir for biomass recovery (g dw m-2)
 
     # response parameters
-    T_opt = 26.7,   # optimum growth temperature (°C)
-    T_min = 8,      # minimum growth temperature (°C)
-    T_max = 40.5,   # maximum growth temperature (°C)
+    T_opt = 26.7,   # optimum growth temperature (deg C)
+    T_min = 8,      # minimum growth temperature (deg C)
+    T_max = 40.5,   # maximum growth temperature (deg C)
     Q10 = 2,        # temperature coefficient (-)
     T_ref = 25,     # ref temperature for response=1 (°C)
     alpha = 5e-5,   # slope of irradiance response of photosynthesis (m2 d kJ-1)

README.Rmd

@@ -62,9 +62,9 @@ plot(result)
 
 The package contains two vignettes that may help you getting started:
 
- - [Introduction to the Lemna package](https://nkehrein.github.io/lemna_web/lemna-introduction.html)<br />
+ - [Introduction to the Lemna package](https://nkehrein.github.io/lemna/lemna-introduction.html)<br />
    A general *Tutorial* and guide to the package functions
- - [Lemna model verification](https://nkehrein.github.io/lemna_web/lemna-verification.html)<br />
+ - [Lemna model verification](https://nkehrein.github.io/lemna/lemna-verification.html)<br />
    A verification of the model implementation against results of the Schmitt
    *et al.* implementation. Contains advanced workflows of package features.
 
@@ -80,12 +80,12 @@ If you find any issues or bugs within the package, please create a
 
 ## References
 
-- Klein J, Cedergreen N, Heine S, Reichenberger S, Rendal C,
-  Schmitt W, Hommen U. 2021. Refined description of the *Lemna* TKTD growth model
+- Klein J., Cedergreen N., Heine S., Reichenberger S., Rendal C.,
+  Schmitt W., Hommen U., 2021: Refined description of the *Lemna* TKTD growth model
   based on *Schmitt et al.* (2013) – equation system and default parameters.
   Report of the working group *Lemna* of the SETAC Europe Interest Group Effect
   Modeling. Version 1, uploaded on 22. Sept. 2021.
   https://www.setac.org/group/SEIGEffectModeling
-- Schmitt W, Bruns E, Dollinger M, Sowig P. 2013. Mechanistic TK/TD-model
+- 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](https://doi.org/10.1016/j.ecolmodel.2013.01.017)