diff options
| -rw-r--r-- | man/mkinfit.Rd | 100 | ||||
| -rw-r--r-- | man/mkinpredict.Rd | 43 |
2 files changed, 78 insertions, 65 deletions
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd index a080f8a..750c346 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 diff --git a/man/mkinpredict.Rd b/man/mkinpredict.Rd index 9d181f5..afb57e0 100644 --- a/man/mkinpredict.Rd +++ b/man/mkinpredict.Rd @@ -4,9 +4,9 @@ Produce predictions from a kinetic model using specifc parameters } \description{ - This function produces a time series for all the observed variables in a kinetic model - as specified by \code{\link{mkinmod}}, using a specific set of kinetic parameters and - initial values for the state variables. + This function produces a time series for all the observed variables in a + kinetic model as specified by \code{\link{mkinmod}}, using a specific set of + kinetic parameters and initial values for the state variables. } \usage{ mkinpredict(mkinmod, odeparms, odeini, outtimes, solution_type = "deSolve", @@ -14,30 +14,31 @@ } \arguments{ \item{mkinmod}{ - A kinetic model as produced by \code{\link{mkinmod}}. + A kinetic model as produced by \code{\link{mkinmod}}. } \item{odeparms}{ - A numeric vector specifying the parameters used in the kinetic model, which is generally - defined as a set of ordinary differential equations. + A numeric vector specifying the parameters used in the kinetic model, which + is generally defined as a set of ordinary differential equations. } \item{odeini}{ - A numeric vectory containing the initial values of the state variables of the model. Note - that the state variables can differ from the observed variables, for example in the case - of the SFORB model. + A numeric vectory containing the initial values of the state variables of + the model. Note that the state variables can differ from the observed + variables, for example in the case of the SFORB model. } \item{outtimes}{ - A numeric vector specifying the time points for which model predictions should be - generated. + A numeric vector specifying the time points for which model predictions + should be generated. } \item{solution_type}{ - The method that should be used for producing the predictions. This should - generally be "analytical" if there is only one observed variable, and usually - "deSolve" in the case of several observed variables. The third possibility "eigen" - is faster but produces results that the author believes to be less accurate. + The method that should be used for producing the predictions. This should + generally be "analytical" if there is only one observed variable, and + usually "deSolve" in the case of several observed variables. The third + possibility "eigen" is faster but produces results that the author believes + to be less accurate. } \item{map_output}{ - Boolean to specify if the output should list values for the observed variables (default) - or for all state variables (if set to FALSE). + Boolean to specify if the output should list values for the observed + variables (default) or for all state variables (if set to FALSE). } \item{atol}{ Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-8, @@ -70,10 +71,10 @@ atol = 1e-20)[20,] # The integration method does not make a lot of difference - mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, atol = 1e-20, - method = "ode45")[20,] - mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, atol = 1e-20, - method = "rk4")[20,] + mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, + atol = 1e-20, method = "ode45")[20,] + mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, + atol = 1e-20, method = "rk4")[20,] # The number of output times used to make a lot of difference until the # default for atol was adjusted |