Add endpoint and GUS functions, roxygenize

1 files changed, 102 insertions, 0 deletions

diff --git a/pkg/R/endpoint.R b/pkg/R/endpoint.R
new file mode 100644
index 0000000..f9b9102
--- /dev/null
+++ b/pkg/R/endpoint.R
@@ -0,0 +1,102 @@
+#' Retrieve endpoint information from the chyaml field of a chent object
+#'
+#' R6 class objects of class \code{\link{chent}} represent chemical entities
+#' 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.
+#'
+#' @import chents
+#' @export
+#' @param chent The \code{\link{chent}} object to get the information from
+#' @param medium The medium for which information is sought
+#' @param type The information type
+#' @param lab_field If not NA, do we want laboratory or field endpoints
+#' @param redox If not NA, are we looking for aerobic or anaerobic data
+#' @param value The name of the value we want. The list given in the 
+#'   usage section is not exclusive
+#' @param aggregator The aggregator function. Can be mean, 
+#'   \code{\link{geomean}}, or identity, for example.
+#' @param signif How many significant digits do we want
+#' @return The result from applying the aggregator function to
+#'   the values converted to a numeric vector, rounded to the
+#'   given number of significant digits, or, if raw = TRUE,
+#'   the values as a character value, retaining any implicit
+#'   information on precision that may be present.
+#' 
+endpoint <- function(chent, 
+                     medium = "soil",
+                     type = c("degradation", "sorption"), 
+                     lab_field = c(NA, "laboratory", "field"),
+                     redox = c(NA, "aerobic", "anaerobic"),
+                     value = c("DT50ref", "Kfoc", "N"),
+                     aggregator = geomean,
+                     raw = FALSE,
+                     signif = 3)
+{
+  ep_list <- chent$chyaml[[medium]][[type]] 
+  if (!is.na(lab_field[1])) {
+    ep_list <- ep_list[[lab_field]]
+  }
+  if (!is.na(redox[1])) {
+    ep_list <- ep_list[[redox]]
+  }
+  values <- ep_list$data[[value]]
+  if (raw) return(values)
+  else return(signif(aggregator(as.numeric(values)), signif))
+}
+
+#' Obtain soil DT50
+#'
+#' @inheritParams endpoint
+#' @export
+soil_DT50 <- function(chent, aggregator = geomean, signif = 3, 
+                      lab_field = "laboratory", value = "DT50ref",
+                      redox = "aerobic", raw = FALSE) {
+  ep <- endpoint(chent, medium = "soil", type = "degradation", 
+                 lab_field = "laboratory", redox = redox,
+                 value = value, aggregator = aggregator, raw = raw)
+  return(ep)
+}
+
+#' Obtain soil Kfoc
+#'
+#' @inheritParams endpoint
+#' @export
+soil_Kfoc <- function(chent, aggregator = geomean, signif = 3, 
+                      value = "Kfoc", raw = FALSE) {
+  ep <- endpoint(chent, medium = "soil", type = "sorption", 
+                 value = value, aggregator = aggregator, raw = raw)
+  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
+#' @export
+soil_N <- function(chent, aggregator = mean, signif = 3, raw = FALSE) {
+  ep <- endpoint(chent, medium = "soil", type = "sorption", 
+                 value = "N", aggregator = aggregator, raw = raw)
+  return(ep)
+}
+
+#' Obtain soil sorption data
+#'
+#' @inheritParams endpoint
+#' @param values The values to be returned
+#' @param aggregators A named vector of aggregator functions to be used
+#' @export
+soil_sorption <- function(chent, values = c("Kfoc", "N"), 
+                          aggregators = c(Kfoc = geomean, Koc = geomean, N = mean), 
+                          signif = rep(3, length(values)),
+                          raw = FALSE) {
+  res <- sapply(values, 
+                function(x) {
+                  endpoint(chent, medium = "soil", type = "sorption",
+                           value = x, aggregator = aggregators[[x]], raw = raw)
+                }
+  )
+  return(res)
+}