Add endpoint and GUS functions, roxygenize

21 files changed, 241 insertions, 25 deletions

diff --git a/pkg/man/FOCUS_GW_scenarios_2012.Rd b/pkg/man/FOCUS_GW_scenarios_2012.Rd
index 5fcf4b1..5494d16 100644
--- a/pkg/man/FOCUS_GW_scenarios_2012.Rd
+++ b/pkg/man/FOCUS_GW_scenarios_2012.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/FOCUS_GW_scenarios_2012.R
 \name{FOCUS_GW_scenarios_2012}
 \alias{FOCUS_GW_scenarios_2012}
@@ -7,8 +7,8 @@
 Currently, only a small subset of the soil definitions are provided.
 }
 \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.
+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
 }
 
diff --git a/pkg/man/GUS.Rd b/pkg/man/GUS.Rd
new file mode 100644
index 0000000..5e2c936
--- /dev/null
+++ b/pkg/man/GUS.Rd
@@ -0,0 +1,70 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/GUS.R
+\name{GUS}
+\alias{GUS}
+\alias{GUS.chent}
+\alias{GUS.numeric}
+\title{Groundwater ubiquity score based on Gustafson (1989)}
+\usage{
+GUS(...)
+
+\method{GUS}{numeric}(DT50, Koc)
+
+\method{GUS}{chent}(chent, lab_field = "laboratory", aerobic = TRUE,
+  degradation_value = "DT50ref", sorption_value = "Kfoc",
+  degradation_aggregator = geomean, sorption_aggregator = geomean,
+  digits = 1)
+}
+\arguments{
+\item{DT50}{Half-life of the chemical in soil. Should be a field
+half-life according to Gustafson (1989). However, leaching to the sub-soil
+can not completely be excluded in field dissipation experiments and Gustafson
+did not refer to any normalisation procedure, but says the field study should
+be conducted under use conditions.}
+
+\item{Koc}{The sorption constant normalised to organic carbon. Gustafson
+does not mention the nonlinearity of the sorption constant commonly
+found and usually described by Freundlich sorption, therefore it is 
+unclear at which reference concentration the Koc should be observed
+(and if the reference concentration would be in soil or in porewater).}
+
+\item{chent}{If a chent is given with appropriate information present in its
+chyaml field, this information is used, with defaults specified below.}
+
+\item{lab_field}{Should laboratory or field half-lives be used? This
+defaults to lab in this implementation, in order to avoid
+double-accounting for mobility. If comparability with the original GUS
+values given by Gustafson (1989) is desired, non-normalised first-order
+field half-lives obtained under actual use conditions should be used.}
+
+\item{degradation_value}{Which of the available degradation values should 
+be used?}
+
+\item{sorption_value}{Which of the available sorption values should be used?
+Defaults to Kfoc as this is what is generally available from the European
+pesticide peer review process. These values generally use a reference
+concentration of 1 mg/L in porewater, that means they would be expected to
+be Koc values at a concentration of 1 mg/L in the water phase.}
+
+\item{degradation_aggregator}{Function for aggregating half-lives}
+
+\item{sorption_aggregator}{Function for aggregation Koc values}
+}
+\value{
+A list with the DT50 and Koc used as well as the resulting score
+  of class GUS_result
+}
+\description{
+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)}
+}
+\author{
+Johannes Ranke
+}
+\references{
+Gustafson, David I. (1989) Groundwater ubiquity score: a simple
+method for assessing pesticide leachability. _Environmental
+toxicology and chemistry_ *8*(4) 339–57.
+}
+
diff --git a/pkg/man/PEC_soil.Rd b/pkg/man/PEC_soil.Rd
index 1ced69a..2433ecc 100644
--- a/pkg/man/PEC_soil.Rd
+++ b/pkg/man/PEC_soil.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/PEC_soil.R
 \name{PEC_soil}
 \alias{PEC_soil}
diff --git a/pkg/man/PEC_soil_product.Rd b/pkg/man/PEC_soil_product.Rd
index 28cb5fd..b3afc8e 100644
--- a/pkg/man/PEC_soil_product.Rd
+++ b/pkg/man/PEC_soil_product.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/PEC_soil.R
 \name{PEC_soil_product}
 \alias{PEC_soil_product}
diff --git a/pkg/man/PEC_sw_drainage_UK_ini.Rd b/pkg/man/PEC_sw_drainage_UK_ini.Rd
index 1715b39..c75b846 100644
--- a/pkg/man/PEC_sw_drainage_UK_ini.Rd
+++ b/pkg/man/PEC_sw_drainage_UK_ini.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/PEC_sw_drainage_UK.R
 \name{PEC_sw_drainage_UK_ini}
 \alias{PEC_sw_drainage_UK_ini}
