Fork the gmkin GUI from mkin. See ChangeLog for details

1 files changed, 0 insertions, 254 deletions

diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
deleted file mode 100644
index 823ceee..0000000
--- a/man/mkinfit.Rd
+++ /dev/null
@@ -1,254 +0,0 @@
-\name{mkinfit}
-\alias{mkinfit}
-\title{
-  Fit a kinetic model to data with one or more state variables.
-}
-\description{
-  This function uses the Flexible Modelling Environment package
-  \code{\link{FME}} to create a function calculating the model cost, i.e. the 
-  deviation between the kinetic model and the observed data. This model cost is
-  then minimised using the Levenberg-Marquardt algorithm \code{\link{nls.lm}}, 
-  using the specified initial or fixed parameters and starting values.
-  In each step of the optimsation, the kinetic model is solved using the
-  function \code{\link{mkinpredict}}. The variance of the residuals for each
-  observed variable can optionally be iteratively reweighted until convergence
-  using the argument \code{reweight.method = "obs"}.
-}
-\usage{
-mkinfit(mkinmod, observed, 
-  parms.ini = "auto",
-  state.ini = c(100, rep(0, length(mkinmod$diffs) - 1)), 
-  fixed_parms = NULL, fixed_initials = names(mkinmod$diffs)[-1], 
-  solution_type = "auto",
-  method.ode = "lsoda",
-  method.modFit = "Marq",
-  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, ...)
-}
-\arguments{
-  \item{mkinmod}{
-    A list of class \code{\link{mkinmod}}, containing the kinetic model to be fitted to the data.
-  }
-  \item{observed}{
-    The observed data. It has to be in the long format as described in
-    \code{\link{modFit}}, i.e. the first column called "name" must contain the
-    name of the observed variable for each data point. The second column must
-    contain the times of observation, named "time".  The third column must be
-    named "value" and contain the observed values. Optionally, a further column
-    can contain weights for each data point. If it is not named "err", its name
-    must be passed as a further argument named \code{err} which is then passed
-    on to \code{\link{modFit}}.
-  }
-  \item{parms.ini}{
-    A named vector of initial values for the parameters, including parameters
-    to be optimised and potentially also fixed parameters as indicated by
-    \code{fixed_parms}.  If set to "auto", initial values for rate constants
-    are set to default values.  Using parameter names that are not in the model
-    gives an error.
-
-    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.
-  }
-  \item{state.ini}{
-    A named vector of initial values for the state variables of the model. In
-    case the observed variables are represented by more than one model
-    variable, the names will differ from the names of the observed variables
-    (see \code{map} component of \code{\link{mkinmod}}). The default is to set
-    the initial value of the first model variable to 100 and all others to 0.
-  }
-  \item{fixed_parms}{
-    The names of parameters that should not be optimised but rather kept at the
-    values specified in \code{parms.ini}.
-  }
-  \item{fixed_initials}{
-    The names of model variables for which the initial state at time 0 should
-    be excluded from the optimisation. Defaults to all state variables except
-    for the first one.
-  }
-  \item{solution_type}{
-    If set to "eigen", the solution of the system of differential equations is
-    based on the spectral decomposition of the coefficient matrix in cases that
-    this is possible. If set to "deSolve", a numerical ode solver from package
-    \code{\link{deSolve}} is used. If set to "analytical", an analytical
-    solution of the model is used. This is only implemented for simple
-    degradation experiments with only one state variable, i.e. with no
-    metabolites. The default is "auto", which uses "analytical" if possible,
-    otherwise "eigen" if the model can be expressed using eigenvalues and
-    eigenvectors, and finally "deSolve" for the remaining models (time
-    dependence of degradation rates and metabolites). This argument is passed
-    on to the helper function \code{\link{mkinpredict}}.
-  }
-  \item{method.ode}{
-    The solution method passed via \code{\link{mkinpredict}} to
-    \code{\link{ode}} in case the solution type is "deSolve". The default
-    "lsoda" is performant, but sometimes fails to converge.
-  }
-  \item{method.modFit}{
-    The optimisation method passed to \code{\link{modFit}}. The default "Marq"
-    is the Levenberg Marquardt algorithm \code{\link{nls.lm}} from the package
-    \code{minpack.lm}. Often other methods need more iterations to find the
-    same result. When using "Pseudo", "upper" and "lower" need to be 
-    specified for the transformed parameters.
-  }
-  \item{control.modFit}{
-    Additional arguments passed to the optimisation method used by
-    \code{\link{modFit}}.
-  }
-  \item{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 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.
-    If TRUE, zero is used as a lower bound for the rates in the optimisation.
-  }
-  \item{transform_fractions}{
-    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. 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.
-  }
-  \item{plot}{
-    Should the observed values and the numerical solutions be plotted at each
-    stage of the optimisation?
-  }
-  \item{quiet}{
-    Suppress printing out the current model cost after each improvement?
-  }
-  \item{err }{either \code{NULL}, or the name of the column with the
-    \emph{error} estimates, used to weigh the residuals (see details of
-    \code{\link{modCost}}); if \code{NULL}, then the residuals are not weighed.
-  }
-  \item{weight}{
-    only if \code{err}=\code{NULL}: how to weight the residuals, one of "none",
-    "std", "mean", see details of \code{\link{modCost}}.
-  }
-  \item{scaleVar}{
-    Will be passed to \code{\link{modCost}}. Default is not to scale Variables
-    according to the number of observations.
-  }
-  \item{atol}{
-    Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-8,
-    lower than in \code{\link{lsoda}}.
-  }
-  \item{rtol}{
-    Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-10,
-    much lower than in \code{\link{lsoda}}.
-  }
-  \item{n.outtimes}{
-    The length of the dataseries that is produced by the model prediction
-    function \code{\link{mkinpredict}}. This impacts the accuracy of
-    the numerical solver if that is used (see \code{solution_type} argument. 
-    The default value is 100.
-  }
-  \item{reweight.method}{
-    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} or up to the maximum number of iterations
-    specified by \code{reweight.max.iter}.
-  }
-  \item{reweight.tol}{
-    Tolerance for convergence criterion for the variance components
-    in IRLS fits.
-  }
-  \item{reweight.max.iter}{
-    Maximum iterations in IRLS fits.
-  }
-  \item{trace_parms}{
-    Should a trace of the parameter values be listed?
-  }
-  \item{\dots}{
-    Further arguments that will be passed to \code{\link{modFit}}. 
-  }
-}
-\value{
-  A list with "mkinfit" and "modFit" in the class attribute. 
-  A summary can be obtained by \code{\link{summary.mkinfit}}. 
-}
-\note{
-  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.
-}
-\author{
-  Johannes Ranke <jranke@uni-bremen.de>
-}
-\examples{
-# One parent compound, one metabolite, both single first order.
-SFO_SFO <- mkinmod(
-  parent = list(type = "SFO", to = "m1", sink = TRUE),
-  m1 = list(type = "SFO"))
-# Fit the model to the FOCUS example dataset D using defaults
-fit <- mkinfit(SFO_SFO, FOCUS_2006_D)
-summary(fit)
-
-# Use stepwise fitting, using optimised parameters from parent only fit, FOMC
-\dontrun{
-FOMC <- mkinmod(parent = list(type = "FOMC"))
-FOMC_SFO <- mkinmod(
-  parent = list(type = "FOMC", to = "m1", sink = TRUE),
-  m1 = list(type = "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 <- mkinmod(parent = list(type = "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)
-# 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)
-}
-
-# Weighted fits, including IRLS
-SFO_SFO.ff <- mkinmod(parent = list(type = "SFO", to = "m1"),
-                      m1 = list(type = "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.mean.irls <- mkinfit(SFO_SFO.ff, FOCUS_2006_D, weight = "mean",
-                         reweight.method = "obs")
-summary(f.w.mean.irls)
-
-\dontrun{
-# 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)
-}
-}
-\keyword{ models }
-\keyword{ optimize }