Improve docs, fail with erroneus crop_group arguments

PEC_sw_drift: The argument 'crop_group_focus' was renamed
to 'crop_group_RF' to make it easier to understand the
relation to the 'drift_data' argument.

2 files changed, 32 insertions, 26 deletions

diff --git a/R/PEC_sw_drift.R b/R/PEC_sw_drift.R
index 22aa012..c1b24d3 100644
--- a/R/PEC_sw_drift.R
+++ b/R/PEC_sw_drift.R
@@ -14,7 +14,7 @@
 #'   either in the original form or integrated over the width of the water body, depending
 #'   on the 'formula' argument.
 #' @param crop_group_JKI When using the 'JKI' drift data, one of the German names
-#'   as used in [drift_parameters_focus].
+#'   as used in [drift_parameters_focus]. Will only be used if drift_data is 'JKI'.
 #' @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
@@ -34,13 +34,13 @@
 #' PEC_sw_drift(100, distances = c(1, 3, 5, 6, 10, 20, 50, 100), drift_data = "RF")
 #'
 #' # or consider aerial application
-#' PEC_sw_drift(100, distances = c(1, 3, 5, 6, 10, 20, 50, 100), drift_data = "RF", 
-#'   crop_group_focus = "aerial")
+#' PEC_sw_drift(100, distances = c(1, 3, 5, 6, 10, 20, 50, 100), drift_data = "RF",
+#'   crop_group_RF = "aerial")
 #'
 #' # Using custom drift percentages is also supported
 #' PEC_sw_drift(100, drift_percentages = c(2.77, 0.95, 0.57, 0.48, 0.29, 0.15, 0.06, 0.03))
 #'
-#' # The influence of assuming a 45° angle of the sides of the waterbody and the width of the 
+#' # The influence of assuming a 45° angle of the sides of the waterbody and the width of the
 #' # waterbody can be illustrated
 #' PEC_sw_drift(100)
 #' PEC_sw_drift(100, drift_data = "RF")
