Finish the Step 1 calculator including tests

Some cleaning up. PELMO facilities do not currently work at my end,
as I have no working wine installation on this computer

8 files changed, 111 insertions, 16 deletions

diff --git a/man/FOCUS_GW_scenarios_2012.Rd b/man/FOCUS_GW_scenarios_2012.Rd
index a19bbe5..4529816 100644
--- a/man/FOCUS_GW_scenarios_2012.Rd
+++ b/man/FOCUS_GW_scenarios_2012.Rd
@@ -3,7 +3,7 @@
 \docType{data}
 \name{FOCUS_GW_scenarios_2012}
 \alias{FOCUS_GW_scenarios_2012}
-\title{A very small subset of the FOCUS Groundwater scenario defitions}
+\title{A very small subset of the FOCUS Groundwater scenario definitions}
 \format{An object of class \code{list} of length 2.}
 \usage{
 FOCUS_GW_scenarios_2012
diff --git a/man/FOCUS_Step_12_scenarios.Rd b/man/FOCUS_Step_12_scenarios.Rd
new file mode 100644
index 0000000..f58dea7
--- /dev/null
+++ b/man/FOCUS_Step_12_scenarios.Rd
@@ -0,0 +1,40 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/FOCUS_Step_12_scenarios.R
+\docType{data}
+\name{FOCUS_Step_12_scenarios}
+\alias{FOCUS_Step_12_scenarios}
+\title{Step 1/2 scenario data as distributed with the FOCUS Step 1/2 calculator}
+\format{A list containing the scenario names in a character vector called 'names',
+  the drift percentiles in a matrix called 'drift', interception percentages in
+  a matrix called 'interception' and the runoff/drainage percentages for Step 2
+  calculations in a matrix called 'rd'.}
+\description{
+The data were extracted from the scenario.txt file using the R code shown below.
+The text file 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
+  scenario_path <- "inst/extdata/FOCUS_Step_12_scenarios.txt"
+  scenarios <- readLines(scenario_path)[9:38]
+  FOCUS_Step_12_scenarios <- list()
+  sce <- read.table(text = scenarios, sep = "\\t", header = TRUE, check.names = FALSE,
+    stringsAsFactors = FALSE)
+  FOCUS_Step_12_scenarios$names = sce$Crop
+  rownames(sce) <- sce$Crop
+  FOCUS_Step_12_scenarios$drift = sce[, 3:11]
+  FOCUS_Step_12_scenarios$interception = sce[, 12:15]
+  sce_2 <- readLines(scenario_path)[41:46]
+  rd <- read.table(text = sce_2, sep = "\\t")[1:2]
+  rd_mat <- matrix(rd$V2, nrow = 3, byrow = FALSE)
+  dimnames(rd_mat) = list(Time = c("Oct-Feb", "Mar-May", "Jun-Sep"),
+                          Region = c("North", "South"))
+  FOCUS_Step_12_scenarios$rd = rd_mat
+  save(FOCUS_Step_12_scenarios, file = "data/FOCUS_Step_12_scenarios.RData")
+}
+
+# And this is the resulting data
+FOCUS_Step_12_scenarios
+}
+\keyword{datasets}
diff --git a/man/PEC_sw_focus.Rd b/man/PEC_sw_focus.Rd
index 0f444ca..22c20c5 100644
--- a/man/PEC_sw_focus.Rd
+++ b/man/PEC_sw_focus.Rd
@@ -4,9 +4,8 @@
 \alias{PEC_sw_focus}
 \title{Calculate FOCUS Step 1 PEC surface water}
 \usage{
-PEC_sw_focus(parent, rate, n = 1, i = NA, applications = data.frame(time =
-  seq(0, 0 + n * i, length.out = n), amount = rate), met = NULL, step = 1,
-  f_drift = 0.02759, f_rd = 0.1)
+PEC_sw_focus(parent, rate, n = 1, i = NA, met = NULL, f_drift = NA,
+  f_rd = 0.1, scenario = FOCUS_Step_12_scenarios$names)
 }
 \arguments{
 \item{parent}{A list containing substance specific parameters}
@@ -18,19 +17,51 @@ applications are given explicitly}
 
 \item{i}{The application interval}
 
-\item{applications}{A dataframe containing times and amounts of each application}
+\item{met}{A list containing metabolite specific parameters. If not NULL, 
+the PEC is calculated for this compound, not the parent.}
 
-\item{step}{At the moment, only Step 1 is implemented}
+\item{f_drift}{The fraction of the application rate reaching the waterbody
+via drift. If NA, this is derived from the scenario name and the number
+of applications via the drift data defined by the 
+\code{\link{FOCUS_Step_12_scenarios}}}
+
+\item{f_rd}{The fraction of the amount applied reaching the waterbody via
+runoff/drainage. At Step 1, it is assumed to be 10%, be it the
+parent or a metabolite}
+
+\item{scenario}{The name of the scenario. Must be one of the scenario
+names given in \code{\link{FOCUS_Step_12_scenarios}}}
 }
 \description{
-This is an attempt to reimplement the FOCUS Step 1 and 2 calculator authored
-by Michael Klein. The Step 1 and 2 scenario assumes an area ratio of 10:1
-between field and waterbody, and a water depth of 30 cm.
-I did not (yet) implement the TWA formulas for times later than day 1, as I
-did not understand them right away.
-Also, Step 2 is not implemented (yet).
+This is reimplementation of Step 1 of the FOCUS Step 1 and 2 calculator
+version 3.2, authored by Michael Klein. Note that results for multiple
+applications should be compared to the corresponding results for a
+single application. At current, this is not done automatically in
+this implementation.
+}
+\note{
+The formulas for input to the waterbody via runoff/drainage of the
+  parent and subsequent formation of the metabolite in water is not
+  documented in the model description coming with the calculator
+
+Step 2 is not implemented
 }
 \examples{
+# Parent only
 dummy_1 <- chent_focus_sw(cwsat = 6000, DT50_ws = 6, Koc = 344.8)
 PEC_sw_focus(dummy_1, 3000, f_drift = 0)
+
+# Metabolite
+new_dummy <- chent_focus_sw(mw = 250, Koc = 100)
+M1 <- chent_focus_sw(mw = 100, cwsat = 100, DT50_ws = 100, Koc = 50, max_ws = 0, max_soil = 0.5)
+PEC_sw_focus(new_dummy, 1000, scenario = "cereals, winter", met = M1)
+}
+\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
+
+Website of the Steps 1 and 2 calculator at the Joint Research
+  Center of the European Union:
+  http://esdac.jrc.ec.europa.eu/projects/stepsonetwo
 }