@@ -19,7 +19,7 @@ PEC_sw_drainage_UK_ini(rate, interception = 0, Koc,
 
 \item{soil_DT50}{Soil degradation half-life, if SFO kinetics are to be used}
 
-\item{model}{The degradation model to be used. Either one of "FOMC", "DFOP",
+\item{model}{The degradation model to be used. Either one of "FOMC", "DFOP", 
 "HS", or "IORE", or an mkinmod object}
 
 \item{model_parms}{A named numeric vector containing the model parameters}
diff --git a/pkg/man/PEC_sw_drift.Rd b/pkg/man/PEC_sw_drift.Rd
index 99d3d65..c486831 100644
--- a/pkg/man/PEC_sw_drift.Rd
+++ b/pkg/man/PEC_sw_drift.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/PEC_sw_drift.R
 \name{PEC_sw_drift}
 \alias{PEC_sw_drift}
diff --git a/pkg/man/PEC_sw_drift_ini.Rd b/pkg/man/PEC_sw_drift_ini.Rd
index 994a07e..26ef40a 100644
--- a/pkg/man/PEC_sw_drift_ini.Rd
+++ b/pkg/man/PEC_sw_drift_ini.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/PEC_sw_drift_ini.R
 \name{PEC_sw_drift_ini}
 \alias{PEC_sw_drift_ini}
diff --git a/pkg/man/PEC_sw_sed.Rd b/pkg/man/PEC_sw_sed.Rd
index 515562c..ecd57f5 100644
--- a/pkg/man/PEC_sw_sed.Rd
+++ b/pkg/man/PEC_sw_sed.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/PEC_sw_sed.R
 \name{PEC_sw_sed}
 \alias{PEC_sw_sed}
diff --git a/pkg/man/SFO_actual_twa.Rd b/pkg/man/SFO_actual_twa.Rd
index 7a9c2f1..573ea03 100644
--- a/pkg/man/SFO_actual_twa.Rd
+++ b/pkg/man/SFO_actual_twa.Rd
@@ -1,11 +1,11 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/SFO_actual_twa.R
 \name{SFO_actual_twa}
 \alias{SFO_actual_twa}
 \title{Actual and maximum moving window time average concentrations for SFO kinetics}
 \source{
 FOCUS (2014) Generic Guidance for Estimating Persistence and Degradation
-  Kinetics from Environmental Fate Studies on Pesticides in EU Registratin, Version 1.1,
+  Kinetics from Environmental Fate Studies on Pesticides in EU Registratin, Version 1.1, 
   18 December 2014, p. 251
 }
 \usage{
diff --git a/pkg/man/SSLRC_mobility_classification.Rd b/pkg/man/SSLRC_mobility_classification.Rd
index 0b441ae..04aa01d 100644
--- a/pkg/man/SSLRC_mobility_classification.Rd
+++ b/pkg/man/SSLRC_mobility_classification.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/SSLRC_mobility_classification.R
 \name{SSLRC_mobility_classification}
 \alias{SSLRC_mobility_classification}
@@ -14,7 +14,7 @@ A list containing the classification and the percentage of the
   compound transported per 10 mm drain water
 }
 \description{
-This implements the method specified in the UK data requirements handbook and was
+This implements the method specified in the UK data requirements handbook and was 
 checked against the spreadsheet published on the CRC website
 }
 \examples{
diff --git a/pkg/man/TOXSWA_cwa.Rd b/pkg/man/TOXSWA_cwa.Rd
index b14f654..de87510 100644
--- a/pkg/man/TOXSWA_cwa.Rd
+++ b/pkg/man/TOXSWA_cwa.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/TOXSWA_cwa.R
 \docType{class}
 \name{TOXSWA_cwa}
@@ -26,7 +26,7 @@ Usually, an instance of this class will be generated by \code{\link{read.TOXSWA_
 \item{\code{events}}{List of dataframes holding the event statistics for each threshold.}
 
 \item{\code{windows}}{Matrix of maximum time weighted average concentrations (TWAC_max)
-and areas under the curve in µg/day * h (AUC_max_h) or µg/day * d (AUC_max_d)
+and areas under the curve in µg/day * h (AUC_max_h) or µg/day * d (AUC_max_d) 
 for the requested moving window sizes in days.}
 }}
 \section{Methods}{
@@ -35,7 +35,7 @@ for the requested moving window sizes in days.}
   \item{\code{get_events(threshold, total = FALSE)}}{
         Populate a datataframe with event information for the specified threshold value
         in µg/L. If \code{total = TRUE}, the total concentration including the amount
-        adsorbed to suspended matter will be used. The resulting dataframe is stored in the
+        adsorbed to suspended matter will be used. The resulting dataframe is stored in the 
         \code{events} field of the object.
         }
   \item{\code{moving_windows(windows, total = FALSE)}}{
diff --git a/pkg/man/drift_data_JKI.Rd b/pkg/man/drift_data_JKI.Rd
index d7e6d3b..cc27985 100644
--- a/pkg/man/drift_data_JKI.Rd
+++ b/pkg/man/drift_data_JKI.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/drift_data_JKI.R
 \docType{data}
 \name{drift_data_JKI}
@@ -22,8 +22,11 @@ published by the German Julius-Kühn Institute (JKI).
 The data were extracted from the spreadsheet cited below using the R code
 given in the example section. The spreadsheet is not included in the package
 as its licence is not clear.
+
+
 }
 \examples{
+
 \dontrun{
   # This is the code that was used to extract the data
   library(readxl)
@@ -34,13 +37,14 @@ as its licence is not clear.
 
   for (n in 1:8) {
     drift_data_raw <- read_excel(abdrift_path, sheet = n + 1, skip = 2)
-    drift_data <- as.matrix(drift_data_raw[1:9, 2:4])
+    drift_data <- as.matrix(drift_data_raw[1:9, 2:4]) 
     dimnames(drift_data) <- list(distance = as.integer(drift_data_raw[1:9, 1]),
                                             crop = JKI_crops)
     drift_data_JKI[[n]] <- drift_data
   }
   save(drift_data_JKI, file = "data/drift_data_JKI.RData")
 }
+
 }
 \keyword{datasets}
 
diff --git a/pkg/man/endpoint.Rd b/pkg/man/endpoint.Rd
new file mode 100644
index 0000000..6c93022
--- /dev/null
+++ b/pkg/man/endpoint.Rd
@@ -0,0 +1,45 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{endpoint}
+\alias{endpoint}
+\title{Retrieve endpoint information from the chyaml field of a chent object}
+\usage{
+endpoint(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)
+}
+\arguments{
+\item{chent}{The \code{\link{chent}} object to get the information from}
+
+\item{medium}{The medium for which information is sought}
+
+\item{type}{The information type}
+
+\item{lab_field}{If not NA, do we want laboratory or field endpoints}
+
+\item{redox}{If not NA, are we looking for aerobic or anaerobic data}
+
+\item{value}{The name of the value we want. The list given in the 
+usage section is not exclusive}
+
+\item{aggregator}{The aggregator function. Can be mean, 
+\code{\link{geomean}}, or identity, for example.}
+
+\item{signif}{How many significant digits do we want}
+}
+\value{
+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.
+
+}
+\description{
+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.
+}
+
diff --git a/pkg/man/geomean.Rd b/pkg/man/geomean.Rd
index be9f26a..ed82294 100644
--- a/pkg/man/geomean.Rd
+++ b/pkg/man/geomean.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/geomean.R
 \name{geomean}
 \alias{geomean}
diff --git a/pkg/man/pfm_degradation.Rd b/pkg/man/pfm_degradation.Rd
index 04a692f..6e5ce03 100644
--- a/pkg/man/pfm_degradation.Rd
+++ b/pkg/man/pfm_degradation.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/pfm_degradation.R
 \name{pfm_degradation}
 \alias{pfm_degradation}
diff --git a/pkg/man/plot.TOXSWA_cwa.Rd b/pkg/man/plot.TOXSWA_cwa.Rd
index 8a5ada4..fdc11f5 100644
--- a/pkg/man/plot.TOXSWA_cwa.Rd
+++ b/pkg/man/plot.TOXSWA_cwa.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/TOXSWA_cwa.R
 \name{plot.TOXSWA_cwa}
 \alias{plot.TOXSWA_cwa}
@@ -14,7 +14,7 @@
 \item{time_column}{What should be used for the time axis. If "t_firstjan" is chosen,
 the time is given in days relative to the first of January in the first year.}
 
-\item{xlab,ylab}{Labels for x and y axis.}
+\item{xlab, ylab}{Labels for x and y axis.}
 
 \item{add}{Should we add to an existing plot?}
 
diff --git a/pkg/man/read.TOXSWA_cwa.Rd b/pkg/man/read.TOXSWA_cwa.Rd
index 5d97bb2..acc384c 100644
--- a/pkg/man/read.TOXSWA_cwa.Rd
+++ b/pkg/man/read.TOXSWA_cwa.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/TOXSWA_cwa.R
 \name{read.TOXSWA_cwa}
 \alias{read.TOXSWA_cwa}
@@ -14,7 +14,7 @@ read.TOXSWA_cwa(filename, basedir = ".", zipfile = NULL, segment = "last",
 
 \item{zipfile}{Optional path to a zip file containing the cwa file.}
 
-\item{segment}{The segment for which the data should be read. Either "last", or
+\item{segment}{The segment for which the data should be read. Either "last", or 
 the segment number.}
 
 \item{windows}{Numeric vector of width of moving windows in days, for calculating
diff --git a/pkg/man/soil_DT50.Rd b/pkg/man/soil_DT50.Rd
new file mode 100644
index 0000000..cbec234
--- /dev/null
+++ b/pkg/man/soil_DT50.Rd
@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{soil_DT50}
+\alias{soil_DT50}
+\title{Obtain soil DT50}
+\usage{
+soil_DT50(chent, aggregator = geomean, signif = 3,
+  lab_field = "laboratory", value = "DT50ref", redox = "aerobic",
+  raw = FALSE)
+}
+\arguments{
+\item{chent}{The \code{\link{chent}} object to get the information from}
+
+\item{aggregator}{The aggregator function. Can be mean, 
+\code{\link{geomean}}, or identity, for example.}
+
+\item{signif}{How many significant digits do we want}
+
+\item{lab_field}{If not NA, do we want laboratory or field endpoints}
+
+\item{value}{The name of the value we want. The list given in the 
+usage section is not exclusive}
+
+\item{redox}{If not NA, are we looking for aerobic or anaerobic data}
+}
+\description{
+Obtain soil DT50
+}
+
diff --git a/pkg/man/soil_Kfoc.Rd b/pkg/man/soil_Kfoc.Rd
new file mode 100644
index 0000000..3cc67cd
--- /dev/null
+++ b/pkg/man/soil_Kfoc.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{soil_Kfoc}
+\alias{soil_Kfoc}
+\title{Obtain soil Kfoc}
+\usage{
+soil_Kfoc(chent, aggregator = geomean, signif = 3, value = "Kfoc",
+  raw = FALSE)
+}
+\arguments{
+\item{chent}{The \code{\link{chent}} object to get the information from}
+
+\item{aggregator}{The aggregator function. Can be mean, 
+\code{\link{geomean}}, or identity, for example.}
+
+\item{signif}{How many significant digits do we want}
+
+\item{value}{The name of the value we want. The list given in the 
+usage section is not exclusive}
+}
+\description{
+Obtain soil Kfoc
+}
+
diff --git a/pkg/man/soil_N.Rd b/pkg/man/soil_N.Rd
new file mode 100644
index 0000000..9045ea8
--- /dev/null
+++ b/pkg/man/soil_N.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{soil_N}
+\alias{soil_N}
+\title{Obtain soil Freundlich exponent}
+\usage{
+soil_N(chent, aggregator = mean, signif = 3, raw = FALSE)
+}
+\arguments{
+\item{chent}{The \code{\link{chent}} object to get the information from}
+
+\item{aggregator}{The aggregator function. Can be mean, 
+\code{\link{geomean}}, or identity, for example.}
+
+\item{signif}{How many significant digits do we want}
+}
+\description{
+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.
+}
+
diff --git a/pkg/man/soil_sorption.Rd b/pkg/man/soil_sorption.Rd
new file mode 100644
index 0000000..41b8794
--- /dev/null
+++ b/pkg/man/soil_sorption.Rd
@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{soil_sorption}
+\alias{soil_sorption}
+\title{Obtain soil sorption data}
+\usage{
+soil_sorption(chent, values = c("Kfoc", "N"), aggregators = c(Kfoc =
+  geomean, Koc = geomean, N = mean), signif = rep(3, length(values)),
+  raw = FALSE)
+}
+\arguments{
+\item{chent}{The \code{\link{chent}} object to get the information from}
+
+\item{values}{The values to be returned}
+
+\item{aggregators}{A named vector of aggregator functions to be used}
+
+\item{signif}{How many significant digits do we want}
+}
+\description{
+Obtain soil sorption data
+}
+