diff options
Diffstat (limited to 'man/mkinfit.Rd')
| -rw-r--r-- | man/mkinfit.Rd | 438 |
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 } |