aboutsummaryrefslogtreecommitdiff
path: root/man/mkinfit.Rd
diff options
context:
space:
mode:
Diffstat (limited to 'man/mkinfit.Rd')
-rw-r--r--man/mkinfit.Rd438
1 files changed, 206 insertions, 232 deletions
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index 09af4918..d9afb753 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -1,253 +1,214 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mkinfit.R
\name{mkinfit}
\alias{mkinfit}
-\title{
- Fit a kinetic model to data with one or more state variables
-}
-\description{
- This function maximises the likelihood of the observed data using
- the Port algorithm \code{\link{nlminb}}, and the specified initial or fixed
- parameters and starting values. In each step of the optimsation, the kinetic
- model is solved using the function \code{\link{mkinpredict}}. The parameters
- of the selected error model are fitted simultaneously with the degradation
- model parameters, as both of them are arguments of the likelihood function.
-
- Per default, parameters in the kinetic models are internally transformed in
- order to better satisfy the assumption of a normal distribution of their
- estimators.
+\title{Fit a kinetic model to data with one or more state variables}
+\source{
+Rocke, David M. und Lorenzato, Stefan (1995) A two-component model
+ for measurement error in analytical chemistry. Technometrics 37(2), 176-184.
}
\usage{
-mkinfit(mkinmod, observed,
- parms.ini = "auto",
- state.ini = "auto",
- err.ini = "auto",
- fixed_parms = NULL, fixed_initials = names(mkinmod$diffs)[-1],
- from_max_mean = FALSE,
+mkinfit(mkinmod, observed, parms.ini = "auto", state.ini = "auto",
+ err.ini = "auto", fixed_parms = NULL,
+ fixed_initials = names(mkinmod$diffs)[-1], from_max_mean = FALSE,
solution_type = c("auto", "analytical", "eigen", "deSolve"),
- method.ode = "lsoda",
- use_compiled = "auto",
+ method.ode = "lsoda", use_compiled = "auto",
control = list(eval.max = 300, iter.max = 200),
- transform_rates = TRUE,
- transform_fractions = TRUE,
- quiet = FALSE,
- atol = 1e-8, rtol = 1e-10, n.outtimes = 100,
+ transform_rates = TRUE, transform_fractions = TRUE, quiet = FALSE,
+ atol = 1e-08, rtol = 1e-10, n.outtimes = 100,
error_model = c("const", "obs", "tc"),
- error_model_algorithm = c("auto", "d_3", "direct", "twostep", "threestep",
- "fourstep", "IRLS", "OLS"),
- reweight.tol = 1e-8, reweight.max.iter = 10,
- trace_parms = FALSE, ...)
+ error_model_algorithm = c("auto", "d_3", "direct", "twostep",
+ "threestep", "fourstep", "IRLS", "OLS"), reweight.tol = 1e-08,
+ reweight.max.iter = 10, trace_parms = FALSE, ...)
}
\arguments{
- \item{mkinmod}{
- A list of class \code{\link{mkinmod}}, containing the kinetic model to be
- fitted to the data, or one of the shorthand names ("SFO", "FOMC", "DFOP",
- "HS", "SFORB", "IORE"). If a shorthand name is given, a parent only degradation
- model is generated for the variable with the highest value in
- \code{observed}.
- }
- \item{observed}{
- A dataframe with the observed data. The first column called "name" must
- contain the name of the observed variable for each data point. The second
- column must contain the times of observation, named "time". The third
- column must be named "value" and contain the observed values. Zero values
- in the "value" column will be removed, with a warning, in order to
- avoid problems with fitting the two-component error model. This is not
- expected to be a problem, because in general, values of zero are not
- observed in degradation data, because there is a lower limit of detection.
- }
- \item{parms.ini}{
- A named vector of initial values for the parameters, including parameters
- to be optimised and potentially also fixed parameters as indicated by
- \code{fixed_parms}. If set to "auto", initial values for rate constants
- are set to default values. Using parameter names that are not in the model
- gives an error.
-
- It is possible to only specify a subset of the parameters that the model
- needs. You can use the parameter lists "bparms.ode" from a previously
- fitted model, which contains the differential equation parameters from this
- model. This works nicely if the models are nested. An example is given
- below.
- }
- \item{state.ini}{
- A named vector of initial values for the state variables of the model. In
- case the observed variables are represented by more than one model
- variable, the names will differ from the names of the observed variables
- (see \code{map} component of \code{\link{mkinmod}}). The default is to set
- the initial value of the first model variable to the mean of the time zero
- values for the variable with the maximum observed value, and all others to 0.
- If this variable has no time zero observations, its initial value is set to 100.
- }
- \item{err.ini}{
- A named vector of initial values for the error model parameters to be
- optimised. If set to "auto", initial values are set to default values.
- Otherwise, inital values for all error model parameters must be
- given.
- }
- \item{fixed_parms}{
- The names of parameters that should not be optimised but rather kept at the
- values specified in \code{parms.ini}.
- }
- \item{fixed_initials}{
- 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{from_max_mean}{
- If this is set to TRUE, and the model has only one observed variable, then
- data before the time of the maximum observed value (after averaging for each
- sampling time) are discarded, and this time is subtracted from all
- remaining time values, so the time of the maximum observed mean value is
- the new time zero.
- }
- \item{solution_type}{
- If set to "eigen", the solution of the system of differential equations is
- based on the spectral decomposition of the coefficient matrix in cases that
- this is possible. If set to "deSolve", a numerical ode solver from package
- \code{\link{deSolve}} is used. If set to "analytical", an analytical
- solution of the model is used. This is only implemented for simple
- degradation experiments with only one state variable, i.e. with no
- metabolites. The default is "auto", which uses "analytical" if possible,
- otherwise "deSolve" if a compiler is present, and "eigen" if no
- compiler is present and the model can be expressed using eigenvalues and
- eigenvectors. This argument is passed on to the helper function
- \code{\link{mkinpredict}}.
- }
- \item{method.ode}{
- The solution method passed via \code{\link{mkinpredict}} to
- \code{\link{ode}} in case the solution type is "deSolve". The default
- "lsoda" is performant, but sometimes fails to converge.
- }
- \item{use_compiled}{
- If set to \code{FALSE}, no compiled version of the \code{\link{mkinmod}}
- model is used in the calls to \code{\link{mkinpredict}} even if a compiled
- version is present.
- }
- \item{control}{
- A list of control arguments passed to \code{\link{nlminb}}.
- }
- \item{transform_rates}{
- Boolean specifying if kinetic rate constants should be transformed in the
- model specification used in the fitting for better compliance with the
- assumption of normal distribution of the estimator. If TRUE, also
- alpha and beta parameters of the FOMC model are log-transformed, as well
- as k1 and k2 rate constants for the DFOP and HS models and the break point
- tb of the HS model. If FALSE, zero is used as a lower bound for the rates
- in the optimisation.
- }
- \item{transform_fractions}{
- Boolean specifying if formation fractions constants should be transformed in the
- model specification used in the fitting for better compliance with the
- assumption of normal distribution of the estimator. The default (TRUE) is
- to do transformations. If TRUE, the g parameter of the DFOP and HS
- models are also transformed, as they can also be seen as compositional
- data. The transformation used for these transformations is the
- \code{\link{ilr}} transformation.
- }
- \item{quiet}{
- Suppress printing out the current value of the negative log-likelihood
- after each improvement?
- }
- \item{atol}{
- Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-8,
- lower than in \code{\link{lsoda}}.
- }
- \item{rtol}{
- Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-10,
- much lower than in \code{\link{lsoda}}.
- }
- \item{n.outtimes}{
- The length of the dataseries that is produced by the model prediction
- function \code{\link{mkinpredict}}. This impacts the accuracy of
- the numerical solver if that is used (see \code{solution_type} argument.
- The default value is 100.
- }
- \item{error_model}{
- If the error model is "const", a constant standard deviation
- is assumed.
-
- If the error model is "obs", each observed variable is assumed to have its
- own variance.
-
- If the error model is "tc" (two-component error model), a two component
- error model similar to the one described by Rocke and Lorenzato (1995) is
- used for setting up the likelihood function. Note that this model deviates
- from the model by Rocke and Lorenzato, as their model implies that the
- errors follow a lognormal distribution for large values, not a normal
- distribution as assumed by this method.
- }
- \item{error_model_algorithm}{
- If "auto", the selected algorithm depends on the error model.
- If the error model is "const", unweighted nonlinear least squares fitting
- ("OLS") is selected. If the error model is "obs", or "tc", the "d_3"
- algorithm is selected.
-
- The algorithm "d_3" will directly minimize the negative
- log-likelihood and - independently - also use the three step algorithm
- described below. The fit with the higher likelihood is returned.
-
- The algorithm "direct" will directly minimize the negative
- log-likelihood.
-
- The algorithm "twostep" will minimize the negative log-likelihood
- after an initial unweighted least squares optimisation step.
-
- The algorithm "threestep" starts with unweighted least squares,
- then optimizes only the error model using the degradation model
- parameters found, and then minimizes the negative log-likelihood
- with free degradation and error model parameters.
-
- The algorithm "fourstep" starts with unweighted least squares,
- then optimizes only the error model using the degradation model
- parameters found, then optimizes the degradation model again
- with fixed error model parameters, and finally minimizes the negative
- log-likelihood with free degradation and error model parameters.
-
- The algorithm "IRLS" (Iteratively Reweighted Least Squares) starts with
- unweighted least squares, and then iterates optimization of the error model
- parameters and subsequent
- optimization of the degradation model using those error model parameters,
- until the error model parameters converge.
- }
- \item{reweight.tol}{
- Tolerance for the convergence criterion calculated from the error model
- parameters in IRLS fits.
- }
- \item{reweight.max.iter}{
- Maximum number of iterations in IRLS fits.
- }
- \item{trace_parms}{
- Should a trace of the parameter values be listed?
- }
- \item{\dots}{
- Further arguments that will be passed on to \code{\link{deSolve}}.
- }
+\item{mkinmod}{A list of class \code{\link{mkinmod}}, containing the kinetic
+model to be fitted to the data, or one of the shorthand names ("SFO",
+"FOMC", "DFOP", "HS", "SFORB", "IORE"). If a shorthand name is given, a
+parent only degradation model is generated for the variable with the
+highest value in \code{observed}.}
+
+\item{observed}{A dataframe with the observed data. The first column called
+"name" must contain the name of the observed variable for each data point.
+The second column must contain the times of observation, named "time".
+The third column must be named "value" and contain the observed values.
+Zero values in the "value" column will be removed, with a warning, in
+order to avoid problems with fitting the two-component error model. This
+is not expected to be a problem, because in general, values of zero are
+not observed in degradation data, because there is a lower limit of
+detection.}
+
+\item{parms.ini}{A named vector of initial values for the parameters,
+ including parameters to be optimised and potentially also fixed parameters
+ as indicated by \code{fixed_parms}. If set to "auto", initial values for
+ rate constants are set to default values. Using parameter names that are
+ not in the model gives an error.
+
+ It is possible to only specify a subset of the parameters that the model
+ needs. You can use the parameter lists "bparms.ode" from a previously
+ fitted model, which contains the differential equation parameters from
+ this model. This works nicely if the models are nested. An example is
+ given below.}
+
+\item{state.ini}{A named vector of initial values for the state variables of
+the model. In case the observed variables are represented by more than one
+model variable, the names will differ from the names of the observed
+variables (see \code{map} component of \code{\link{mkinmod}}). The default
+is to set the initial value of the first model variable to the mean of the
+time zero values for the variable with the maximum observed value, and all
+others to 0. If this variable has no time zero observations, its initial
+value is set to 100.}
+
+\item{err.ini}{A named vector of initial values for the error model
+parameters to be optimised. If set to "auto", initial values are set to
+default values. Otherwise, inital values for all error model parameters
+must be given.}
+
+\item{fixed_parms}{The names of parameters that should not be optimised but
+rather kept at the values specified in \code{parms.ini}.}
+
+\item{fixed_initials}{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{from_max_mean}{If this is set to TRUE, and the model has only one
+observed variable, then data before the time of the maximum observed value
+(after averaging for each sampling time) are discarded, and this time is
+subtracted from all remaining time values, so the time of the maximum
+observed mean value is the new time zero.}
+
+\item{solution_type}{If set to "eigen", the solution of the system of
+differential equations is based on the spectral decomposition of the
+coefficient matrix in cases that this is possible. If set to "deSolve", a
+numerical ode solver from package \code{\link{deSolve}} is used. If set to
+"analytical", an analytical solution of the model is used. This is only
+implemented for simple degradation experiments with only one state
+variable, i.e. with no metabolites. The default is "auto", which uses
+"analytical" if possible, otherwise "deSolve" if a compiler is present,
+and "eigen" if no compiler is present and the model can be expressed using
+eigenvalues and eigenvectors. This argument is passed on to the helper
+function \code{\link{mkinpredict}}.}
+
+\item{method.ode}{The solution method passed via \code{\link{mkinpredict}}
+to \code{\link{ode}} in case the solution type is "deSolve". The default
+"lsoda" is performant, but sometimes fails to converge.}
+
+\item{use_compiled}{If set to \code{FALSE}, no compiled version of the
+\code{\link{mkinmod}} model is used in the calls to
+\code{\link{mkinpredict}} even if a compiled version is present.}
+
+\item{control}{A list of control arguments passed to \code{\link{nlminb}}.}
+
+\item{transform_rates}{Boolean specifying if kinetic rate constants should
+be transformed in the model specification used in the fitting for better
+compliance with the assumption of normal distribution of the estimator. If
+TRUE, also alpha and beta parameters of the FOMC model are
+log-transformed, as well as k1 and k2 rate constants for the DFOP and HS
+models and the break point tb of the HS model. If FALSE, zero is used as
+a lower bound for the rates in the optimisation.}
+
+\item{transform_fractions}{Boolean specifying if formation fractions
+constants should be transformed in the model specification used in the
+fitting for better compliance with the assumption of normal distribution
+of the estimator. The default (TRUE) is to do transformations. If TRUE,
+the g parameter of the DFOP and HS models are also transformed, as they
+can also be seen as compositional data. The transformation used for these
+transformations is the \code{\link{ilr}} transformation.}
+
+\item{quiet}{Suppress printing out the current value of the negative
+log-likelihood after each improvement?}
+
+\item{atol}{Absolute error tolerance, passed to \code{\link{ode}}. Default
+is 1e-8, lower than in \code{\link{lsoda}}.}
+
+\item{rtol}{Absolute error tolerance, passed to \code{\link{ode}}. Default
+is 1e-10, much lower than in \code{\link{lsoda}}.}
+
+\item{n.outtimes}{The length of the dataseries that is produced by the model
+prediction function \code{\link{mkinpredict}}. This impacts the accuracy
+of the numerical solver if that is used (see \code{solution_type}
+argument. The default value is 100.}
+
+\item{error_model}{If the error model is "const", a constant standard
+ deviation is assumed.
+
+ If the error model is "obs", each observed variable is assumed to have its
+ own variance.
+
+ If the error model is "tc" (two-component error model), a two component
+ error model similar to the one described by Rocke and Lorenzato (1995) is
+ used for setting up the likelihood function. Note that this model
+ deviates from the model by Rocke and Lorenzato, as their model implies
+ that the errors follow a lognormal distribution for large values, not a
+ normal distribution as assumed by this method.}
+
+\item{error_model_algorithm}{If "auto", the selected algorithm depends on
+ the error model. If the error model is "const", unweighted nonlinear
+ least squares fitting ("OLS") is selected. If the error model is "obs", or
+ "tc", the "d_3" algorithm is selected.
+
+ The algorithm "d_3" will directly minimize the negative log-likelihood and
+ - independently - also use the three step algorithm described below. The
+ fit with the higher likelihood is returned.
+
+ The algorithm "direct" will directly minimize the negative log-likelihood.
+
+ The algorithm "twostep" will minimize the negative log-likelihood after an
+ initial unweighted least squares optimisation step.
+
+ The algorithm "threestep" starts with unweighted least squares, then
+ optimizes only the error model using the degradation model parameters
+ found, and then minimizes the negative log-likelihood with free
+ degradation and error model parameters.
+
+ The algorithm "fourstep" starts with unweighted least squares, then
+ optimizes only the error model using the degradation model parameters
+ found, then optimizes the degradation model again with fixed error model
+ parameters, and finally minimizes the negative log-likelihood with free
+ degradation and error model parameters.
+
+ The algorithm "IRLS" (Iteratively Reweighted Least Squares) starts with
+ unweighted least squares, and then iterates optimization of the error
+ model parameters and subsequent optimization of the degradation model
+ using those error model parameters, until the error model parameters
+ converge.}
+
+\item{reweight.tol}{Tolerance for the convergence criterion calculated from
+the error model parameters in IRLS fits.}
+
+\item{reweight.max.iter}{Maximum number of iterations in IRLS fits.}
+
+\item{trace_parms}{Should a trace of the parameter values be listed?}
+
+\item{\dots}{Further arguments that will be passed on to
+\code{\link{deSolve}}.}
}
\value{
- A list with "mkinfit" in the class attribute. A summary can be obtained by
- \code{\link{summary.mkinfit}}.
+A list with "mkinfit" in the class attribute. A summary can be
+ obtained by \code{\link{summary.mkinfit}}.
}
-\seealso{
- Plotting methods \code{\link{plot.mkinfit}} and \code{\link{mkinparplot}}.
-
- Comparisons of models fitted to the same data can be made using \code{\link{AIC}}
- by virtue of the method \code{\link{logLik.mkinfit}}.
-
- Fitting of several models to several datasets in a single call to
- \code{\link{mmkin}}.
+\description{
+This function maximises the likelihood of the observed data using the Port
+algorithm \code{\link{nlminb}}, and the specified initial or fixed
+parameters and starting values. In each step of the optimsation, the
+kinetic model is solved using the function \code{\link{mkinpredict}}. The
+parameters of the selected error model are fitted simultaneously with the
+degradation model parameters, as both of them are arguments of the
+likelihood function.
+}
+\details{
+Per default, parameters in the kinetic models are internally transformed in
+order to better satisfy the assumption of a normal distribution of their
+estimators.
}
\note{
- When using the "IORE" submodel for metabolites, fitting with
+When using the "IORE" submodel for metabolites, fitting with
"transform_rates = TRUE" (the default) often leads to failures of the
numerical ODE solver. In this situation it may help to switch off the
internal rate transformation.
}
-\source{
- Rocke, David M. und Lorenzato, Stefan (1995) A two-component model for
- measurement error in analytical chemistry. Technometrics 37(2), 176-184.
-}
-\author{
- Johannes Ranke
-}
\examples{
+
# Use shorthand notation for parent only degradation
fit <- mkinfit("FOMC", FOCUS_2006_C, quiet = TRUE)
summary(fit)
@@ -307,5 +268,18 @@ f.tc <- mkinfit(SFO_SFO.ff, FOCUS_2006_D, error_model = "tc", quiet = TRUE)
summary(f.tc)
}
+
+}
+\seealso{
+Plotting methods \code{\link{plot.mkinfit}} and
+ \code{\link{mkinparplot}}.
+
+ Comparisons of models fitted to the same data can be made using
+ \code{\link{AIC}} by virtue of the method \code{\link{logLik.mkinfit}}.
+
+ Fitting of several models to several datasets in a single call to
+ \code{\link{mmkin}}.
+}
+\author{
+Johannes Ranke
}
-\keyword{ optimize }

Contact - Imprint