From 1718d434efae26de02754c6622c43f4dc9e624b9 Mon Sep 17 00:00:00 2001 From: jranke Date: Thu, 15 Mar 2012 15:54:14 +0000 Subject: Update kinfit and mkin to the latest version published on BerliOS. git-svn-id: svn+ssh://svn.r-forge.r-project.org/svnroot/kinfit/pkg/mkin@17 edb9625f-4e0d-4859-8d74-9fd3b1da38cb --- man/DFOP.solution.Rd | 36 ++++++++++++++++++++++++++ man/FOCUS_2006_datasets.Rd | 2 +- man/FOMC.solution.Rd | 49 +++++++++++++++++++++++++++++++++++ man/HS.solution.Rd | 34 ++++++++++++++++++++++++ man/SFO.solution.Rd | 29 +++++++++++++++++++++ man/SFORB.solution.Rd | 36 ++++++++++++++++++++++++++ man/mkin_long_to_wide.Rd | 7 +++-- man/mkinerrmin.Rd | 1 - man/mkinfit.Rd | 31 +++++++++++++++++----- man/mkinmod.Rd | 18 ++++++++----- man/mkinplot.Rd | 6 ++++- man/mkinresplot.Rd | 64 ++++++++++++++++++++++++++++++++++++++++++++++ man/mkinstart.Rd | 38 +++++++++++++++++++++++++++ man/summary.mkinfit.Rd | 16 +++++++++--- 14 files changed, 344 insertions(+), 23 deletions(-) create mode 100644 man/DFOP.solution.Rd create mode 100644 man/FOMC.solution.Rd create mode 100644 man/HS.solution.Rd create mode 100644 man/SFO.solution.Rd create mode 100644 man/SFORB.solution.Rd create mode 100644 man/mkinresplot.Rd create mode 100644 man/mkinstart.Rd (limited to 'man') diff --git a/man/DFOP.solution.Rd b/man/DFOP.solution.Rd new file mode 100644 index 0000000..d30cf7f --- /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 04565f7..5053b88 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 0000000..d04d34e --- /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 0000000..71f68a1 --- /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 0000000..41a9ba9 --- /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 0000000..a935f69 --- /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 97791e6..6fa1860 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 4bbf96a..654115b 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 0ec2d21..d4139eb 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 diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd index 7ec9627..7c11735 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 diff --git a/man/mkinplot.Rd b/man/mkinplot.Rd index 58959d7..b72675a 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 0000000..0b48692 --- /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 0000000..ec1204f --- /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 1c30589..8a8c6ab 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,13 +26,20 @@ 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. 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 + Johannes Ranke } \examples{ summary(mkinfit(mkinmod(parent = list(type = "SFO")), FOCUS_2006_A)) -- cgit v1.2.1