aboutsummaryrefslogtreecommitdiff
path: root/inst/web/mkinfit.html
diff options
context:
space:
mode:
authorJohannes Ranke <jranke@uni-bremen.de>2016-10-06 08:56:45 +0200
committerJohannes Ranke <jranke@uni-bremen.de>2016-10-06 08:56:45 +0200
commitec1487f0f2cef32d44b0c6ce94a6f1b4f65a79d3 (patch)
tree10820a2fa5ae6b51115c2d2f40e40bcc8f0b8d5e /inst/web/mkinfit.html
parent6b7c2049d4feb9dd76dd532830adba23b8a5007f (diff)
Remove staticdocs from old location
Diffstat (limited to 'inst/web/mkinfit.html')
-rw-r--r--inst/web/mkinfit.html524
1 files changed, 0 insertions, 524 deletions
diff --git a/inst/web/mkinfit.html b/inst/web/mkinfit.html
deleted file mode 100644
index 899f2cc7..00000000
--- a/inst/web/mkinfit.html
+++ /dev/null
@@ -1,524 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="utf-8">
-<title>mkinfit. mkin 0.9.44.9000</title>
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="author" content="
- Johannes Ranke
-">
-
-<link href="css/bootstrap.css" rel="stylesheet">
-<link href="css/bootstrap-responsive.css" rel="stylesheet">
-<link href="css/highlight.css" rel="stylesheet">
-<link href="css/staticdocs.css" rel="stylesheet">
-
-<!--[if lt IE 9]>
- <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
-<![endif]-->
-
-<script type="text/x-mathjax-config">
- MathJax.Hub.Config({
- tex2jax: {
- inlineMath: [ ['$','$'], ["\\(","\\)"] ],
- processEscapes: true
- }
- });
-</script>
-<script type="text/javascript"
- src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
-</script>
- </head>
-
- <body>
- <div class="navbar">
- <div class="navbar-inner">
- <div class="container">
- <a class="brand" href="#">mkin 0.9.44.9000</a>
- <div class="nav">
- <ul class="nav">
- <li><a href="index.html"><i class="icon-home icon-white"></i> Index</a></li>
- </ul>
- </div>
- </div>
- </div>
-</div>
-
- <div class="container">
- <header>
-
- </header>
-
- <h1>
- Fit a kinetic model to data with one or more state variables
-</h1>
-
-<div class="row">
- <div class="span8">
- <h2>Usage</h2>
- <pre><div>mkinfit(mkinmod, observed, parms.ini&nbsp;=&nbsp;"auto", state.ini&nbsp;=&nbsp;"auto", fixed_parms&nbsp;=&nbsp;NULL, fixed_initials&nbsp;=&nbsp;names(mkinmod$diffs)[-1], from_max_mean&nbsp;=&nbsp;FALSE, solution_type&nbsp;=&nbsp;c("auto", "analytical", "eigen", "deSolve"), method.ode&nbsp;=&nbsp;"lsoda", use_compiled&nbsp;=&nbsp;"auto", method.modFit&nbsp;=&nbsp;c("Port", "Marq", "SANN", "Nelder-Mead", "BFGS", "CG", "L-BFGS-B"), maxit.modFit&nbsp;=&nbsp;"auto", control.modFit&nbsp;=&nbsp;list(), transform_rates&nbsp;=&nbsp;TRUE, transform_fractions&nbsp;=&nbsp;TRUE, plot&nbsp;=&nbsp;FALSE, quiet&nbsp;=&nbsp;FALSE, err&nbsp;=&nbsp;NULL, weight&nbsp;=&nbsp;"none", scaleVar&nbsp;=&nbsp;FALSE, atol&nbsp;=&nbsp;1e-8, rtol&nbsp;=&nbsp;1e-10, n.outtimes&nbsp;=&nbsp;100, reweight.method&nbsp;=&nbsp;NULL, reweight.tol&nbsp;=&nbsp;1e-8, reweight.max.iter&nbsp;=&nbsp;10, trace_parms&nbsp;=&nbsp;FALSE, ...)</div></pre>
-
- <h2>Arguments</h2>
- <dl>
- <dt>mkinmod</dt>
- <dd>
- A list of class <code><a href='mkinmod.html'>mkinmod</a></code>, containing the kinetic model to be
- fitted to the data, or one of the shorthand names ("SFO", "FOMC", "DFOP",
- "HS", "SFORB"). If a shorthand name is given, a parent only degradation
- model is generated for the variable with the highest value in
- <code>observed</code>.
- </dd>
- <dt>observed</dt>
- <dd>
- The observed data. It has to be in the long format as described in
- <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modFit'>modFit</a></code>, 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. Its name must be passed as a
- further argument named <code>err</code> which is then passed on to
- <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modFit'>modFit</a></code>.
- </dd>
- <dt>parms.ini</dt>
- <dd>
- 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</code>. 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.
- </dd>
- <dt>state.ini</dt>
- <dd>
- 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 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.
- </dd>
- <dt>fixed_parms</dt>
- <dd>
- The names of parameters that should not be optimised but rather kept at the
- values specified in <code>parms.ini</code>.
- </dd>
- <dt>fixed_initials</dt>
- <dd>
- 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.
- </dd>
- <dt>from_max_mean</dt>
- <dd>
- 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.
- </dd>
- <dt>solution_type</dt>
- <dd>
- 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><a href='http://www.inside-r.org/packages/cran/deSolve/docs/deSolve'>deSolve</a></code> 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><a href='mkinpredict.html'>mkinpredict</a></code>.
- </dd>
- <dt>method.ode</dt>
- <dd>
- The solution method passed via <code><a href='mkinpredict.html'>mkinpredict</a></code> to
- <code><a href='http://www.inside-r.org/packages/cran/deSolve/docs/ode'>ode</a></code> in case the solution type is "deSolve". The default
- "lsoda" is performant, but sometimes fails to converge.
- </dd>
- <dt>use_compiled</dt>
- <dd>
- 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 verion is present.
- </dd>
- <dt>method.modFit</dt>
- <dd>
- The optimisation method passed to <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modFit'>modFit</a></code>.
-
- In order to optimally deal with problems where local minima occur, the
- "Port" algorithm is now used per default as it is less prone to get trapped
- in local minima and depends less on starting values for parameters than
- the Levenberg Marquardt variant selected by "Marq". However, "Port" needs
- more iterations.
-
- The former default "Marq" is the Levenberg Marquardt algorithm
- <code><a href='http://www.inside-r.org/packages/cran/minpack.lm/docs/nls.lm'>nls.lm</a></code> from the package <code>minpack.lm</code> and usually needs
- the least number of iterations.
-
- The "Pseudo" algorithm is not included because it needs finite parameter bounds
- which are currently not supported.
-
- The "Newton" algorithm is not included because its number of iterations
- can not be controlled by <code>control.modFit</code> and it does not appear
- to provide advantages over the other algorithms.
- </dd>
- <dt>maxit.modFit</dt>
- <dd>
- Maximum number of iterations in the optimisation. If not "auto", this will
- be passed to the method called by <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modFit'>modFit</a></code>, overriding
- what may be specified in the next argument <code>control.modFit</code>.
- </dd>
- <dt>control.modFit</dt>
- <dd>
- Additional arguments passed to the optimisation method used by
- <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modFit'>modFit</a></code>.
- </dd>
- <dt>transform_rates</dt>
- <dd>
- 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.
- </dd>
- <dt>transform_fractions</dt>
- <dd>
- 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><a href='ilr.html'>ilr</a></code> transformation.
- </dd>
- <dt>plot</dt>
- <dd>
- Should the observed values and the numerical solutions be plotted at each
- stage of the optimisation?
- </dd>
- <dt>quiet</dt>
- <dd>
- Suppress printing out the current model cost after each improvement?
- </dd>
- <dt>err </dt>
- <dd>either <code>NULL</code>, or the name of the column with the
- <em>error</em> estimates, used to weigh the residuals (see details of
- <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modCost'>modCost</a></code>); if <code>NULL</code>, then the residuals are not weighed.
- </dd>
- <dt>weight</dt>
- <dd>
- only if <code>err</code>=<code>NULL</code>: how to weight the residuals, one of "none",
- "std", "mean", see details of <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modCost'>modCost</a></code>.
- </dd>
- <dt>scaleVar</dt>
- <dd>
- Will be passed to <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modCost'>modCost</a></code>. Default is not to scale Variables
- according to the number of observations.
- </dd>
- <dt>atol</dt>
- <dd>
- Absolute error tolerance, passed to <code><a href='http://www.inside-r.org/packages/cran/deSolve/docs/ode'>ode</a></code>. Default is 1e-8,
- lower than in <code><a href='http://www.inside-r.org/packages/cran/deSolve/docs/lsoda'>lsoda</a></code>.
- </dd>
- <dt>rtol</dt>
- <dd>
- Absolute error tolerance, passed to <code><a href='http://www.inside-r.org/packages/cran/deSolve/docs/ode'>ode</a></code>. Default is 1e-10,
- much lower than in <code><a href='http://www.inside-r.org/packages/cran/deSolve/docs/lsoda'>lsoda</a></code>.
- </dd>
- <dt>n.outtimes</dt>
- <dd>
- The length of the dataseries that is produced by the model prediction
- function <code><a href='mkinpredict.html'>mkinpredict</a></code>. This impacts the accuracy of
- the numerical solver if that is used (see <code>solution_type</code> argument.
- The default value is 100.
- </dd>
- <dt>reweight.method</dt>
- <dd>
- The method used for iteratively reweighting residuals, also known
- as iteratively reweighted least squares (IRLS). Default is NULL,
- the other method implemented is called "obs", meaning that each
- observed variable is assumed to have its own variance, this is
- estimated from the fit and used for weighting the residuals
- in each iteration until convergence of this estimate up to
- <code>reweight.tol</code> or up to the maximum number of iterations
- specified by <code>reweight.max.iter</code>.
- </dd>
- <dt>reweight.tol</dt>
- <dd>
- Tolerance for convergence criterion for the variance components
- in IRLS fits.
- </dd>
- <dt>reweight.max.iter</dt>
- <dd>
- Maximum iterations in IRLS fits.
- </dd>
- <dt>trace_parms</dt>
- <dd>
- Should a trace of the parameter values be listed?
- </dd>
- <dt>...</dt>
- <dd>
- Further arguments that will be passed to <code><a href='http://www.inside-r.org/packages/cran/FME/docs/modFit'>modFit</a></code>.
- </dd>
- </dl>
-
- <div class="Description">
- <h2>Description</h2>
-
- <p>This function uses the Flexible Modelling Environment package
- <code><a href='http://www.inside-r.org/packages/cran/FME/docs/FME'>FME</a></code> 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 Port algorithm <code><a href='http://www.inside-r.org/r-doc/stats/nlminb'>nlminb</a></code>,
- using the specified initial or fixed parameters and starting values.
- Per default, parameters in the kinetic models are internally transformed in order
- to better satisfy the assumption of a normal distribution of their estimators.
- In each step of the optimsation, the kinetic model is solved using the
- function <code><a href='mkinpredict.html'>mkinpredict</a></code>. The variance of the residuals for each
- observed variable can optionally be iteratively reweighted until convergence
- using the argument <code>reweight.method = "obs"</code>.</p>
-
- </div>
-
- <div class="Value">
- <h2>Value</h2>
-
- <p><dl>
- A list with "mkinfit" and "modFit" in the class attribute.
- A summary can be obtained by <code><a href='summary.mkinfit.html'>summary.mkinfit</a></code>.
-</dl></p>
-
- </div>
-
- <div class="Note">
- <h2>Note</h2>
-
- <p>The implementation of iteratively reweighted least squares is inspired by the
- work of the KinGUII team at Bayer Crop Science (Walter Schmitt and Zhenglei
- Gao). A similar implemention can also be found in CAKE 2.0, which is the
- other GUI derivative of mkin, sponsored by Syngenta.</p>
-
- </div>
-
- <div class="Note">
- <h2>Note</h2>
-
- <p>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.</p>
-
- </div>
-
- <h2 id="examples">Examples</h2>
- <pre class="examples"><div class='input'># Use shorthand notation for parent only degradation
-fit &lt;- mkinfit(&quot;FOMC&quot;, FOCUS_2006_C, quiet = TRUE)
-summary(fit)
-</div>
-<div class='output'>mkin version: 0.9.44.9000
-R version: 3.3.1
-Date of fit: Sat Sep 10 05:19:38 2016
-Date of summary: Sat Sep 10 05:19:38 2016
-
-Equations:
-d_parent = - (alpha/beta) * 1/((time/beta) + 1) * parent
-
-Model predictions using solution type analytical
-
-Fitted with method Port using 64 model solutions performed in 0.148 s
-
-Weighting: none
-
-Starting values for parameters to be optimised:
- value type
-parent_0 85.1 state
-alpha 1.0 deparm
-beta 10.0 deparm
-
-Starting values for the transformed parameters actually optimised:
- value lower upper
-parent_0 85.100000 -Inf Inf
-log_alpha 0.000000 -Inf Inf
-log_beta 2.302585 -Inf Inf
-
-Fixed parameter values:
-None
-
-Optimised, transformed parameters with symmetric confidence intervals:
- Estimate Std. Error Lower Upper
-parent_0 85.87000 2.2460 80.38000 91.3700
-log_alpha 0.05192 0.1605 -0.34080 0.4446
-log_beta 0.65100 0.2801 -0.03452 1.3360
-
-Parameter correlation:
- parent_0 log_alpha log_beta
-parent_0 1.0000 -0.2033 -0.3624
-log_alpha -0.2033 1.0000 0.9547
-log_beta -0.3624 0.9547 1.0000
-
-Residual standard error: 2.275 on 6 degrees of freedom
-
-Backtransformed parameters:
-Confidence intervals for internally transformed parameters are asymmetric.
-t-test (unrealistically) based on the assumption of normal distribution
-for estimators of untransformed parameters.
- Estimate t value Pr(&gt;t) Lower Upper
-parent_0 85.870 38.230 1.069e-08 80.3800 91.370
-alpha 1.053 6.231 3.953e-04 0.7112 1.560
-beta 1.917 3.570 5.895e-03 0.9661 3.806
-
-Chi2 error levels in percent:
- err.min n.optim df
-All data 6.657 3 6
-parent 6.657 3 6
-
-Estimated disappearance times:
- DT50 DT90 DT50back
-parent 1.785 15.15 4.56
-
-Data:
- time variable observed predicted residual
- 0 parent 85.1 85.875 -0.7749
- 1 parent 57.9 55.191 2.7091
- 3 parent 29.9 31.845 -1.9452
- 7 parent 14.6 17.012 -2.4124
- 14 parent 9.7 9.241 0.4590
- 28 parent 6.6 4.754 1.8460
- 63 parent 4.0 2.102 1.8977
- 91 parent 3.9 1.441 2.4590
- 119 parent 0.6 1.092 -0.4919
-</div>
-<div class='input'>
-# One parent compound, one metabolite, both single first order.
-# Use mkinsub for convenience in model formulation. Pathway to sink included per default.
-SFO_SFO &lt;- mkinmod(
- parent = mkinsub(&quot;SFO&quot;, &quot;m1&quot;),
- m1 = mkinsub(&quot;SFO&quot;))
-</div>
-<strong class='message'>Successfully compiled differential equation model from auto-generated C code.</strong>
-<div class='input'># Fit the model to the FOCUS example dataset D using defaults
-print(system.time(fit &lt;- mkinfit(SFO_SFO, FOCUS_2006_D,
- solution_type = &quot;eigen&quot;, quiet = TRUE)))
-</div>
-<div class='output'> user system elapsed
- 1.236 1.188 0.911
-</div>
-<div class='input'>coef(fit)
-</div>
-<div class='output'> parent_0 log_k_parent_sink log_k_parent_m1 log_k_m1_sink
- 99.59848 -3.03822 -2.98030 -5.24750
-</div>
-<div class='input'>endpoints(fit)
-</div>
-<div class='output'>$ff
-parent_sink parent_m1 m1_sink
- 0.485524 0.514476 1.000000
-
-$SFORB
-logical(0)
-
-$distimes
- DT50 DT90
-parent 7.022929 23.32967
-m1 131.760712 437.69961
-
-</div>
-<div class='input'>## Not run:
-# # deSolve is slower when no C compiler (gcc) was available during model generation
-# print(system.time(fit.deSolve &lt;- mkinfit(SFO_SFO, FOCUS_2006_D,
-# solution_type = &quot;deSolve&quot;)))
-# coef(fit.deSolve)
-# endpoints(fit.deSolve)
-# ## End(Not run)
-
-# Use stepwise fitting, using optimised parameters from parent only fit, FOMC
-## Not run:
-# FOMC_SFO &lt;- mkinmod(
-# parent = mkinsub(&quot;FOMC&quot;, &quot;m1&quot;),
-# m1 = mkinsub(&quot;SFO&quot;))
-# # Fit the model to the FOCUS example dataset D using defaults
-# fit.FOMC_SFO &lt;- mkinfit(FOMC_SFO, FOCUS_2006_D)
-# # Use starting parameters from parent only FOMC fit
-# fit.FOMC = mkinfit(&quot;FOMC&quot;, FOCUS_2006_D, plot=TRUE)
-# fit.FOMC_SFO &lt;- mkinfit(FOMC_SFO, FOCUS_2006_D,
-# parms.ini = fit.FOMC$bparms.ode, plot=TRUE)
-#
-# # Use stepwise fitting, using optimised parameters from parent only fit, SFORB
-# SFORB_SFO &lt;- mkinmod(
-# parent = list(type = &quot;SFORB&quot;, to = &quot;m1&quot;, sink = TRUE),
-# m1 = list(type = &quot;SFO&quot;))
-# # Fit the model to the FOCUS example dataset D using defaults
-# fit.SFORB_SFO &lt;- mkinfit(SFORB_SFO, FOCUS_2006_D)
-# fit.SFORB_SFO.deSolve &lt;- mkinfit(SFORB_SFO, FOCUS_2006_D, solution_type = &quot;deSolve&quot;)
-# # Use starting parameters from parent only SFORB fit (not really needed in this case)
-# fit.SFORB = mkinfit(&quot;SFORB&quot;, FOCUS_2006_D)
-# fit.SFORB_SFO &lt;- mkinfit(SFORB_SFO, FOCUS_2006_D, parms.ini = fit.SFORB$bparms.ode)
-# ## End(Not run)
-
-## Not run:
-# # Weighted fits, including IRLS
-# SFO_SFO.ff &lt;- mkinmod(parent = mkinsub(&quot;SFO&quot;, &quot;m1&quot;),
-# m1 = mkinsub(&quot;SFO&quot;), use_of_ff = &quot;max&quot;)
-# f.noweight &lt;- mkinfit(SFO_SFO.ff, FOCUS_2006_D)
-# summary(f.noweight)
-# f.irls &lt;- mkinfit(SFO_SFO.ff, FOCUS_2006_D, reweight.method = &quot;obs&quot;)
-# summary(f.irls)
-# f.w.mean &lt;- mkinfit(SFO_SFO.ff, FOCUS_2006_D, weight = &quot;mean&quot;)
-# summary(f.w.mean)
-# f.w.value &lt;- mkinfit(SFO_SFO.ff, subset(FOCUS_2006_D, value != 0), err = &quot;value&quot;)
-# summary(f.w.value)
-# ## End(Not run)
-
-## Not run:
-# # Manual weighting
-# dw &lt;- FOCUS_2006_D
-# errors &lt;- c(parent = 2, m1 = 1)
-# dw$err.man &lt;- errors[FOCUS_2006_D$name]
-# f.w.man &lt;- mkinfit(SFO_SFO.ff, dw, err = &quot;err.man&quot;)
-# summary(f.w.man)
-# f.w.man.irls &lt;- mkinfit(SFO_SFO.ff, dw, err = &quot;err.man&quot;,
-# reweight.method = &quot;obs&quot;)
-# summary(f.w.man.irls)
-# ## End(Not run)
-</div></pre>
- </div>
- <div class="span4">
- <!-- <ul>
- <li>mkinfit</li>
- </ul>
- <ul>
- <li> optimize </li>
- </ul> -->
-
- <h2>See also</h2>
-
- Plotting methods <code><a href='plot.mkinfit.html'>plot.mkinfit</a></code> and
- <code><a href='mkinparplot.html'>mkinparplot</a></code>.
-
- Fitting of several models to several datasets in a single call to
- <code><a href='mmkin.html'>mmkin</a></code>.
-
-
- <h2>Author</h2>
-
- Johannes Ranke
-
-
- </div>
-</div>
-
- <footer>
- <p class="pull-right"><a href="#">Back to top</a></p>
-<p>Built by <a href="https://github.com/hadley/staticdocs">staticdocs</a>. Styled with <a href="http://twitter.github.com/bootstrap">bootstrap</a>.</p>
- </footer>
- </div>
- </body>
-</html> \ No newline at end of file

Contact - Imprint