diff options
Diffstat (limited to 'inst/web/mkinfit.html')
| -rw-r--r-- | inst/web/mkinfit.html | 524 |
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 = "auto", state.ini = "auto", fixed_parms = NULL, fixed_initials = names(mkinmod$diffs)[-1], from_max_mean = FALSE, solution_type = c("auto", "analytical", "eigen", "deSolve"), method.ode = "lsoda", use_compiled = "auto", method.modFit = c("Port", "Marq", "SANN", "Nelder-Mead", "BFGS", "CG", "L-BFGS-B"), maxit.modFit = "auto", control.modFit = list(), transform_rates = TRUE, transform_fractions = TRUE, plot = FALSE, quiet = FALSE, err = NULL, weight = "none", scaleVar = FALSE, atol = 1e-8, rtol = 1e-10, n.outtimes = 100, reweight.method = NULL, reweight.tol = 1e-8, reweight.max.iter = 10, trace_parms = 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 <- mkinfit("FOMC", 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(>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 <- mkinmod( - parent = mkinsub("SFO", "m1"), - m1 = mkinsub("SFO")) -</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 <- mkinfit(SFO_SFO, FOCUS_2006_D, - solution_type = "eigen", 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 <- mkinfit(SFO_SFO, FOCUS_2006_D, -# solution_type = "deSolve"))) -# coef(fit.deSolve) -# endpoints(fit.deSolve) -# ## End(Not run) - -# Use stepwise fitting, using optimised parameters from parent only fit, FOMC -## Not run: -# FOMC_SFO <- mkinmod( -# parent = mkinsub("FOMC", "m1"), -# m1 = mkinsub("SFO")) -# # Fit the model to the FOCUS example dataset D using defaults -# fit.FOMC_SFO <- mkinfit(FOMC_SFO, FOCUS_2006_D) -# # Use starting parameters from parent only FOMC fit -# fit.FOMC = mkinfit("FOMC", FOCUS_2006_D, plot=TRUE) -# fit.FOMC_SFO <- 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 <- mkinmod( -# parent = list(type = "SFORB", to = "m1", sink = TRUE), -# m1 = list(type = "SFO")) -# # Fit the model to the FOCUS example dataset D using defaults -# fit.SFORB_SFO <- mkinfit(SFORB_SFO, FOCUS_2006_D) -# fit.SFORB_SFO.deSolve <- mkinfit(SFORB_SFO, FOCUS_2006_D, solution_type = "deSolve") -# # Use starting parameters from parent only SFORB fit (not really needed in this case) -# fit.SFORB = mkinfit("SFORB", FOCUS_2006_D) -# fit.SFORB_SFO <- mkinfit(SFORB_SFO, FOCUS_2006_D, parms.ini = fit.SFORB$bparms.ode) -# ## End(Not run) - -## Not run: -# # Weighted fits, including IRLS -# SFO_SFO.ff <- mkinmod(parent = mkinsub("SFO", "m1"), -# m1 = mkinsub("SFO"), use_of_ff = "max") -# f.noweight <- mkinfit(SFO_SFO.ff, FOCUS_2006_D) -# summary(f.noweight) -# f.irls <- mkinfit(SFO_SFO.ff, FOCUS_2006_D, reweight.method = "obs") -# summary(f.irls) -# f.w.mean <- mkinfit(SFO_SFO.ff, FOCUS_2006_D, weight = "mean") -# summary(f.w.mean) -# f.w.value <- mkinfit(SFO_SFO.ff, subset(FOCUS_2006_D, value != 0), err = "value") -# summary(f.w.value) -# ## End(Not run) - -## Not run: -# # Manual weighting -# dw <- FOCUS_2006_D -# errors <- c(parent = 2, m1 = 1) -# dw$err.man <- errors[FOCUS_2006_D$name] -# f.w.man <- mkinfit(SFO_SFO.ff, dw, err = "err.man") -# summary(f.w.man) -# f.w.man.irls <- mkinfit(SFO_SFO.ff, dw, err = "err.man", -# reweight.method = "obs") -# 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 |