aboutsummaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/DFOP.solution.Rd36
-rw-r--r--man/FOCUS_2006_datasets.Rd2
-rw-r--r--man/FOMC.solution.Rd49
-rw-r--r--man/HS.solution.Rd34
-rw-r--r--man/SFO.solution.Rd29
-rw-r--r--man/SFORB.solution.Rd36
-rw-r--r--man/mkin_long_to_wide.Rd7
-rw-r--r--man/mkinerrmin.Rd1
-rw-r--r--man/mkinfit.Rd31
-rw-r--r--man/mkinmod.Rd18
-rw-r--r--man/mkinplot.Rd6
-rw-r--r--man/mkinresplot.Rd64
-rw-r--r--man/mkinstart.Rd38
-rw-r--r--man/summary.mkinfit.Rd16
14 files changed, 344 insertions, 23 deletions
diff --git a/man/DFOP.solution.Rd b/man/DFOP.solution.Rd
new file mode 100644
index 00000000..d30cf7f3
--- /dev/null
+++ b/man/DFOP.solution.Rd
@@ -0,0 +1,36 @@
+\name{DFOP.solution}
+\Rdversion{1.1}
+\alias{DFOP.solution}
+\title{
+Dual First-Order in Parallel kinetics
+}
+\description{
+ Function describing decline from a defined starting value using the sum
+ of two exponential decline functions.
+}
+\usage{
+DFOP.solution(t, parent.0, k1, k2, g)
+}
+\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{g}{ Fraction of the starting value declining according to the
+ first kinetic constant.
+ }
+}
+\value{
+ The value of the response variable at time \code{t}.
+}
+\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://focus.jrc.ec.europa.eu/dk}
+}
+\examples{
+ \dontrun{plot(function(x) DFOP.solution(x, 100, 5, 0.5, 0.3), 0, 4, ylim=c(0,100))}
+}
+\keyword{ manip }
diff --git a/man/FOCUS_2006_datasets.Rd b/man/FOCUS_2006_datasets.Rd
index 04565f74..5053b880 100644
--- a/man/FOCUS_2006_datasets.Rd
+++ b/man/FOCUS_2006_datasets.Rd
@@ -11,7 +11,7 @@
Datasets A to F from the FOCUS Kinetics report from 2006
}
\description{
-Data taken from an FOCUS (2006), p. 258.
+Data taken from FOCUS (2006), p. 258.
}
\usage{FOCUS_2006_datasets}
\format{
diff --git a/man/FOMC.solution.Rd b/man/FOMC.solution.Rd
new file mode 100644
index 00000000..d04d34e1
--- /dev/null
+++ b/man/FOMC.solution.Rd
@@ -0,0 +1,49 @@
+\name{FOMC.solution}
+\Rdversion{1.1}
+\alias{FOMC.solution}
+\title{ First-Order Multi-Compartment kinetics }
+\description{
+ Function describing exponential decline from a defined starting value, with
+ a decreasing rate constant.
+
+ The form given here differs slightly from the original reference by Gustafson
+ and Holden (1990). The parameter \code{beta} corresponds to 1/beta in the
+ original equation.
+}
+\usage{
+FOMC.solution(t, parent.0, alpha, beta)
+}
+\arguments{
+ \item{t}{ Time. }
+ \item{parent.0}{ Starting value for the response variable at time zero. }
+ \item{alpha}{
+ Shape parameter determined by coefficient of variation of rate constant
+ values. }
+ \item{beta}{
+ Location parameter.
+}
+}
+\note{
+ The solution of the FOMC kinetic model reduces to the
+ \code{\link{SFO.solution}} for large values of \code{alpha} and
+ \code{beta} with
+ \eqn{k = \frac{\beta}{\alpha}}{k = beta/alpha}.
+}
+\value{
+ The value of the response variable at time \code{t}.
+}
+\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://focus.jrc.ec.europa.eu/dk}
+
+ Gustafson DI and Holden LR (1990) Nonlinear pesticide dissipation in soil: A
+ new model based on spatial variability. \emph{Environmental Science and
+ Technology} \bold{24}, 1032-1038
+}
+\examples{
+ \dontrun{plot(function(x) FOMC.solution(x, 100, 10, 2), 0, 2)}
+}
+\keyword{ manip }
diff --git a/man/HS.solution.Rd b/man/HS.solution.Rd
new file mode 100644
index 00000000..71f68a1e
--- /dev/null
+++ b/man/HS.solution.Rd
@@ -0,0 +1,34 @@
+\name{HS.solution}
+\Rdversion{1.1}
+\alias{HS.solution}
+\title{ Hockey-Stick kinetics }
+\description{
+ Function describing two exponential decline functions with a break point
+ between them.
+}
+\usage{
+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}.
+}
+\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://focus.jrc.ec.europa.eu/dk}
+}
+\examples{
+ \dontrun{plot(function(x) HS.solution(x, 100, 2, 0.3, 0.5), 0, 2, ylim=c(0,100))}
+}
+\keyword{ manip }
diff --git a/man/SFO.solution.Rd b/man/SFO.solution.Rd
new file mode 100644
index 00000000..41a9ba96
--- /dev/null
+++ b/man/SFO.solution.Rd
@@ -0,0 +1,29 @@
+\name{SFO.solution}
+\Rdversion{1.1}
+\alias{SFO.solution}
+\title{ Single First-Order kinetics }
+\description{
+ Function describing exponential decline from a defined starting value.
+}
+\usage{
+ SFO.solution(t, parent.0, k)
+}
+\arguments{
+ \item{t}{ Time. }
+ \item{parent.0}{ Starting value for the response variable at time zero. }
+ \item{k}{ Kinetic constant. }
+}
+\value{
+ The value of the response variable at time \code{t}.
+}
+\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://focus.jrc.ec.europa.eu/dk}
+}
+\examples{
+ \dontrun{plot(function(x) SFO.solution(x, 100, 3), 0, 2)}
+}
+\keyword{ manip }
diff --git a/man/SFORB.solution.Rd b/man/SFORB.solution.Rd
new file mode 100644
index 00000000..a935f696
--- /dev/null
+++ b/man/SFORB.solution.Rd
@@ -0,0 +1,36 @@
+\name{SFORB.solution}
+\Rdversion{1.1}
+\alias{SFORB.solution}
+\title{ Single First-Order Reversible Binding kinetics }
+\description{
+ Function describing the solution of the differential equations describing
+ the kinetic model with first-order terms for a two-way transfer from a free
+ to a bound fraction, and a first-order degradation term for the free
+ fraction. The initial condition is a defined amount in the free fraction and
+ no substance in the bound fraction.
+}
+\usage{
+ 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. }
+ \item{k_1output}{ Kinetic constant describing degradation of the free fraction. }
+}
+\value{
+ The value of the response variable, which is the sum of free and bound
+ fractions at time \code{t}.
+}
+\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://focus.jrc.ec.europa.eu/dk}
+}
+\examples{
+ \dontrun{plot(function(x) SFORB.solution(x, 100, 0.5, 2, 3), 0, 2)}
+}
+\keyword{ manip }
diff --git a/man/mkin_long_to_wide.Rd b/man/mkin_long_to_wide.Rd
index 97791e6d..6fa18606 100644
--- a/man/mkin_long_to_wide.Rd
+++ b/man/mkin_long_to_wide.Rd
@@ -4,7 +4,7 @@
Convert a dataframe from long to wide format.
}
\usage{
-mkin_long_to_wide(long_data, time = "time")
+mkin_long_to_wide(long_data, time = "time", outtime = "time")
}
\description{
This function takes a dataframe in the long form as required by \code{\link{modCost}}
@@ -17,7 +17,10 @@ mkin_long_to_wide(long_data, time = "time")
\code{time} argument and one column of observed values named "value".
}
\item{time}{
- The name of the time variable.
+ The name of the time variable in the long input data.
+}
+ \item{outtime}{
+ The name of the time variable in the wide output data.
}
}
\value{
diff --git a/man/mkinerrmin.Rd b/man/mkinerrmin.Rd
index 4bbf96ab..654115b6 100644
--- a/man/mkinerrmin.Rd
+++ b/man/mkinerrmin.Rd
@@ -42,5 +42,4 @@ mkinerrmin(errdata, n.parms, alpha = 0.05)
EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,
\url{http://focus.jrc.ec.europa.eu/dk}
}
-\author{ Johannes Ranke }
\keyword{ manip }
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index 0ec2d218..d4139eb3 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -15,7 +15,10 @@ mkinfit(mkinmod, observed,
state.ini = c(100, rep(0, length(mkinmod$diffs) - 1)),
lower = 0, upper = Inf,
fixed_parms = NULL, fixed_initials = names(mkinmod$diffs)[-1],
- plot = FALSE, quiet = FALSE, err = NULL, weight = "none", scaleVar = FALSE, ...)
+ eigen = FALSE,
+ plot = FALSE, quiet = FALSE, err = NULL, weight = "none",
+ scaleVar = FALSE,
+ atol = 1e-6, ...)
}
\arguments{
\item{mkinmod}{
@@ -32,8 +35,11 @@ mkinfit(mkinmod, observed,
\code{\link{modFit}}.
}
\item{parms.ini}{
- A named vector if initial values for the parameters, including both parameters to
+ A named vector if initial values for the parameters, including parameters to
be optimised and potentially also fixed parameters as indicated by \code{fixed_parms}.
+ The default is to set the initial values to 0.1. The setting of the initial values for
+ the parameters has a strong impart on performance and it lies in the responsibilty of the
+ user to set sensible initial values.
}
\item{state.ini}{
A named vector of initial values for the state variables of the model. In case the
@@ -47,9 +53,10 @@ mkinfit(mkinmod, observed,
negative values to not make sense for the models currently created by \code{\link{mkinmod}}.
}
\item{upper}{
- Upper bounds for the parameters, passed to \code{\link{modFit}}. Defaults to \code{Inf}. Setting
- non-infinite upper bounds has a strong impact on performance, and using a method like "L-BFGS-B" (by
- specifying an additional \code{method} argument) is recommended.
+ Upper bounds for the parameters, passed to \code{\link{modFit}}. Defaults to \code{Inf}
+ except for formation fraction parameters. Setting non-infinite upper bounds has a strong
+ impact on performance, and using a method like "L-BFGS-B" (by specifying an additional
+ \code{method} argument) is recommended.
}
\item{fixed_parms}{
The names of parameters that should not be optimised but rather kept at the values
@@ -59,6 +66,12 @@ mkinfit(mkinmod, observed,
The names of model variables for which the initial state at time 0 should be excluded
from the optimisation. Defaults to all state variables except for the first one.
}
+ \item{eigen}{
+ Should the solution of the system of differential equations be based on the
+ spectral decomposition of the coefficient matrix in cases that this is
+ possible? Be aware that the results may differ from the results returned using
+ the ode solver.
+ }
\item{plot}{
Should the observed values and the numerical solutions be plotted at each stage
of the optimisation?
@@ -77,13 +90,17 @@ mkinfit(mkinmod, observed,
Will be passed to \code{\link{modCost}}. Default is not to scale Variables according
to the number of observations.
}
+ \item{atol}{
+ Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-6 as in
+ \code{\link{lsoda}}.
+ }
\item{\dots}{
Further arguments that will be passed to \code{\link{modFit}}.
}
}
\value{
- A list with "mkinfit" and "modFit" in the class attribute. Thus, at
- present, a summary can be obtained by \code{\link{summary.modFit}}.
+ A list with "mkinfit" and "modFit" in the class attribute.
+ A summary can be obtained by \code{\link{summary.mkinfit}}.
}
\author{
Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
index 7ec96277..7c117357 100644
--- a/man/mkinmod.Rd
+++ b/man/mkinmod.Rd
@@ -15,13 +15,16 @@ mkinmod(...)
\item{...}{
For each observed variable, a list has to be specified as an argument, containing
at least a component \code{type}, specifying the type of kinetics to use
- for the variable. Currently, only single first order kinetics "SFO" or
- single first order with reversible binding "SFORB" are implemented, as well as
- "FOMC" for the first compartment which is assumed to be the source compartment.
- Optional components of each argument are \code{to}, a vector of names of
- variables to which a transfer is to be assumed in the model, and
- \code{sink}, a logical specifying if transformation to unspecified
- compounds (sink) is to be assumed in the model (defaults to \code{TRUE})
+ for the variable. Currently, single first order kinetics "SFO" or
+ single first order with reversible binding "SFORB" are implemented for all
+ variables, while
+ "FOMC", "DFOP" and "HS" can additionally be chosen for the first
+ variable which is assumed to be the source compartment. Optional components
+ of each argument are \code{to}, a
+ vector of names of variables to which a transfer is to be assumed in the
+ model, and \code{sink}, a logical specifying if transformation to
+ unspecified compounds (sink) is to be assumed in the model (defaults to
+ \code{TRUE})
}
}
\value{
@@ -31,6 +34,7 @@ mkinmod(...)
\item{parms}{ A vector of parameter names occurring in the differential equations. }
\item{map}{ A list containing named character vectors for each observed variable, specifying
the modelling variables by which it is represented. }
+ \item{coefmat}{ The coefficient matrix, if the system of differential equations can be represented by one. }
}
\author{
Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
diff --git a/man/mkinplot.Rd b/man/mkinplot.Rd
index 58959d77..b72675a9 100644
--- a/man/mkinplot.Rd
+++ b/man/mkinplot.Rd
@@ -10,7 +10,8 @@
}
\usage{
mkinplot(fit, xlab = "Time", ylab = "Observed",
- xlim = range(fit$data$time), ylim = range(fit$data$observed, na.rm=TRUE), ...)
+ xlim = range(fit$data$time), ylim = range(fit$data$observed, na.rm=TRUE),
+ legend = TRUE, ...)
}
\arguments{
\item{fit}{
@@ -28,6 +29,9 @@
\item{ylim}{
plot range in y direction.
}
+ \item{legend}{
+ legend specifying if a legend should be included in the plot.
+ }
\item{\dots}{
further arguments passed to \code{\link{plot}}.
}
diff --git a/man/mkinresplot.Rd b/man/mkinresplot.Rd
new file mode 100644
index 00000000..0b48692c
--- /dev/null
+++ b/man/mkinresplot.Rd
@@ -0,0 +1,64 @@
+\name{mkinresplot}
+\alias{mkinresplot}
+\title{
+ Function to plot residuals stored in an mkin object
+}
+\description{
+ This function plots the residuals for the specified subset of the
+ observed variables from an mkinfit object.
+}
+\usage{
+ mkinresplot(object, obs_vars = vector(),
+ xlab = "Time [days]", ylab = "Residual [\% of applied radioactivity]",
+ maxabs = "auto", legend = TRUE, lpos = "topright", ...)
+}
+\arguments{
+ \item{object}{
+ A fit represented in an \code{\link{mkinfit}} object.
+}
+ \item{obs_vars}{
+ A character vector of names of the observed variables for which residuals
+ should be plotted.
+}
+ \item{xlab}{
+ Label for the x axis. Defaults to "Time [days]".
+}
+ \item{ylab}{
+ Label for the y axis. Defaults to "Residual [\% of applied radioactivity]".
+}
+ \item{maxabs}{
+ Maximum absolute value of the residuals. This is used for the scaling of
+ the y axis and defaults to "auto".
+}
+ \item{legend}{
+ Should a legend be plotted? Defaults to "TRUE".
+}
+ \item{lpos}{
+ Where should the legend be placed? Default is "topright". Will be passed on to
+ \code{\link{legend}}. }
+ \item{\dots}{
+ further arguments passed to \code{\link{plot}}.
+}
+}
+\value{
+ Nothing is returned by this function, as it is called for its side effect, namely to produce a plot.
+}
+\author{
+ Katrin Lindenberger and Johannes Ranke
+}
+
+\seealso{
+ \code{\link{mkinplot}}, for a way to plot the data and the fitted lines of the
+ mkinfit object. }
+\examples{
+data <- mkin_wide_to_long(schaefer07_complex_case, time = "time")
+model <- mkinmod(
+ parent = list(type = "SFO", to = c("A1", "B1", "C1"), sink = FALSE),
+ A1 = list(type = "SFO", to = "A2"),
+ B1 = list(type = "SFO"),
+ C1 = list(type = "SFO"),
+ A2 = list(type = "SFO"))
+\dontrun{fit <- mkinfit(model, data, plot=TRUE)}
+\dontrun{mkinresplot(fit, "A1")}
+}
+\keyword{ hplot }
diff --git a/man/mkinstart.Rd b/man/mkinstart.Rd
new file mode 100644
index 00000000..ec1204f2
--- /dev/null
+++ b/man/mkinstart.Rd
@@ -0,0 +1,38 @@
+\name{mkinstart}
+\alias{mkinstart}
+\title{
+ Generate starting parameters for optimisations
+}
+\description{
+ This function is supposed to analyse a kinetic model and kinetic data in
+ order to generate suitable starting parameters for fitting the model.
+ It does not do anything really useful at the moment.
+}
+\usage{
+mkinstart(model, data, mode = "auto")
+}
+\arguments{
+ \item{model}{
+ A kinetic model of class \code{\link{mkinmod}}.
+}
+ \item{data}{
+ Kinetic data in wide format suitable for fitting with \code{\link{mkinfit}}.
+}
+ \item{mode}{
+ How the starting parameters should be generated. At the moment, only
+ "auto" is supported, which internally uses \code{\link{kinfit}}.
+}
+}
+\details{
+%% ~~ If necessary, more details than the description above ~~
+}
+\value{
+ A named vector of starting parameters.
+}
+\author{
+ Johannes Ranke
+}
+\examples{
+
+}
+\keyword{ manip }
diff --git a/man/summary.mkinfit.Rd b/man/summary.mkinfit.Rd
index 1c305899..8a8c6ab2 100644
--- a/man/summary.mkinfit.Rd
+++ b/man/summary.mkinfit.Rd
@@ -11,8 +11,8 @@
and residual values.
}
\usage{
-\method{summary}{mkinfit}(object, data = TRUE, distimes = TRUE, cov = FALSE, ...)
-\method{print}{summary.mkinfit}(x, digits = max(3, getOption("digits") - 3), ...)
+\method{summary}{mkinfit}(object, data = TRUE, distimes = TRUE, ff = TRUE, cov = FALSE, ...)
+\method{print}{summary.mkinfit}(x, digits = max(3, getOption("digits") - 3), tval = TRUE, ...)
}
\arguments{
@@ -26,7 +26,10 @@
logical, indicating whether the data should be included in the summary.
}
\item{distimes}{
- logical, indicating whether DT50 and DT90 values shoule be included.
+ logical, indicating whether DT50 and DT90 values should be included.
+}
+ \item{ff}{
+ logical, indicating whether formation fractions should be included.
}
\item{cov}{
logical, indicating whether parameter covariances should be calculated.
@@ -34,6 +37,10 @@ Passed to \code{\link{summary.modFit}}. }
\item{digits}{
Number of digits to use for printing
}
+ \item{tval}{
+ Should the test statistic of the t-test for parameter significance be
+ printed? Defaults to \code{TRUE}. Saves vertical space if set to \code{FALSE}.
+}
\item{\dots}{
optional arguments passed to methods like \code{print}.
}
@@ -47,6 +54,7 @@ Passed to \code{\link{summary.modFit}}. }
\item{fixed }{The values of fixed parameters.}
\item{errmin }{The chi2 error levels for each observed variable.}
\item{disstimes }{The DT50 and DT90 values for each observed variable.}
+ \item{ff }{The estimated formation fractions derived from the fitted model.}
The print method is called for its side effect, i.e. printing the summary.
}
\references{
@@ -57,7 +65,7 @@ Passed to \code{\link{summary.modFit}}. }
\url{http://focus.jrc.ec.europa.eu/dk}
}
\author{
- Johannes Ranke <jranke@harlan.com>
+ Johannes Ranke <jranke@{harlan.com,uni-bremen.de}>
}
\examples{
summary(mkinfit(mkinmod(parent = list(type = "SFO")), FOCUS_2006_A))

Contact - Imprint