EFSA 2015 tier 1 PEC soil, clean up, add static docs

11 files changed, 250 insertions, 168 deletions

diff --git a/pkg/R/FOCUS_GW_scenarios_2012.R b/pkg/R/FOCUS_GW_scenarios_2012.R
index 4e03572..49cf7dd 100644
--- a/pkg/R/FOCUS_GW_scenarios_2012.R
+++ b/pkg/R/FOCUS_GW_scenarios_2012.R
@@ -6,4 +6,6 @@
 #' @references FOCUS (2012) Generic guidance for Tier 1 FOCUS ground water assessments. Version 2.1. 
 #'  FOrum for the Co-ordination of pesticde fate models and their USe. 
 #'  http://focus.jrc.ec.europa.eu/gw/docs/Generic_guidance_FOCV2_1.pdf
+#' @examples
+#' FOCUS_GW_scenarios_2012
 NULL
diff --git a/pkg/R/GUS.R b/pkg/R/GUS.R
index 8a20561..4a6532d 100644
--- a/pkg/R/GUS.R
+++ b/pkg/R/GUS.R
@@ -1,8 +1,25 @@
+# Copyright (C) 2015  Johannes Ranke
+# Contact: jranke@uni-bremen.de
+# This file is part of the R package pfm
+
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+
+# You should have received a copy of the GNU General Public License along with
+# this program. If not, see <http://www.gnu.org/licenses/>
+
 #' Groundwater ubiquity score based on Gustafson (1989)
 #' 
 #' The groundwater ubiquity score GUS is calculated according to
 #' the following equation
-#' \deqn{GUS = \log_10 DT50_{soil} (4 - \log_10 K_{oc}}{GUS = log10 DT50soil * (4 - log10 Koc)}
+#' \deqn{GUS = \log_{10} DT50_{soil} (4 - \log_{10} K_{oc})}{GUS = log10 DT50soil * (4 - log10 Koc)}
 #' 
 #' @references Gustafson, David I. (1989) Groundwater ubiquity score: a simple
 #' method for assessing pesticide leachability. \emph{Environmental
diff --git a/pkg/R/PEC_soil.R b/pkg/R/PEC_soil.R
index fff1f20..27fac52 100644
--- a/pkg/R/PEC_soil.R
+++ b/pkg/R/PEC_soil.R
@@ -15,122 +15,200 @@
 # You should have received a copy of the GNU General Public License along with
 # this program. If not, see <http://www.gnu.org/licenses/>
 
+# Register global variables
+if(getRversion() >= '2.15.1') utils::globalVariables(c("destination", "study_type", "TP_identifier",
+                                                       "soil_scenario_data_EFSA_2015"))
+
 #' Calculate predicted environmental concentrations in soil
 #'
-#' This is a basic, vectorised form of a simple calculation of a contaminant
-#' concentration in bulk soil based on complete, instantaneous mixing.
-#'
+#' This is a basic calculation of a contaminant concentration in bulk soil
+#' based on complete, instantaneous mixing. If an interval is given, an 
+#' attempt is made at calculating a long term maximum concentration using
+#' the concepts layed out for example in the PPR panel opinion (EFSA 2012).
+#' 
+#' This assumes that the complete load to soil during the time specified by
+#' 'interval' (typically 365 days) is dosed at once. As in the PPR panel
+#' opinion cited below (PPR panel 2012), only temperature correction using the
+#' Arrhenius equation is performed.  
+#' 
+#' Total soil and porewater PEC values for the scenarios as defined in the EFSA
+#' guidance (2015, p. 13) can easily be calculated.
+#' 
+#' @note If temperature information is available in the selected scenarios, as
+#'   e.g. in the EFSA scenarios, the DT50 for groundwater modelling
+#'   (destination 'PECgw') is taken from the chent object, otherwise the DT50
+#'   with destination 'PECsoil'.
 #' @param rate Application rate in units specified below
 #' @param rate_units Defaults to g/ha
 #' @param interception The fraction of the application rate that does not reach the soil
 #' @param mixing_depth Mixing depth in cm
-#' @param bulk_density Bulk density of the soil. Defaults to 1.5 kg/L, or 1500 kg/m3
+#' @param interval Period of the deeper mixing, defaults to 365, which is a year if
+#'   rate units are in days
+#' @param n_periods Number of periods to be considered for long term PEC calculations
 #' @param PEC_units Requested units for the calculated PEC. Only mg/kg currently supported
