diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/pkgdown.yml | 2 | ||||
| -rw-r--r-- | docs/reference/mkinfit.html | 94 |
2 files changed, 49 insertions, 47 deletions
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 #> |