@@ -52,10 +52,10 @@ PEC_sw_drift <- function(rate,
   water_depth = 30,
   drift_percentages = NULL,
   drift_data = c("JKI", "RF"),
-  crop_group_JKI = c("Ackerbau", 
+  crop_group_JKI = c("Ackerbau",
     "Obstbau frueh", "Obstbau spaet", "Weinbau frueh", "Weinbau spaet",
     "Hopfenbau", "Flaechenkulturen > 900 l/ha", "Gleisanlagen"),
-  crop_group_focus = c("arable", "hops", "vines, late", "vines, early", 
+  crop_group_RF = c("arable", "hops", "vines, late", "vines, early",
     "fruit, late", "fruit, early", "aerial"),
   distances = c(1, 5, 10, 20),
   formula = c("Rautmann", "FOCUS"),
@@ -68,7 +68,13 @@ PEC_sw_drift <- function(rate,
   PEC_units <- match.arg(PEC_units)
   drift_data <- match.arg(drift_data)
   crop_group_JKI <- match.arg(crop_group_JKI)
-  crop_group_focus <- match.arg(crop_group_focus)
+  crop_group_RF <- match.arg(crop_group_RF)
+  if (drift_data == "JKI" & crop_group_RF != "arable") {
+    stop("Specifying crop_group_RF only makes sense if 'RF' is used for 'drift_data'")
+  }
+  if (drift_data == "RF" & crop_group_JKI != "Ackerbau") {
+    stop("Specifying crop_group_JKI only makes sense if 'JKI' is used for 'drift_data'")
+  }
   formula <- match.arg(formula)
   if (side_angle < 0 | side_angle > 90) stop("The side anglemust be between 0 and 90 degrees")
   mean_water_width <- if (side_angle == 90) water_width
@@ -80,9 +86,9 @@ PEC_sw_drift <- function(rate,
   if (is.null(drift_percentages)) {
     drift_percentages <- switch(drift_data,
       JKI = pfm::drift_data_JKI[[applications]][dist_index, crop_group_JKI],
-      RF =  drift_percentages_rautmann(distances, applications, 
+      RF =  drift_percentages_rautmann(distances, applications,
         formula = formula,
-        crop_group_focus, widths = water_width/100)
+        crop_group_RF, widths = water_width/100)
     )
     names(drift_percentages) <- paste(dist_index, "m")
   } else {
@@ -101,14 +107,14 @@ PEC_sw_drift <- function(rate,
 #' @param distances The distances in m for which to get PEC values
 #' @param widths The widths of the water bodies (only used in the FOCUS formula)
 #' @param applications Number of applications for selection of drift percentile
-#' @param crop_group_focus One of the crop groups as used in [drift_parameters_focus]
+#' @param crop_group_RF One of the crop groups as used in [drift_parameters_focus]
 #' @seealso [drift_parameters_focus], [PEC_sw_drift]
 #' @references FOCUS (2014) Generic guidance for Surface Water Scenarios (version 1.4).
 #' FOrum for the Co-ordination of pesticde fate models and their USe.
 #' <http://esdac.jrc.ec.europa.eu/public_path/projects_data/focus/sw/docs/Generic%20FOCUS_SWS_vc1.4.pdf>
 #' @export
 #' @examples
-#' # Compare JKI data with Rautmann formula
+#' # Compare JKI data with Rautmann and FOCUS formulas for arable crops (default)
 #' # One application on field crops, for 1 m, 3 m and 5 m distance
 #' drift_data_JKI[[1]][as.character(c(1, 3, 5)), "Ackerbau"]
 #' drift_percentages_rautmann(c(1, 3, 5))
@@ -116,31 +122,31 @@ PEC_sw_drift <- function(rate,
 #'
 #' # One application to early or late fruit crops
 #' drift_data_JKI[[1]][as.character(c(3, 5, 20, 50)), "Obstbau frueh"]
-#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group = "fruit, early")
-#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group = "fruit, early",
+#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group_RF = "fruit, early")
+#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group_RF = "fruit, early",
 #'   formula = "FOCUS")
 #' drift_data_JKI[[1]][as.character(c(3, 5, 20, 50)), "Obstbau spaet"]
-#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group = "fruit, late")
-#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group = "fruit, late",
+#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group_RF = "fruit, late")
+#' drift_percentages_rautmann(c(3, 5, 20, 50), crop_group_RF = "fruit, late",
 #'   formula = "FOCUS")
-#' 
+#'
 #' # We get a continuum if the waterbody covers the hinge distance
 #' # (11.4 m for 1 early app to fruit)
 #' x <- seq(3, 30, by = 0.1)
-#' d <- drift_percentages_rautmann(x, crop_group = "fruit, early", formula = "FOCUS")
+#' d <- drift_percentages_rautmann(x, crop_group_RF = "fruit, early", formula = "FOCUS")
 #' plot(x, d, type = "l",
-#'   xlab = "Distance of near edge [m]", 
+#'   xlab = "Distance of near edge [m]",
 #'   ylab = "Mean drift percentage over waterbody width",
 #'   main = "One application to fruit, early")
 #' abline(v = 11.4, lty = 2)
-drift_percentages_rautmann <- function(distances, applications = 1, 
-  crop_group_focus = c("arable", "hops", "vines, late", "vines, early", "fruit, late",
+drift_percentages_rautmann <- function(distances, applications = 1,
+  crop_group_RF = c("arable", "hops", "vines, late", "vines, early", "fruit, late",
     "fruit, early", "aerial"),
   formula = c("Rautmann", "FOCUS"),
   widths = 1
 )
 {
-  cg <- match.arg(crop_group_focus)
+  cg <- match.arg(crop_group_RF)
   if (!applications %in% 1:8) stop("Only 1 to 8 applications are supported")
   formula <- match.arg(formula)
 
@@ -161,7 +167,7 @@ drift_percentages_rautmann <- function(distances, applications = 1,
       ifelse(z2 < hinge,
         # farther edge closer than hinge distance
         A/(widths * (B + 1)) * (z2^(B + 1) - z1^(B + 1)),
-        ifelse(z1 < hinge, 
+        ifelse(z1 < hinge,
           # hinge distance in waterbody (between z1 and z2)
           (A/(B + 1) * (H^(B + 1) - z1^(B + 1)) + C/(D + 1) * (z2^(D + 1) - H^(D + 1)))/widths,
           # z1 >= hinge, i.e. near edge farther than hinge distance
diff --git a/R/PEC_sw_exposit_runoff.R b/R/PEC_sw_exposit_runoff.R
index 8b89cd9..877dd92 100644
--- a/R/PEC_sw_exposit_runoff.R
+++ b/R/PEC_sw_exposit_runoff.R
@@ -137,10 +137,10 @@ PEC_sw_exposit_runoff <- function(rate, interception = 0, Koc, DT50 = Inf, t_run
 #' @param dilution The dilution factor
 #' @return A list containing the following components
 #'   \describe{
-#'     \item{perc_runoff}{The runoff percentages for dissolved and bound substance}
-#'     \item{runoff}{A matrix containing dissolved and bound input for the different distances}
-#'     \item{PEC_sw_runoff}{A matrix containing PEC values for dissolved and bound substance
-#'       for the different distances. If the rate was given in g/ha, the PECsw are in microg/L.}
+#'     \item{perc_drainage_total}{Gesamtaustrag (total fraction of the residue drained)}
+#'     \item{perc_peak}{Stoßbelastung (fraction drained at event)}
+#'     \item{PEC_sw_drainage}{A matrix containing PEC values for the spring and autumn
+#'       scenarios. If the rate was given in g/ha, the PECsw are in microg/L.}
 #'   }
 #' @export
 #' @source Excel 3.02 spreadsheet available from