+#' @param PEC_pw_units Only mg/L currently supported
+#' @param tillage_depth Periodic (see interval) deeper mixing in cm
+#' @param chent An optional chent object holding substance specific information. Can 
+#'   also be a name for the substance as a character string
+#' @param DT50 If specified, overrides soil DT50 endpoints from a chent object
+#'   If DT50 is not specified here and not available from the chent object, zero
+#'   degradation is assumed
+#' @param Koc If specified, overrides Koc endpoints from a chent object
+#' @param Kom Calculated from Koc by default, but can explicitly be specified
+#'   as Kom here
+#' @param t_avg Averaging times for time weighted average concentrations
+#' @param scenarios If this is 'default', the DT50 will be used without correction
+#'   and soil properties as specified in the REACH guidance (R.16, Table
+#'   R.16-9) are used for porewater PEC calculations.  If this is "EFSA_2015",
+#'   the DT50 is taken to be a modelling half-life at 20°C and pF2 (for when
+#'   'chents' is specified, the DegT50 with destination 'PECgw' will be used),
+#'   and corrected using an Arrhenius activation energy of 65.4 kJ/mol. Also
+#'   model and scenario adjustment factors from the EFSA guidance are used.
+#' @param porewater Should equilibrium porewater concentrations be estimated
+#'   based on Kom and the organic carbon fraction of the soil instead of total
+#'   soil concentrations?  Based on equation (7) given in the PPR panel opinion
+#'   (EFSA 2012, p. 24) and the scenarios specified in the EFSA guidance (2015,
+#'   p. 13).
 #' @return The predicted concentration in soil
-#' @export
+#' @references EFSA Panel on Plant Protection Products and their Residues (2012)
+#'   Scientific Opinion on the science behind the guidance for scenario
+#'   selection and scenario parameterisation for predicting environmental
+#'   concentrations of plant protection products in soil. \emph{EFSA Journal}
+#'   \bold{10}(2) 2562, doi:10.2903/j.efsa.2012.2562
+#' 
+#'   EFSA (European Food Safety Authority) (2015) EFSA guidance document for
+#'   predicting environmental concentrations of active substances of plant
+#'   protection products and transformation products of these active substances
+#'   in soil. \emph{EFSA Journal} \bold{13}(4) 4093
+#'   doi:10.2903/j.efsa.2015.4093
 #' @author Johannes Ranke
+#' @export
 #' @examples
 #' PEC_soil(100, interception = 0.25)
+#' 
+#' # This is example 1 starting at p. 79 of the EFSA guidance (2015)
+#' PEC_soil(1000, interval = 365, DT50 = 250, t_avg = c(0, 21),
+#'                scenarios = "EFSA_2015")
+#' PEC_soil(1000, interval = 365, DT50 = 250, t_av = c(0, 21),
+#'                Kom = 1000, scenarios = "EFSA_2015", porewater = TRUE)
+#' 
+#' # The following is from example 4 starting at p. 85 of the EFSA guidance (2015)
+#' # Metabolite M2
+#' # Calculate total and porewater soil concentrations for tier 1 scenarios
+#' # Relative molar mass is 100/300, formation fraction is 0.7 * 1
+#' results_pfm <- PEC_soil(100/300 * 0.7 * 1 * 1000, interval = 365, DT50 = 250, t_avg = c(0, 21),
+#'                         scenarios = "EFSA_2015")
+#' results_pfm_pw <- PEC_soil(100/300 * 0.7 * 1000, interval = 365, DT50 = 250, t_av = c(0, 21),
+#'                            Kom = 100, scenarios = "EFSA_2015", porewater = TRUE)
+
 PEC_soil <- function(rate, rate_units = "g/ha", interception = 0,
-                     mixing_depth = 5, bulk_density = 1.5,
-                     PEC_units = "mg/kg")
+                     mixing_depth = 5, 
+                     PEC_units = "mg/kg", PEC_pw_units = "mg/L",
+                     interval = NA, n_periods = Inf,
+                     tillage_depth = 20, 
+                     chent = NA, 
+                     DT50 = NA, 
+                     Koc = NA, Kom = Koc / 1.724,
+                     t_avg = 0,
+                     scenarios = c("default", "EFSA_2015"),
+                     porewater = FALSE)
 {
   rate_to_soil = (1 - interception) * rate
   rate_units = match.arg(rate_units)
   PEC_units = match.arg(PEC_units)
+  scenarios = match.arg(scenarios)
+  sce <- switch(scenarios, 
+    default = data.frame(rho = 1.5, T_arr = NA, theta_fc = 0.2, f_oc = 0.02, 
+                         f_sce = 1, f_mod = 1, row.names = "default"),
+    EFSA_2015 = if (porewater) soil_scenario_data_EFSA_2015[4:6, ] 
+                else soil_scenario_data_EFSA_2015[1:3, ]
+  )
+  n_sce = nrow(sce)
+
   soil_volume = 100 * 100 * (mixing_depth/100)   # in m3
-  soil_mass = soil_volume * bulk_density * 1000  # in kg
-  PEC_soil = rate_to_soil * 1000 / soil_mass     # in mg/kg
-  return(PEC_soil)
-}
+  soil_mass = soil_volume * sce$rho * 1000  # in kg
 
