Another overhaul of analytical solutions

Still in preparation for analytical solutions of coupled models

7 files changed, 86 insertions, 61 deletions

diff --git a/man/HS.solution.Rd b/man/HS.solution.Rd
index 343f83f0..f72df23b 100644
--- a/man/HS.solution.Rd
+++ b/man/HS.solution.Rd
@@ -7,10 +7,21 @@
 HS.solution(t, parent_0, k1, k2, tb)
 }
 \arguments{
+\item{t}{Time.}
+
+\item{parent_0}{Starting value for the response variable at time zero.}
+
+\item{k1}{First kinetic constant.}
+
+\item{k2}{Second kinetic constant.}
+
 \item{tb}{Break point. Before this time, exponential decline according to
 \code{k1} is calculated, after this time, exponential decline proceeds
 according to \code{k2}.}
 }
+\value{
+The value of the response variable at time \code{t}.
+}
 \description{
 Function describing two exponential decline functions with a break point
 between them.
@@ -20,6 +31,18 @@ between them.
   plot(function(x) HS.solution(x, 100, 2, 0.3, 0.5), 0, 2, ylim=c(0,100))
 
 }
+\references{
+FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
+  and Degradation Kinetics from Environmental Fate Studies on Pesticides in
+  EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
+  EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,
+  \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
+FOCUS (2014) \dQuote{Generic guidance for Estimating Persistence
+  and Degradation Kinetics from Environmental Fate Studies on Pesticides in
+  EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
+  Version 1.1, 18 December 2014
+  \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
+}
 \seealso{
 Other parent solutions: 
 \code{\link{DFOP.solution}()},
diff --git a/man/SFORB.solution.Rd b/man/SFORB.solution.Rd
index c70ce13b..98a8c684 100644
--- a/man/SFORB.solution.Rd
+++ b/man/SFORB.solution.Rd
@@ -7,6 +7,10 @@
 SFORB.solution(t, parent_0, k_12, k_21, k_1output)
 }
 \arguments{
+\item{t}{Time.}
+
+\item{parent_0}{Starting value for the response variable at time zero.}
+
 \item{k_12}{Kinetic constant describing transfer from free to bound.}
 
 \item{k_21}{Kinetic constant describing transfer from bound to free.}
@@ -30,6 +34,18 @@ and no substance in the bound fraction.
   \dontrun{plot(function(x) SFORB.solution(x, 100, 0.5, 2, 3), 0, 2)}
 
 }
+\references{
+FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
+  and Degradation Kinetics from Environmental Fate Studies on Pesticides in
+  EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
+  EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,
+  \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
+FOCUS (2014) \dQuote{Generic guidance for Estimating Persistence
+  and Degradation Kinetics from Environmental Fate Studies on Pesticides in
+  EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
+  Version 1.1, 18 December 2014
+  \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
+}
 \seealso{
 Other parent solutions: 
 \code{\link{DFOP.solution}()},
diff --git a/man/create_deg_func.Rd b/man/create_deg_func.Rd
new file mode 100644
index 00000000..2eefdb80
--- /dev/null
+++ b/man/create_deg_func.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/create_deg_func.R
+\name{create_deg_func}
+\alias{create_deg_func}
+\title{Create degradation functions for known analytical solutions}
+\usage{
+create_deg_func(spec, use_of_ff = c("min", "max"))
+}
+\arguments{
+\item{spec}{List of model specifications as contained in mkinmod objects}
+
+\item{use_of_ff}{Minimum or maximum use of formation fractions}
+}
+\value{
+Degradation function to be attached to mkinmod objects
+}
+\description{
+Create degradation functions for known analytical solutions
+}
+\examples{
+
+SFO_SFO <- mkinmod(
+  parent = mkinsub("SFO", "m1"),
+  m1 = mkinsub("SFO"))
+fit <- mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE)
+}
diff --git a/man/logistic.solution.Rd b/man/logistic.solution.Rd
index 589ee8ec..33b3d44a 100644
--- a/man/logistic.solution.Rd
+++ b/man/logistic.solution.Rd
@@ -1,12 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/logistic.solution.R, R/parent_solutions.R
+% Please edit documentation in R/parent_solutions.R
 \name{logistic.solution}
 \alias{logistic.solution}
 \title{Logistic kinetics}
 \usage{
 logistic.solution(t, parent_0, kmax, k0, r)
-
-logistic.solution(t, parent_0, kmax, k0, r)
 }
 \arguments{
 \item{t}{Time.}
@@ -18,8 +16,6 @@ logistic.solution(t, parent_0, kmax, k0, r)
 \item{k0}{Minumum rate constant effective at time zero.}
 
 \item{r}{Growth rate of the increase in the rate constant.}
-
-\item{parent.0}{Starting value for the response variable at time zero.}
 }
 \value{
 The value of the response variable at time \code{t}.
@@ -27,16 +23,10 @@ The value of the response variable at time \code{t}.
 \description{
 Function describing exponential decline from a defined starting value, with
 an increasing rate constant, supposedly caused by microbial growth
-
-Function describing exponential decline from a defined starting value, with
-an increasing rate constant, supposedly caused by microbial growth
 }
 \note{
 The solution of the logistic model reduces to the
   \code{\link{SFO.solution}} if \code{k0} is equal to \code{kmax}.
-
-The solution of the logistic model reduces to the
-  \code{\link{SFO.solution}} if \code{k0} is equal to \code{kmax}.
 }
 \examples{
 
@@ -74,43 +64,13 @@ The solution of the logistic model reduces to the
   summary(m)$bpar
   endpoints(m)$distimes
 
-
-  # Reproduce the plot on page 57 of FOCUS (2014)
-  plot(function(x) logistic.solution(x, 100, 0.08, 0.0001, 0.2),
-       from = 0, to = 100, ylim = c(0, 100),
-       xlab = "Time", ylab = "Residue")
-  plot(function(x) logistic.solution(x, 100, 0.08, 0.0001, 0.4),
-       from = 0, to = 100, add = TRUE, lty = 2, col = 2)
-  plot(function(x) logistic.solution(x, 100, 0.08, 0.0001, 0.8),
-       from = 0, to = 100, add = TRUE, lty = 3, col = 3)
-  plot(function(x) logistic.solution(x, 100, 0.08, 0.001, 0.2),
-       from = 0, to = 100, add = TRUE, lty = 4, col = 4)
-  plot(function(x) logistic.solution(x, 100, 0.08, 0.08, 0.2),
-       from = 0, to = 100, add = TRUE, lty = 5, col = 5)
-  legend("topright", inset = 0.05,
-         legend = paste0("k0 = ", c(0.0001, 0.0001, 0.0001, 0.001, 0.08),
-                         ", r = ", c(0.2, 0.4, 0.8, 0.2, 0.2)),
-         lty = 1:5, col = 1:5)
-
-  # Fit with synthetic data
-  logistic <- mkinmod(parent = mkinsub("logistic"))
-
-  sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120)
-  parms_logistic <- c(kmax = 0.08, k0 = 0.0001, r = 0.2)
-  d_logistic <- mkinpredict(logistic,
-    parms_logistic, c(parent = 100),
-    sampling_times)
-  d_2_1 <- add_err(d_logistic,
-    sdfunc = function(x) sigma_twocomp(x, 0.5, 0.07),
-    n = 1, reps = 2, digits = 5, LOD = 0.1, seed = 123456)[[1]]
-
-  m <- mkinfit("logistic", d_2_1, quiet = TRUE)
-  plot_sep(m)
-  summary(m)$bpar
-  endpoints(m)$distimes
-
 }
 \references{
+FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
+  and Degradation Kinetics from Environmental Fate Studies on Pesticides in
+  EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
+  EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,
+  \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
 FOCUS (2014) \dQuote{Generic guidance for Estimating Persistence
   and Degradation Kinetics from Environmental Fate Studies on Pesticides in
   EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
index 020917b9..2ba917d6 100644
--- a/man/mkinmod.Rd
+++ b/man/mkinmod.Rd
@@ -6,7 +6,7 @@
 \usage{
 mkinmod(
   ...,
-  use_of_ff = "min",
+  use_of_ff = "max",
   speclist = NULL,
   quiet = FALSE,
   verbose = FALSE
diff --git a/man/mkinpredict.Rd b/man/mkinpredict.Rd
index 366d5b83..f7e4acfc 100644
--- a/man/mkinpredict.Rd
+++ b/man/mkinpredict.Rd
@@ -102,36 +102,36 @@ kinetic parameters and initial values for the state variables.
 
 SFO <- mkinmod(degradinol = mkinsub("SFO"))
 # Compare solution types
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       solution_type = "analytical")
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       solution_type = "deSolve")
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       solution_type = "deSolve", use_compiled = FALSE)
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       solution_type = "eigen")
 
 # Compare integration methods to analytical solution
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       solution_type = "analytical")[21,]
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       method = "lsoda")[21,]
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       method = "ode45")[21,]
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100), 0:20,
       method = "rk4")[21,]
 # rk4 is not as precise here
 
 # The number of output times used to make a lot of difference until the
 # default for atol was adjusted
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100),
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100),
       seq(0, 20, by = 0.1))[201,]
-mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100),
+mkinpredict(SFO, c(k_degradinol = 0.3), c(degradinol = 100),
       seq(0, 20, by = 0.01))[2001,]
 
 # Check compiled model versions - they are faster than the eigenvalue based solutions!
 SFO_SFO = mkinmod(parent = list(type = "SFO", to = "m1"),
-                  m1 = list(type = "SFO"))
+                  m1 = list(type = "SFO"), use_of_ff = "min")
 if(require(rbenchmark)) {
   benchmark(
     eigen = mkinpredict(SFO_SFO, c(k_parent_m1 = 0.05, k_parent_sink = 0.1, k_m1_sink = 0.01),
diff --git a/man/nlme.Rd b/man/nlme.Rd
index 4a668ac0..a9e368dd 100644
--- a/man/nlme.Rd
+++ b/man/nlme.Rd
@@ -37,15 +37,15 @@ datasets.
 sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120)
 m_SFO <- mkinmod(parent = mkinsub("SFO"))
 d_SFO_1 <- mkinpredict(m_SFO,
-  c(k_parent_sink = 0.1),
+  c(k_parent = 0.1),
   c(parent = 98), sampling_times)
 d_SFO_1_long <- mkin_wide_to_long(d_SFO_1, time = "time")
 d_SFO_2 <- mkinpredict(m_SFO,
-  c(k_parent_sink = 0.05),
+  c(k_parent = 0.05),
   c(parent = 102), sampling_times)
 d_SFO_2_long <- mkin_wide_to_long(d_SFO_2, time = "time")
 d_SFO_3 <- mkinpredict(m_SFO,
-  c(k_parent_sink = 0.02),
+  c(k_parent = 0.02),
   c(parent = 103), sampling_times)
 d_SFO_3_long <- mkin_wide_to_long(d_SFO_3, time = "time")