diff --git a/man/PELMO_runs.Rd b/man/PELMO_runs.Rd
index aa02a89..a0d0df8 100644
--- a/man/PELMO_runs.Rd
+++ b/man/PELMO_runs.Rd
@@ -44,7 +44,7 @@ If evaluate is TRUE, a list of lists of matrices holding the
 Per default, the runs are not only set up but also executed with FOCUS
 PELMO, the results are processed and returned. Currently, only FOCUS PELMO
 as installed on Linux (or other Unix systems)
-using the \code{\link{install_PELMO}} from the \code{PELMO.installeR} package
+using the \code{install_PELMO} from the \code{PELMO.installeR} package
 maintained on github is supported. In such installations, FOCUS PELMO is
 installed into the package installation directory of \code{PELMO.installeR}
 and run using \code{wine}.
@@ -55,6 +55,8 @@ run directory, holding the results for all FOCUS periods, equivalent to
 the period.plm file generated by the FOCUS PELMO GUI.
 }
 \examples{
+# At the moment I can not run the examples, as my wine installation is not working
+\dontrun{
 # Reproduce the official test results for annual application of Pesticide D
 # to winter cereals at the day before emergence
 runs_1 <- list(
@@ -77,6 +79,7 @@ PECgw_2 <- PELMO_runs(runs_2, psm_dir = system.file("testdata", package = "pfm")
   cores = 3, overwrite = TRUE)
 print(PECgw_2)
 }
+}
 \references{
 PELMO.installeR \url{https://jranke.github.io/PELMO.installeR}
 
diff --git a/man/chent_focus_sw.Rd b/man/chent_focus_sw.Rd
index 26742d0..945c343 100644
--- a/man/chent_focus_sw.Rd
+++ b/man/chent_focus_sw.Rd
@@ -2,9 +2,10 @@
 % Please edit documentation in R/PEC_sw_focus.R
 \name{chent_focus_sw}
 \alias{chent_focus_sw}
-\title{Create an chemical compound object for FOCUS Step 1 and 2 calculations}
+\title{Create a chemical compound object for FOCUS Step 1 calculations}
 \usage{
-chent_focus_sw(Koc, DT50_ws, cwsat = 1000)
+chent_focus_sw(Koc, DT50_ws = NA, cwsat = 1000, mw = NA, max_soil = 1,
+  max_ws = 1)
 }
 \arguments{
 \item{Koc}{Partition coefficient between organic carbon and water
@@ -13,10 +14,17 @@ in L/kg.}
 \item{DT50_ws}{Half-life in water/sediment systems in days}
 
 \item{cwsat}{Water solubility in mg/L}
+
+\item{mw}{Molar weight in g/mol}
+
+\item{max_soil}{Maximum observed fraction (dimensionless) in soil}
+
+\item{max_ws}{Maximum observed fraction (dimensionless) in water/sediment
+systems}
 }
 \value{
 A list with the substance specific properties
 }
 \description{
-Create an chemical compound object for FOCUS Step 1 and 2 calculations
+Create a chemical compound object for FOCUS Step 1 calculations
 }
diff --git a/man/get_flux.Rd b/man/get_flux.Rd
index 93778cb..c56b891 100644
--- a/man/get_flux.Rd
+++ b/man/get_flux.Rd
@@ -6,6 +6,9 @@
 \usage{
 get_flux(chem_file)
 }
+\arguments{
+\item{chem_file}{The full path to a CHEM*.PLM file}
+}
 \description{
 Get the flux of a chemical out of the FOCUS layer from a CHEM*.PLM file
 }
diff --git a/man/get_interval.Rd b/man/get_interval.Rd
index a751996..519cf36 100644
--- a/man/get_interval.Rd
+++ b/man/get_interval.Rd
@@ -6,6 +6,11 @@
 \usage{
 get_interval(psm_file, location_code)
 }
+\arguments{
+\item{psm_file}{The path to the .psm file}
+
+\item{location_code}{The location code}
+}
 \description{
 Get the application interval in years from a psm file
 }
diff --git a/man/sum_periods.Rd b/man/sum_periods.Rd
index 5051af4..21bd2c9 100644
--- a/man/sum_periods.Rd
+++ b/man/sum_periods.Rd
@@ -6,6 +6,11 @@
 \usage{
 sum_periods(annual, interval)
 }
+\arguments{
+\item{annual}{The annual flux as obtained by \code{get_flux}}
+
+\item{interval}{The interval in years}
+}
 \description{
 Sum up values according to FOCUS periods
 }