-if(getRversion() >= '2.15.1') utils::globalVariables(c("destination", "study_type", "TP_identifier"))
+  # The following is C_T,ini from EFSA 2012, p. 22, but potentially with interception > 0
+  PEC_soil_ini = rate_to_soil * 1000 / soil_mass     # in mg/kg
 
-#' Calculate predicted environmental concentrations in soil for a product
-#'
-#' Calculates long term accumulation PEC values
-#'
-#' @param product An object of class pp
-#' @param rate Application rate in units specified below
-#' @param rate_units Defaults to g/ha
-#' @param interception The fraction of the application rate that does not reach the soil
-#' @param mixing_depth Mixing depth in cm
-#' @param tillage_depth Periodic (see interval) deeper mixing in cm
-#' @param interval Period of the deeper mixing, defaults to 365, which is a year if
-#'   rate units are in days
-#' @param bulk_density Bulk density of the soil. Defaults to 1.5 kg/L, or 1500 kg/m3
-#' @param PEC_units Requested units for the calculated PEC. Only mg/kg currently supported
-#' @return A data frame with compound names, and initial, plateau maximum, plateau minimum (background)
-#'   and long term maximum predicted concentrations in soil
-#' @export PEC_soil_product
-#' @author Johannes Ranke
-PEC_soil_product <- function(product, rate, rate_units = "L/ha", interception = 0,
-                             mixing_depth = 5, tillage_depth = 20, 
-                             interval = 365,
-                             bulk_density = 1.5,
-                             PEC_units = "mg/kg") {
-  rate_units = match.arg(rate_units)
-  PEC_units = match.arg(PEC_units)
-  if (product$density_units != "g/L") stop("Product density other than g/L not supported")
-  if (product$concentration_units != "g/L") {
-    stop("Active ingredient concentration units other than g/L not supported")
+  # Decide which DT50 to take, or set degradation to zero if no DT50 available
+  if (is.na(DT50) & is(chent, "chent")) {
+    if (all(is.na(sce$T_arr))) {   # No temperature correction
+      DT50 <- subset(chent$soil_degradation_endpoints, destination == "PECsoil")$DT50
+    } else {
+      DT50 <- subset(chent$soil_degradation_endpoints, destination == "PECgw")$DT50
+    }
+    if (length(DT50) > 1) stop("More than one PECsoil DT50 in chent object")
+    if (length(DT50) == 0) DT50 <- Inf
   }
+  k = log(2)/DT50
 
-  results <- data.frame(compound = character(0), initial = numeric(0), 
-                        plateau_max = numeric(0), plateau_min = numeric(0), 
-                        long_term_max = numeric(0),
-                        stringsAsFactors = FALSE)
-
-  for (ai_name in names(product$ais)) {
-    ai <- product$ais[[ai_name]]
-    ai_rate <- rate * product$concentrations[ai_name] 
-    ini <- PEC_soil(ai_rate,
-                    interception = interception, mixing_depth = mixing_depth,
-                    bulk_density = bulk_density)
-    results[ai_name, "compound"] <- ai$identifier
-    results[ai_name, "initial"] <- ini
-
-    ini_tillage <- ini * mixing_depth / tillage_depth
-    DT50 <- subset(ai$soil_degradation_endpoints, destination == "PECsoil")$DT50
-    if (length(DT50) > 1) stop("More than one PECsoil DT50 for", ai_name)
-    if (length(DT50) > 0) {
-      if (!is.na(DT50)) {
-        k <- log(2) / DT50
-        plateau_max <- ini_tillage / (1 - exp( - k * interval))
-        plateau_min <- plateau_max *  exp( - k * interval)
-        long_term_max <- plateau_min + ini
-        results[ai_name, c("plateau_max", "plateau_min", "long_term_max")] <- 
-          c(plateau_max, plateau_min, long_term_max)
+  # Temperature correction of degradation (accumulation)
+  if (all(is.na(sce$T_arr))) {   # No temperature correction
+    f_T = 1
+  } else {
+    # Temperature correction as in EFSA 2012 p. 23
+    f_T = ifelse(sce$T_arr == 0, 
+                 0, 
+                 exp(- (65.4 / 0.008314) * (1/(sce$T_arr + 273.15) - 1/293.15)))
+  }
+
+  # X is the fraction left after one period (EFSA guidance p. 23)
+  X = exp(- k * f_T * interval)
+  
+  # f_accu is the fraction left after n periods (X + X^2 + ...)
+  f_accu = 0 
+  if (!is.na(interval)) {
+    if (n_periods == Inf) {
+      f_accu = X/(1 - X)
+    } else {
+      for (i in 1:n_periods) {
+        f_accu = f_accu + X^i
       }
     }
+  }
 
-    for (TP_name in names(ai$TPs)) {
-      TP <- ai$TPs[[TP_name]]
-      max_occurrence = max(subset(ai$transformations, 
-                                  grepl("soil", study_type) & 
-                                  TP_identifier == TP$identifier, max_occurrence))
-      TP_rate <- ai_rate * TP$mw / ai$mw * max_occurrence
-      ini <- PEC_soil(TP_rate, interception = interception, mixing_depth = mixing_depth,
-                      bulk_density = bulk_density)
-      results[TP_name, "compound"] <- TP$identifier
-      results[TP_name, "initial"] <- ini
-
-      ini_tillage <- ini * mixing_depth / tillage_depth
-      DT50 <- subset(TP$soil_degradation_endpoints, destination == "PECsoil")$DT50
-      if (length(DT50) > 1) stop("More than one PECsoil DT50 for", TP_name)
-      if (length(DT50) > 0) {
-        if (!is.na(DT50)) {
-          k <- log(2) / DT50
-          plateau_max <- ini_tillage / (1 - exp( - k * interval))
-          plateau_min <- plateau_max *  exp( - k * interval)
-          results[TP_name, c("plateau_max", "plateau_min")] <- c(plateau_max, plateau_min)
-          long_term_max <- plateau_min + ini
-          results[TP_name, c("plateau_max", "plateau_min", "long_term_max")] <- 
-            c(plateau_max, plateau_min, long_term_max)
-        }
-      }
+  f_tillage = mixing_depth / tillage_depth
+
+  PEC_background = f_accu * f_tillage * PEC_soil_ini
+
+  PEC_soil = (1 + f_accu * f_tillage) * PEC_soil_ini
+
+  # Get porewater PEC if requested
+  if (porewater) {
+
+    # If Kom is not specified, try to get K(f)oc
+    if (is.na(Kom)) {
+      # If Koc not specified, try to get K(f)oc from chent
+      if (is.na(Koc) & is(chent, "chent")) {
+        Koc <- soil_Kfoc(chent)
+      } 
+      Kom <- Koc / 1.724
     }
+
+    if (is.na(Kom)) stop("No Kom information specified")
+
+    PEC_soil = PEC_soil/((sce$theta_fc/sce$rho) + sce$f_om * Kom)
   }
-  return(results)
-}
 
+  # Scenario adjustment factors
+  PEC_soil_sce = PEC_soil * sce$f_sce
+
+  # Model adjustment factors
+  PEC_soil_sce_mod = PEC_soil_sce * sce$f_mod
+
+  result <- matrix(NA, ncol = n_sce, nrow = length(t_avg),
+                   dimnames = list(t_avg = t_avg, scenario = rownames(sce)))
+  
+  result[1, ] <- PEC_soil_sce_mod
+
+  for (i in seq_along(t_avg)) {
+    t_av_i <- t_avg[i]
+    if (t_av_i > 0) {
+      # Equation 10 from p. 24 (EFSA 2015)
+      result[i, ] <- PEC_soil_sce_mod/(t_av_i * f_T * k) * (1 - exp(- f_T * k * t_av_i))
+    }
+  }
+
+  return(result)
+}
diff --git a/pkg/R/PEC_sw_drainage_UK.R b/pkg/R/PEC_sw_drainage_UK.R
index 43c732e..e53f179 100644
--- a/pkg/R/PEC_sw_drainage_UK.R
+++ b/pkg/R/PEC_sw_drainage_UK.R
@@ -25,15 +25,15 @@
 #' @param Koc The sorption coefficient normalised to organic carbon in L/kg
 #' @param latest_application Latest application date, formatted as e.g. "01 July"
 #' @param soil_DT50 Soil degradation half-life, if SFO kinetics are to be used
-#' @param model The degradation model to be used. Either one of "FOMC", "DFOP", 
-#'   "HS", or "IORE", or an mkinmod object
+#' @param model The soil degradation model to be used. Either one of "FOMC",
+#'   "DFOP", "HS", or "IORE", or an mkinmod object
 #' @param model_parms A named numeric vector containing the model parameters
 #' @return The predicted concentration in surface water in µg/L
 #' @export
 #' @author Johannes Ranke
 #' @examples
-#' PEC_sw_drainage_UK_ini(150, Koc = 100)
-PEC_sw_drainage_UK_ini <- function(rate, interception = 0, Koc,
+#' PEC_sw_drainage_UK(150, Koc = 100)
+PEC_sw_drainage_UK <- function(rate, interception = 0, Koc,
                                    latest_application = NULL, soil_DT50 = NULL,
                                    model = NULL, model_parms = NULL)
 {
diff --git a/pkg/R/PEC_sw_drift_ini.R b/pkg/R/PEC_sw_drift_ini.R
deleted file mode 100644
index 67e00d9..0000000
--- a/pkg/R/PEC_sw_drift_ini.R
+++ /dev/null
@@ -1,55 +0,0 @@
-# Copyright (C) 2015  Johannes Ranke
-# Contact: jranke@uni-bremen.de
-# This file is part of the R package pfm
-
-# This program is free software: you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free Software
-# Foundation, either version 3 of the License, or (at your option) any later
-# version.
-
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
-# details.
-
-# You should have received a copy of the GNU General Public License along with
-# this program. If not, see <http://www.gnu.org/licenses/>
-
-#' Calculate initial predicted environmental concentrations in surface water due to drift
-#'
-#' This is a basic, vectorised form of a simple calculation of a contaminant
-#' concentration in surface water based on complete, instantaneous mixing
-#' with input via spray drift.
-#'
-#' @param rate Application rate in units specified below
-#' @param applications Number of applications for selection of drift percentile
-#' @param drift_data Source of drift percentage data
-#' @param crop Crop name (use German names for JKI data), defaults to "Ackerbau"
-#' @param distances The distances in m for which to get PEC values
-#' @param water_depth Depth of the water body in cm
-#' @param rate_units Defaults to g/ha
-#' @param PEC_units Requested units for the calculated PEC. Only µg/L currently supported
-#' @return The predicted concentration in surface water
-#' @export
-#' @author Johannes Ranke
-#' @examples
-#' PEC_sw_drift_ini(100)
-PEC_sw_drift_ini <- function(rate, 
-                         applications = 1,
-                         water_depth = 30, 
-                         drift_data = "JKI",
-                         crop = "Ackerbau",
-                         distances = c(1, 5, 10, 20),
-                         rate_units = "g/ha",
-                         PEC_units = "\u00B5g/L")
-{
-  rate_units <- match.arg(rate_units)
-  PEC_units <- match.arg(PEC_units)
-  drift_data <- match.arg(drift_data)
-  water_volume <- 100 * 100 * (water_depth/100) * 1000   # in L (for 1 ha)
-  PEC_sw_overspray <- rate * 1e6 / water_volume          # in µg/L
-  dist_index <- as.character(distances)
-  PEC_sw_drift <- PEC_sw_overspray * pfm::drift_data_JKI[[applications]][dist_index, crop] / 100
-  names(PEC_sw_drift) <- paste(dist_index, "m")
-  return(PEC_sw_drift)
-}
diff --git a/pkg/R/PEC_sw_sed.R b/pkg/R/PEC_sw_sed.R
index 56396e8..a4a3d6a 100644
--- a/pkg/R/PEC_sw_sed.R
+++ b/pkg/R/PEC_sw_sed.R
@@ -15,8 +15,8 @@
 # You should have received a copy of the GNU General Public License along with
 # this program. If not, see <http://www.gnu.org/licenses/>
 
-#' Calculate initial predicted environmental concentrations in sediment from
-#' surface water concentrations
+#' Calculate predicted environmental concentrations in sediment from surface
+#' water concentrations
 #'
 #' The method 'percentage' is equivalent to what is used in the CRD spreadsheet
 #' PEC calculator
@@ -34,7 +34,7 @@
 #' @export
 #' @author Johannes Ranke
 #' @examples
-#' PEC_sw_sed(PEC_sw_drift_ini(100, distances = 1), percentage = 50)
+#' PEC_sw_sed(PEC_sw_drift(100, distances = 1), percentage = 50)
 PEC_sw_sed <- function(PEC_sw, percentage = 100, method = "percentage", 
                        sediment_depth = 5, water_depth = 30,
                        sediment_density = 1.3,
diff --git a/pkg/R/TOXSWA_cwa.R b/pkg/R/TOXSWA_cwa.R
index 9e23284..df7f627 100644
--- a/pkg/R/TOXSWA_cwa.R
+++ b/pkg/R/TOXSWA_cwa.R
@@ -56,7 +56,7 @@ read.TOXSWA_cwa <- function(filename, basedir = ".", zipfile = NULL,
 #' Plot TOXSWA surface water concentrations
 #'
 #' Plot TOXSWA hourly concentrations of a chemical substance in a specific
-#' segment of a segment of a TOXSWA surface water body.
+#' segment of a TOXSWA surface water body.
 #'
 #' @import graphics
 #' @param x The TOXSWA_cwa object to be plotted.
diff --git a/pkg/R/drift_data_JKI.R b/pkg/R/drift_data_JKI.R
index 549798c..888d3b5 100644
--- a/pkg/R/drift_data_JKI.R
+++ b/pkg/R/drift_data_JKI.R
@@ -39,4 +39,6 @@
 #'   save(drift_data_JKI, file = "data/drift_data_JKI.RData")
 #' }
 #' 
+#' # And this is the resulting data
+#' drift_data_JKI
 NULL
diff --git a/pkg/R/endpoint.R b/pkg/R/endpoint.R
index 6cc253a..fbe9f43 100644
--- a/pkg/R/endpoint.R
+++ b/pkg/R/endpoint.R
@@ -4,6 +4,11 @@
 #' and can hold a list of information loaded from a chemical yaml file in their
 #' chyaml field. Such information is extracted and optionally aggregated by
 #' this function.
+#' 
+#' The functions \code{soil_*} are functions to extract soil specific endpoints.
+#' For the Freundlich exponent, the capital letter \code{N} is used in order to
+#' facilitate dealing with such data in R. In pesticide fate modelling, this
+#' exponent is often called 1/n.
 #'
 #' @import chents
 #' @export
@@ -48,9 +53,8 @@ endpoint <- function(chent,
   else return(signif(aggregator(as.numeric(values)), signif))
 }
 
-#' Obtain soil DT50
-#'
 #' @inheritParams endpoint
+#' @rdname endpoint
 #' @export
 soil_DT50 <- function(chent, aggregator = geomean, signif = 3, 
                       lab_field = "laboratory", value = "DT50ref",
@@ -61,9 +65,8 @@ soil_DT50 <- function(chent, aggregator = geomean, signif = 3,
   return(ep)
 }
 
-#' Obtain soil Kfoc
-#'
 #' @inheritParams endpoint
+#' @rdname endpoint
 #' @export
 soil_Kfoc <- function(chent, aggregator = geomean, signif = 3, 
                       value = "Kfoc", raw = FALSE) {
@@ -72,12 +75,8 @@ soil_Kfoc <- function(chent, aggregator = geomean, signif = 3,
   return(ep)
 }
 
-#' Obtain soil Freundlich exponent
-#'
-#' In pesticide fate modelling, this exponent is often called 1/n. Here, in 
-#' order to facilitate dealing with such data in R, it is called N.
-#'
 #' @inheritParams endpoint
+#' @rdname endpoint
 #' @export
 soil_N <- function(chent, aggregator = mean, signif = 3, raw = FALSE) {
   ep <- endpoint(chent, medium = "soil", type = "sorption", 
@@ -85,9 +84,8 @@ soil_N <- function(chent, aggregator = mean, signif = 3, raw = FALSE) {
   return(ep)
 }
 
-#' Obtain soil sorption data
-#'
 #' @inheritParams endpoint
+#' @rdname endpoint
 #' @param values The values to be returned
 #' @param aggregators A named vector of aggregator functions to be used
 #' @export
diff --git a/pkg/R/pfm_degradation.R b/pkg/R/pfm_degradation.R
index d1d2f9d..6c8610e 100644
--- a/pkg/R/pfm_degradation.R
+++ b/pkg/R/pfm_degradation.R
@@ -29,7 +29,7 @@
 #' @export
 #' @author Johannes Ranke
 #' @examples
-#' pfm_degradation("SFO", DT50 = 10)
+#' head(pfm_degradation("SFO", DT50 = 10))
 pfm_degradation <- function(model = "SFO", DT50 = 1000, parms = c(k_parent_sink = log(2)/DT50),
                             years = 1, step_days = 1,
                             times = seq(0, years * 365, by = step_days))
diff --git a/pkg/R/soil_scenario_data_EFSA_2015.R b/pkg/R/soil_scenario_data_EFSA_2015.R
new file mode 100644
index 0000000..fb096bc
--- /dev/null
+++ b/pkg/R/soil_scenario_data_EFSA_2015.R
@@ -0,0 +1,40 @@
+#' Properties of the predefined scenarios from the EFSA guidance from 2015
+#' 
+#' Properties of the predefined scenarios used at Tier 1, Tier 2A and Tier 3A for the 
+#' concentration in soil as given in the EFSA guidance (2015, p. 13/14). Also, the 
+#' scenario and model adjustment factors from p. 15 and p. 17 are included.
+#' 
+#' @name soil_scenario_data_EFSA_2015
+#' @docType data
+#' @format A data frame with one row for each scenario. Row names are the scenario codes, 
+#'   e.g. CTN for the Northern scenario for the total concentration in soil. Columns are 
+#'   mostly self-explanatory. \code{rho} is the dry bulk density of the top soil.
+#' @source EFSA (European Food Safety Authority) (2015)
+#' EFSA guidance document for predicting environmental concentrations
+#' of active substances of plant protection products and transformation products of these
+#' active substances in soil. \emph{EFSA Journal} \bold{13}(4) 4093
+#' doi:10.2903/j.efsa.2015.4093
+#' @keywords datasets
+#' @examples
+#' \dontrun{
+#'   # This is the code that was used to define the data
+#'   soil_scenario_data_EFSA_2015 <- data.frame(
+#'     Zone = rep(c("North", "Central", "South"), 2),
+#'     Country = c("Estonia", "Germany", "France", "Denmark", "Czech Republik", "Spain"),
+#'     T_arit = c(4.7, 8.0, 11.0, 8.2, 9.1, 12.8),
+#'     T_arr = c(7.0, 10.1, 12.3, 9.8, 11.2, 14.7),
+#'     Texture = c("Coarse", "Coarse", "Medium fine", "Medium", "Medium", "Medium"),
+#'     f_om = c(0.118, 0.086, 0.048, 0.023, 0.018, 0.011),
+#'     theta_fc = c(0.244, 0.244, 0.385, 0.347, 0.347, 0.347),
+#'     rho = c(0.95, 1.05, 1.22, 1.39, 1.43, 1.51),
+#'     f_sce = c(3, 2, 2, 2, 1.5, 1.5),
+#'     f_mod = c(2, 2, 2, 4, 4, 4),
+#'     stringsAsFactors = FALSE,
+#'     row.names = c("CTN", "CTC", "CTS", "CLN", "CLC", "CLS")
+#'   )
+#'   save(soil_scenario_data_EFSA_2015, file = '../data/soil_scenario_data_EFSA_2015.RData')
+#' }
+#'
+#' # And this is the resulting dataframe
+#' soil_scenario_data_EFSA_2015
+NULL