diff options
Diffstat (limited to 'man/mkinfit.Rd')
| -rw-r--r-- | man/mkinfit.Rd | 100 |
1 files changed, 56 insertions, 44 deletions
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd index a080f8ae..750c3468 100644 --- a/man/mkinfit.Rd +++ b/man/mkinfit.Rd @@ -5,9 +5,14 @@ } \description{ This function uses the Flexible Modelling Environment package - \code{\link{FME}} to create a function calculating the model cost, which is - then minimised, using the specified initial or fixed parameters and starting - values. + \code{\link{FME}} to create a function calculating the model cost, i.e. the + deviation between the kinetic model and the observed data. This model cost is + then minimised using the Levenberg-Marquardt algorithm \code{\link{nls.lm}}, + using 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 variance of the residuals for each + observed variable can optionally be iteratively reweighted until convergence + using the argument \code{reweight.method = "obs"}. } \usage{ mkinfit(mkinmod, observed, @@ -30,19 +35,20 @@ mkinfit(mkinmod, observed, } \item{observed}{ The observed data. It has to be in the long format as described in - \code{\link{modFit}}, i.e. 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. Optionally, a further column can contain - weights for each data point. If it is not named "err", its name must be - passed as a further argument named \code{err} which is then passed on to - \code{\link{modFit}}. + \code{\link{modFit}}, i.e. 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. Optionally, a further column + can contain weights for each data point. If it is not named "err", its name + must be passed as a further argument named \code{err} which is then passed + on to \code{\link{modFit}}. } \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. + 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 @@ -51,43 +57,48 @@ mkinfit(mkinmod, observed, 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 100 and all others to 0. + 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 100 and all others to 0. } \item{fixed_parms}{ - The names of parameters that should not be optimised but rather kept at the values - specified in \code{parms.ini}. + 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. + 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{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 "eigen" if the model can be expressed - using eigenvalues and eigenvectors, and finally "deSolve" for the remaining - models (time dependence of degradation rates and metabolites). + 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 "eigen" if the model can be expressed using eigenvalues and + eigenvectors, and finally "deSolve" for the remaining models (time + dependence of degradation rates and metabolites). This argument is passed + on to the helper function \code{\link{mkinpredict}}. } \item{method.modFit}{ - The optimisation method passed to \code{\link{modFit}}. The default "Marq" is the Levenberg Marquardt - algorithm \code{\link{nls.lm}} from the package \code{minpack.lm}. Often other methods need - more iterations to find the same result. When using "Pseudo", "upper" and "lower" need to be + The optimisation method passed to \code{\link{modFit}}. The default "Marq" + is the Levenberg Marquardt algorithm \code{\link{nls.lm}} from the package + \code{minpack.lm}. Often other methods need more iterations to find the + same result. When using "Pseudo", "upper" and "lower" need to be specified for the transformed parameters. } \item{control.modFit}{ - Additional arguments passed to the optimisation method used by \code{\link{modFit}}. + Additional arguments passed to the optimisation method used by + \code{\link{modFit}}. } \item{plot}{ - Should the observed values and the numerical solutions be plotted at each stage - of the optimisation? + Should the observed values and the numerical solutions be plotted at each + stage of the optimisation? } \item{quiet}{ Suppress printing out the current model cost after each improvement? @@ -96,12 +107,13 @@ mkinfit(mkinmod, observed, \emph{error} estimates, used to weigh the residuals (see details of \code{\link{modCost}}); if \code{NULL}, then the residuals are not weighed. } - \item{weight}{only if \code{err}=\code{NULL}: how to weight the - residuals, one of "none", "std", "mean", see details of \code{\link{modCost}}. + \item{weight}{ + only if \code{err}=\code{NULL}: how to weight the residuals, one of "none", + "std", "mean", see details of \code{\link{modCost}}. } \item{scaleVar}{ - Will be passed to \code{\link{modCost}}. Default is not to scale Variables according - to the number of observations. + 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-8, @@ -114,7 +126,7 @@ mkinfit(mkinmod, observed, \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} argument. + the numerical solver if that is used (see \code{solution_type} argument. The default value is 100. } \item{reweight.method}{ @@ -125,7 +137,7 @@ mkinfit(mkinmod, observed, estimated from the fit and used for weighting the residuals in each iteration until convergence of this estimate up to \code{reweight.tol} or up to the maximum number of iterations - specified by \code{reweight.maxiter}. + specified by \code{reweight.max.iter}. } \item{reweight.tol}{ Tolerance for convergence criterion for the variance components |