diff options
| -rw-r--r-- | R/mkinfit.R | 48 | ||||
| -rw-r--r-- | docs/pkgdown.yml | 2 | ||||
| -rw-r--r-- | docs/reference/mkinfit.html | 94 | ||||
| -rw-r--r-- | man/mkinfit.Rd | 48 |
4 files changed, 97 insertions, 95 deletions
diff --git a/R/mkinfit.R b/R/mkinfit.R index 8231cd00..393473d1 100644 --- a/R/mkinfit.R +++ b/R/mkinfit.R @@ -3,9 +3,11 @@ if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "time", "value")) #' Fit a kinetic model to data with one or more state variables #' #' This function maximises the likelihood of the observed data using the Port -#' algorithm \code{\link{nlminb}}, and the specified initial or fixed +#' algorithm [stats::nlminb()], and the specified initial or fixed #' parameters and starting values. In each step of the optimisation, the -#' kinetic model is solved using the function \code{\link{mkinpredict}}. The +#' kinetic model is solved using the function [mkinpredict()], except +#' if an analytical solution is implemented, in which case the model is solved +#' using the degradation function in the [mkinmod] object. 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. @@ -14,7 +16,7 @@ if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "time", "value")) #' order to better satisfy the assumption of a normal distribution of their #' estimators. #' -#' @param mkinmod A list of class \code{\link{mkinmod}}, containing the kinetic +#' @param mkinmod A list of class [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 @@ -42,7 +44,7 @@ if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "time", "value")) #' @param 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 +#' variables (see \code{map} component of [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 @@ -66,20 +68,19 @@ if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "time", "value")) #' @param 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 relatively simple degradation models. The default is +#' numerical [ode solver from package deSolve][deSolve::ode()] is used. If +#' set to "analytical", an analytical solution of the model is used. This is +#' only implemented for relatively simple degradation models. 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}}. -#' @param method.ode The solution method passed via \code{\link{mkinpredict}} -#' to \code{\link{ode}} in case the solution type is "deSolve". The default +#' can be expressed using eigenvalues and eigenvectors. +#' @param method.ode The solution method passed via [mkinpredict()] +#' to [deSolve::ode()] in case the solution type is "deSolve". The default #' "lsoda" is performant, but sometimes fails to converge. #' @param 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. -#' @param control A list of control arguments passed to \code{\link{nlminb}}. +#' [mkinmod] model is used in the calls to [mkinpredict()] even if a compiled +#' version is present. +#' @param control A list of control arguments passed to [stats::nlminb()]. #' @param 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 @@ -93,13 +94,14 @@ if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "time", "value")) #' 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. +#' transformations is the [ilr()] transformation. #' @param quiet Suppress printing out the current value of the negative #' log-likelihood after each improvement? -#' @param atol Absolute error tolerance, passed to \code{\link{ode}}. Default -#' is 1e-8, lower than in \code{\link{lsoda}}. -#' @param rtol Absolute error tolerance, passed to \code{\link{ode}}. Default -#' is 1e-10, much lower than in \code{\link{lsoda}}. +#' @param atol Absolute error tolerance, passed to [deSolve::ode()]. Default +#' is 1e-8, which is lower than the default in the [deSolve::lsoda()] +#' function which is used per default. +#' @param rtol Absolute error tolerance, passed to [deSolve::ode()]. Default +#' is 1e-10, much lower than in [deSolve::lsoda()]. #' @param error_model If the error model is "const", a constant standard #' deviation is assumed. #' @@ -147,17 +149,15 @@ if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "time", "value")) #' @param reweight.max.iter Maximum number of iterations in IRLS fits. #' @param trace_parms Should a trace of the parameter values be listed? #' @param \dots Further arguments that will be passed on to -#' \code{\link{deSolve}}. +#' [deSolve::ode()]. #' @importFrom stats nlminb aggregate dist -#' @return A list with "mkinfit" in the class attribute. A summary can be -#' obtained by \code{\link{summary.mkinfit}}. +#' @return A list with "mkinfit" in the class attribute. #' @note 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. #' @author Johannes Ranke -#' @seealso Plotting methods \code{\link{plot.mkinfit}} and -#' \code{\link{mkinparplot}}. +#' @seealso [summary.mkinfit], [plot.mkinfit], [parms] and [lrtest]. #' #' Comparisons of models fitted to the same data can be made using #' \code{\link{AIC}} by virtue of the method \code{\link{logLik.mkinfit}}. diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 3c25ad85..4756397e 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -10,7 +10,7 @@ articles: NAFTA_examples: web_only/NAFTA_examples.html benchmarks: web_only/benchmarks.html compiled_models: web_only/compiled_models.html -last_built: 2020-05-14T16:46Z +last_built: 2020-05-15T05:30Z urls: reference: https://pkgdown.jrwb.de/mkin/reference article: https://pkgdown.jrwb.de/mkin/articles diff --git a/docs/reference/mkinfit.html b/docs/reference/mkinfit.html index 3438b8b1..0c1540d2 100644 --- a/docs/reference/mkinfit.html +++ b/docs/reference/mkinfit.html @@ -41,9 +41,11 @@ <meta property="og:title" content="Fit a kinetic model to data with one or more state variables — mkinfit" /> <meta property="og:description" content="This function maximises the likelihood of the observed data using the Port -algorithm nlminb, and the specified initial or fixed +algorithm stats::nlminb(), and the specified initial or fixed parameters and starting values. In each step of the optimisation, the -kinetic model is solved using the function mkinpredict. The +kinetic model is solved using the function mkinpredict(), except +if an analytical solution is implemented, in which case the model is solved +using the degradation function in the mkinmod object. 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." /> @@ -78,7 +80,7 @@ likelihood function." /> </button> <span class="navbar-brand"> <a class="navbar-link" href="../index.html">mkin</a> - <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">0.9.50.2</span> + <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">0.9.50.3</span> </span> </div> @@ -151,9 +153,11 @@ likelihood function." /> <div class="ref-description"> <p>This function maximises the likelihood of the observed data using the Port -algorithm <code><a href='https://rdrr.io/r/stats/nlminb.html'>nlminb</a></code>, and the specified initial or fixed +algorithm <code><a href='https://rdrr.io/r/stats/nlminb.html'>stats::nlminb()</a></code>, and the specified initial or fixed parameters and starting values. In each step of the optimisation, the -kinetic model is solved using the function <code><a href='mkinpredict.html'>mkinpredict</a></code>. The +kinetic model is solved using the function <code><a href='mkinpredict.html'>mkinpredict()</a></code>, except +if an analytical solution is implemented, in which case the model is solved +using the degradation function in the <a href='mkinmod.html'>mkinmod</a> object. 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.</p> @@ -191,7 +195,7 @@ likelihood function.</p> <colgroup><col class="name" /><col class="desc" /></colgroup> <tr> <th>mkinmod</th> - <td><p>A list of class <code><a href='mkinmod.html'>mkinmod</a></code>, containing the kinetic + <td><p>A list of class <a href='mkinmod.html'>mkinmod</a>, 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 @@ -227,7 +231,7 @@ given below.</p></td> <td><p>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</code> component of <code><a href='mkinmod.html'>mkinmod</a></code>). The default +variables (see <code>map</code> component of <a href='mkinmod.html'>mkinmod</a>). 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 @@ -266,29 +270,28 @@ observed mean value is the new time zero.</p></td> <td><p>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>deSolve</code> is used. If set to -"analytical", an analytical solution of the model is used. This is only -implemented for relatively simple degradation models. The default is +numerical <a href='https://rdrr.io/pkg/deSolve/man/ode.html'>ode solver from package deSolve</a> is used. If +set to "analytical", an analytical solution of the model is used. This is +only implemented for relatively simple degradation models. 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><a href='mkinpredict.html'>mkinpredict</a></code>.</p></td> +can be expressed using eigenvalues and eigenvectors.</p></td> </tr> <tr> <th>method.ode</th> - <td><p>The solution method passed via <code><a href='mkinpredict.html'>mkinpredict</a></code> -to <code>ode</code> in case the solution type is "deSolve". The default + <td><p>The solution method passed via <code><a href='mkinpredict.html'>mkinpredict()</a></code> +to <code><a href='https://rdrr.io/pkg/deSolve/man/ode.html'>deSolve::ode()</a></code> in case the solution type is "deSolve". The default "lsoda" is performant, but sometimes fails to converge.</p></td> </tr> <tr> <th>use_compiled</th> <td><p>If set to <code>FALSE</code>, no compiled version of the -<code><a href='mkinmod.html'>mkinmod</a></code> model is used in the calls to -<code><a href='mkinpredict.html'>mkinpredict</a></code> even if a compiled version is present.</p></td> +<a href='mkinmod.html'>mkinmod</a> model is used in the calls to <code><a href='mkinpredict.html'>mkinpredict()</a></code> even if a compiled +version is present.</p></td> </tr> <tr> <th>control</th> - <td><p>A list of control arguments passed to <code><a href='https://rdrr.io/r/stats/nlminb.html'>nlminb</a></code>.</p></td> + <td><p>A list of control arguments passed to <code><a href='https://rdrr.io/r/stats/nlminb.html'>stats::nlminb()</a></code>.</p></td> </tr> <tr> <th>transform_rates</th> @@ -308,7 +311,7 @@ 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><a href='ilr.html'>ilr</a></code> transformation.</p></td> +transformations is the <code><a href='ilr.html'>ilr()</a></code> transformation.</p></td> </tr> <tr> <th>quiet</th> @@ -317,13 +320,14 @@ log-likelihood after each improvement?</p></td> </tr> <tr> <th>atol</th> - <td><p>Absolute error tolerance, passed to <code>ode</code>. Default -is 1e-8, lower than in <code>lsoda</code>.</p></td> + <td><p>Absolute error tolerance, passed to <code><a href='https://rdrr.io/pkg/deSolve/man/ode.html'>deSolve::ode()</a></code>. Default +is 1e-8, which is lower than the default in the <code><a href='https://rdrr.io/pkg/deSolve/man/lsoda.html'>deSolve::lsoda()</a></code> +function which is used per default.</p></td> </tr> <tr> <th>rtol</th> - <td><p>Absolute error tolerance, passed to <code>ode</code>. Default -is 1e-10, much lower than in <code>lsoda</code>.</p></td> + <td><p>Absolute error tolerance, passed to <code><a href='https://rdrr.io/pkg/deSolve/man/ode.html'>deSolve::ode()</a></code>. Default +is 1e-10, much lower than in <code><a href='https://rdrr.io/pkg/deSolve/man/lsoda.html'>deSolve::lsoda()</a></code>.</p></td> </tr> <tr> <th>error_model</th> @@ -381,14 +385,13 @@ the error model parameters in IRLS fits.</p></td> <tr> <th>...</th> <td><p>Further arguments that will be passed on to -<code>deSolve</code>.</p></td> +<code><a href='https://rdrr.io/pkg/deSolve/man/ode.html'>deSolve::ode()</a></code>.</p></td> </tr> </table> <h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2> - <p>A list with "mkinfit" in the class attribute. A summary can be -obtained by <code><a href='summary.mkinfit.html'>summary.mkinfit</a></code>.</p> + <p>A list with "mkinfit" in the class attribute.</p> <h2 class="hasAnchor" id="details"><a class="anchor" href="#details"></a>Details</h2> <p>Per default, parameters in the kinetic models are internally transformed in @@ -409,8 +412,7 @@ Degradation Data. <em>Environments</em> 6(12) 124 <a href='https://doi.org/10.3390/environments6120124'>doi:10.3390/environments6120124</a>.</p> <h2 class="hasAnchor" id="see-also"><a class="anchor" href="#see-also"></a>See also</h2> - <div class='dont-index'><p>Plotting methods <code><a href='plot.mkinfit.html'>plot.mkinfit</a></code> and -<code><a href='mkinparplot.html'>mkinparplot</a></code>.</p> + <div class='dont-index'><p><a href='summary.mkinfit.html'>summary.mkinfit</a>, <a href='plot.mkinfit.html'>plot.mkinfit</a>, <a href='parms.html'>parms</a> and <a href='https://rdrr.io/pkg/lmtest/man/lrtest.html'>lrtest</a>.</p> <p>Comparisons of models fitted to the same data can be made using <code><a href='https://rdrr.io/r/stats/AIC.html'>AIC</a></code> by virtue of the method <code><a href='logLik.mkinfit.html'>logLik.mkinfit</a></code>.</p> <p>Fitting of several models to several datasets in a single call to @@ -420,17 +422,17 @@ Degradation Data. <em>Environments</em> 6(12) 124 <pre class="examples"><div class='input'> <span class='co'># Use shorthand notation for parent only degradation</span> <span class='no'>fit</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='st'>"FOMC"</span>, <span class='no'>FOCUS_2006_C</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>) -<span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>fit</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.2 +<span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>fit</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.3 #> R version used for fitting: 4.0.0 -#> Date of fit: Tue May 12 19:10:13 2020 -#> Date of summary: Tue May 12 19:10:13 2020 +#> Date of fit: Fri May 15 07:30:32 2020 +#> Date of summary: Fri May 15 07:30:32 2020 #> #> Equations: #> d_parent/dt = - (alpha/beta) * 1/((time/beta) + 1) * parent #> #> Model predictions using solution type analytical #> -#> Fitted using 222 model solutions performed in 0.047 s +#> Fitted using 222 model solutions performed in 0.048 s #> #> Error model: Constant variance #> @@ -506,8 +508,8 @@ Degradation Data. <em>Environments</em> 6(12) 124 <span class='kw'>parent</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>, <span class='st'>"m1"</span>), <span class='kw'>m1</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>))</div><div class='output co'>#> <span class='message'>Successfully compiled differential equation model from auto-generated C code.</span></div><div class='input'><span class='co'># Fit the model to the FOCUS example dataset D using defaults</span> <span class='fu'><a href='https://rdrr.io/r/base/print.html'>print</a></span>(<span class='fu'><a href='https://rdrr.io/r/base/system.time.html'>system.time</a></span>(<span class='no'>fit</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO</span>, <span class='no'>FOCUS_2006_D</span>, - <span class='kw'>solution_type</span> <span class='kw'>=</span> <span class='st'>"eigen"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)))</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='output co'>#> User System verstrichen -#> 0.417 0.000 0.417 </div><div class='input'><span class='fu'><a href='parms.html'>parms</a></span>(<span class='no'>fit</span>)</div><div class='output co'>#> parent_0 k_parent k_m1 f_parent_to_m1 sigma + <span class='kw'>solution_type</span> <span class='kw'>=</span> <span class='st'>"eigen"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)))</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='output co'>#> user system elapsed +#> 0.413 0.005 0.419 </div><div class='input'><span class='fu'><a href='parms.html'>parms</a></span>(<span class='no'>fit</span>)</div><div class='output co'>#> parent_0 k_parent k_m1 f_parent_to_m1 sigma #> 99.598483222 0.098697734 0.005260651 0.514475962 3.125503875 </div><div class='input'><span class='fu'><a href='endpoints.html'>endpoints</a></span>(<span class='no'>fit</span>)</div><div class='output co'>#> $ff #> parent_m1 parent_sink #> 0.514476 0.485524 @@ -596,8 +598,8 @@ Degradation Data. <em>Environments</em> 6(12) 124 #> Sum of squared residuals at call 165: 371.2134 #> Sum of squared residuals at call 166: 371.2134 #> Sum of squared residuals at call 168: 371.2134 -#> Negative log-likelihood at call 178: 97.22429</div><div class='output co'>#> <span class='message'>Optimisation successfully terminated.</span></div><div class='output co'>#> User System verstrichen -#> 0.351 0.000 0.352 </div><div class='input'><span class='fu'><a href='parms.html'>parms</a></span>(<span class='no'>fit.deSolve</span>)</div><div class='output co'>#> parent_0 k_parent k_m1 f_parent_to_m1 sigma +#> Negative log-likelihood at call 178: 97.22429</div><div class='output co'>#> <span class='message'>Optimisation successfully terminated.</span></div><div class='output co'>#> user system elapsed +#> 0.354 0.000 0.354 </div><div class='input'><span class='fu'><a href='parms.html'>parms</a></span>(<span class='no'>fit.deSolve</span>)</div><div class='output co'>#> parent_0 k_parent k_m1 f_parent_to_m1 sigma #> 99.598480759 0.098697739 0.005260651 0.514475958 3.125503874 </div><div class='input'><span class='fu'><a href='endpoints.html'>endpoints</a></span>(<span class='no'>fit.deSolve</span>)</div><div class='output co'>#> $ff #> parent_m1 parent_sink #> 0.514476 0.485524 @@ -629,10 +631,10 @@ Degradation Data. <em>Environments</em> 6(12) 124 <span class='co'># \dontrun{</span> <span class='co'># Weighted fits, including IRLS (error_model = "obs")</span> <span class='no'>SFO_SFO.ff</span> <span class='kw'><-</span> <span class='fu'><a href='mkinmod.html'>mkinmod</a></span>(<span class='kw'>parent</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>, <span class='st'>"m1"</span>), - <span class='kw'>m1</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>), <span class='kw'>use_of_ff</span> <span class='kw'>=</span> <span class='st'>"max"</span>)</div><div class='output co'>#> <span class='message'>Successfully compiled differential equation model from auto-generated C code.</span></div><div class='input'><span class='no'>f.noweight</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO.ff</span>, <span class='no'>FOCUS_2006_D</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>f.noweight</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.2 + <span class='kw'>m1</span> <span class='kw'>=</span> <span class='fu'><a href='mkinsub.html'>mkinsub</a></span>(<span class='st'>"SFO"</span>), <span class='kw'>use_of_ff</span> <span class='kw'>=</span> <span class='st'>"max"</span>)</div><div class='output co'>#> <span class='message'>Successfully compiled differential equation model from auto-generated C code.</span></div><div class='input'><span class='no'>f.noweight</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO.ff</span>, <span class='no'>FOCUS_2006_D</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>f.noweight</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.3 #> R version used for fitting: 4.0.0 -#> Date of fit: Tue May 12 19:10:18 2020 -#> Date of summary: Tue May 12 19:10:18 2020 +#> Date of fit: Fri May 15 07:30:37 2020 +#> Date of summary: Fri May 15 07:30:37 2020 #> #> Equations: #> d_parent/dt = - k_parent * parent @@ -640,7 +642,7 @@ Degradation Data. <em>Environments</em> 6(12) 124 #> #> Model predictions using solution type analytical #> -#> Fitted using 421 model solutions performed in 0.146 s +#> Fitted using 421 model solutions performed in 0.147 s #> #> Error model: Constant variance #> @@ -751,10 +753,10 @@ Degradation Data. <em>Environments</em> 6(12) 124 #> 100 m1 31.04 31.98163 -9.416e-01 #> 100 m1 33.13 31.98163 1.148e+00 #> 120 m1 25.15 28.78984 -3.640e+00 -#> 120 m1 33.31 28.78984 4.520e+00</div><div class='input'><span class='no'>f.obs</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO.ff</span>, <span class='no'>FOCUS_2006_D</span>, <span class='kw'>error_model</span> <span class='kw'>=</span> <span class='st'>"obs"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>f.obs</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.2 +#> 120 m1 33.31 28.78984 4.520e+00</div><div class='input'><span class='no'>f.obs</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO.ff</span>, <span class='no'>FOCUS_2006_D</span>, <span class='kw'>error_model</span> <span class='kw'>=</span> <span class='st'>"obs"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>f.obs</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.3 #> R version used for fitting: 4.0.0 -#> Date of fit: Tue May 12 19:10:19 2020 -#> Date of summary: Tue May 12 19:10:19 2020 +#> Date of fit: Fri May 15 07:30:38 2020 +#> Date of summary: Fri May 15 07:30:38 2020 #> #> Equations: #> d_parent/dt = - k_parent * parent @@ -888,10 +890,10 @@ Degradation Data. <em>Environments</em> 6(12) 124 #> 100 m1 31.04 31.98773 -9.477e-01 #> 100 m1 33.13 31.98773 1.142e+00 #> 120 m1 25.15 28.80429 -3.654e+00 -#> 120 m1 33.31 28.80429 4.506e+00</div><div class='input'><span class='no'>f.tc</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO.ff</span>, <span class='no'>FOCUS_2006_D</span>, <span class='kw'>error_model</span> <span class='kw'>=</span> <span class='st'>"tc"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>f.tc</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.2 +#> 120 m1 33.31 28.80429 4.506e+00</div><div class='input'><span class='no'>f.tc</span> <span class='kw'><-</span> <span class='fu'>mkinfit</span>(<span class='no'>SFO_SFO.ff</span>, <span class='no'>FOCUS_2006_D</span>, <span class='kw'>error_model</span> <span class='kw'>=</span> <span class='st'>"tc"</span>, <span class='kw'>quiet</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</div><div class='output co'>#> <span class='warning'>Warning: Observations with value of zero were removed from the data</span></div><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/summary.html'>summary</a></span>(<span class='no'>f.tc</span>)</div><div class='output co'>#> mkin version used for fitting: 0.9.50.3 #> R version used for fitting: 4.0.0 -#> Date of fit: Tue May 12 19:10:19 2020 -#> Date of summary: Tue May 12 19:10:19 2020 +#> Date of fit: Fri May 15 07:30:39 2020 +#> Date of summary: Fri May 15 07:30:39 2020 #> #> Equations: #> d_parent/dt = - k_parent * parent @@ -899,7 +901,7 @@ Degradation Data. <em>Environments</em> 6(12) 124 #> #> Model predictions using solution type analytical #> -#> Fitted using 1875 model solutions performed in 0.645 s +#> Fitted using 1875 model solutions performed in 0.658 s #> #> Error model: Two-component variance function #> diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd index b8d44fba..5e6b242e 100644 --- a/man/mkinfit.Rd +++ b/man/mkinfit.Rd @@ -32,7 +32,7 @@ mkinfit( ) } \arguments{ -\item{mkinmod}{A list of class \code{\link{mkinmod}}, containing the kinetic +\item{mkinmod}{A list of class \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 @@ -63,7 +63,7 @@ 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 +variables (see \code{map} component of \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 @@ -92,23 +92,22 @@ 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 relatively simple degradation models. The default is +numerical \link[deSolve:ode]{ode solver from package deSolve} is used. If +set to "analytical", an analytical solution of the model is used. This is +only implemented for relatively simple degradation models. 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}}.} +can be expressed using eigenvalues and eigenvectors.} -\item{method.ode}{The solution method passed via \code{\link{mkinpredict}} -to \code{\link{ode}} in case the solution type is "deSolve". The default +\item{method.ode}{The solution method passed via \code{\link[=mkinpredict]{mkinpredict()}} +to \code{\link[deSolve:ode]{deSolve::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.} +\link{mkinmod} model is used in the calls to \code{\link[=mkinpredict]{mkinpredict()}} even if a compiled +version is present.} -\item{control}{A list of control arguments passed to \code{\link{nlminb}}.} +\item{control}{A list of control arguments passed to \code{\link[stats:nlminb]{stats::nlminb()}}.} \item{transform_rates}{Boolean specifying if kinetic rate constants should be transformed in the model specification used in the fitting for better @@ -124,16 +123,17 @@ 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.} +transformations is the \code{\link[=ilr]{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{atol}{Absolute error tolerance, passed to \code{\link[deSolve:ode]{deSolve::ode()}}. Default +is 1e-8, which is lower than the default in the \code{\link[deSolve:lsoda]{deSolve::lsoda()}} +function which is used per default.} -\item{rtol}{Absolute error tolerance, passed to \code{\link{ode}}. Default -is 1e-10, much lower than in \code{\link{lsoda}}.} +\item{rtol}{Absolute error tolerance, passed to \code{\link[deSolve:ode]{deSolve::ode()}}. Default +is 1e-10, much lower than in \code{\link[deSolve:lsoda]{deSolve::lsoda()}}.} \item{error_model}{If the error model is "const", a constant standard deviation is assumed. @@ -187,17 +187,18 @@ the error model parameters 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}}.} +\code{\link[deSolve:ode]{deSolve::ode()}}.} } \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. } \description{ This function maximises the likelihood of the observed data using the Port -algorithm \code{\link{nlminb}}, and the specified initial or fixed +algorithm \code{\link[stats:nlminb]{stats::nlminb()}}, and the specified initial or fixed parameters and starting values. In each step of the optimisation, the -kinetic model is solved using the function \code{\link{mkinpredict}}. The +kinetic model is solved using the function \code{\link[=mkinpredict]{mkinpredict()}}, except +if an analytical solution is implemented, in which case the model is solved +using the degradation function in the \link{mkinmod} object. 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. @@ -285,8 +286,7 @@ Degradation Data. \emph{Environments} 6(12) 124 \href{https://doi.org/10.3390/environments6120124}{doi:10.3390/environments6120124}. } \seealso{ -Plotting methods \code{\link{plot.mkinfit}} and -\code{\link{mkinparplot}}. +\link{summary.mkinfit}, \link{plot.mkinfit}, \link{parms} and \link{lrtest}. Comparisons of models fitted to the same data can be made using \code{\link{AIC}} by virtue of the method \code{\link{logLik.mkinfit}}. |