Some additions, fixes and formatting of the help files for mkinfit and mkinpredict.

git-svn-id: svn+ssh://svn.r-forge.r-project.org/svnroot/kinfit/pkg/mkin@110 edb9625f-4e0d-4859-8d74-9fd3b1da38cb

2 files changed, 78 insertions, 65 deletions

diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index a080f8a..750c346 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -5,9 +5,14 @@
 }
 \description{
   This function uses the Flexible Modelling Environment package
-  \code{\link{FME}} to create a function calculating the model cost, which is
-  then minimised, using the specified initial or fixed parameters and starting
-  values.
+  \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, 
@@ -30,19 +35,20 @@ mkinfit(mkinmod, observed,
   }
   \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}}.
+    \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.
+    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
@@ -51,43 +57,48 @@ mkinfit(mkinmod, observed,
     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.
+    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}.
+    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.
+    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).
+    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.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 
+    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}}. 
+    Additional arguments passed to the optimisation method used by
+    \code{\link{modFit}}.
   }
   \item{plot}{
-    Should the observed values and the numerical solutions be plotted at each stage
-    of the optimisation?
+    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?
@@ -96,12 +107,13 @@ mkinfit(mkinmod, observed,
     \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{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.
+    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,
@@ -114,7 +126,7 @@ mkinfit(mkinmod, observed,
   \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} argument. 
+    the numerical solver if that is used (see \code{solution_type} argument. 
     The default value is 100.
   }
   \item{reweight.method}{
@@ -125,7 +137,7 @@ mkinfit(mkinmod, observed,
     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.maxiter}.
+    specified by \code{reweight.max.iter}.
   }
   \item{reweight.tol}{
     Tolerance for convergence criterion for the variance components
diff --git a/man/mkinpredict.Rd b/man/mkinpredict.Rd
index 9d181f5..afb57e0 100644
--- a/man/mkinpredict.Rd
+++ b/man/mkinpredict.Rd
@@ -4,9 +4,9 @@
   Produce predictions from a kinetic model using specifc parameters
 }
 \description{
-  This function produces a time series for all the observed variables in a kinetic model
-  as specified by \code{\link{mkinmod}}, using a specific set of kinetic parameters and
-  initial values for the state variables.
+  This function produces a time series for all the observed variables in a
+  kinetic model as specified by \code{\link{mkinmod}}, using a specific set of
+  kinetic parameters and initial values for the state variables.
 }
 \usage{
   mkinpredict(mkinmod, odeparms, odeini, outtimes, solution_type = "deSolve",
@@ -14,30 +14,31 @@
 }
 \arguments{
   \item{mkinmod}{
-  A kinetic model as produced by \code{\link{mkinmod}}.
+    A kinetic model as produced by \code{\link{mkinmod}}.
   }
   \item{odeparms}{
-  A numeric vector specifying the parameters used in the kinetic model, which is generally
-  defined as a set of ordinary differential equations.
+    A numeric vector specifying the parameters used in the kinetic model, which
+    is generally defined as a set of ordinary differential equations.
   }
   \item{odeini}{
-  A numeric vectory containing the initial values of the state variables of the model. Note
-  that the state variables can differ from the observed variables, for example in the case
-  of the SFORB model.
+    A numeric vectory containing the initial values of the state variables of
+    the model. Note that the state variables can differ from the observed
+    variables, for example in the case of the SFORB model.
   }
   \item{outtimes}{
-  A numeric vector specifying the time points for which model predictions should be 
-  generated.
+    A numeric vector specifying the time points for which model predictions
+    should be generated.
   }
   \item{solution_type}{
-  The method that should be used for producing the predictions. This should
-  generally be "analytical" if there is only one observed variable, and usually
-  "deSolve" in the case of several observed variables. The third possibility "eigen"
-  is faster but produces results that the author believes to be less accurate.
+    The method that should be used for producing the predictions. This should
+    generally be "analytical" if there is only one observed variable, and
+    usually "deSolve" in the case of several observed variables. The third
+    possibility "eigen" is faster but produces results that the author believes
+    to be less accurate.
   }
   \item{map_output}{
-  Boolean to specify if the output should list values for the observed variables (default)
-  or for all state variables (if set to FALSE). 
+    Boolean to specify if the output should list values for the observed
+    variables (default) or for all state variables (if set to FALSE). 
   }
   \item{atol}{
     Absolute error tolerance, passed to \code{\link{ode}}. Default is 1e-8,
@@ -70,10 +71,10 @@
 	      atol = 1e-20)[20,]
 
   # The integration method does not make a lot of difference
-  mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, atol = 1e-20, 
-	      method = "ode45")[20,]
-  mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, atol = 1e-20, 
-	      method = "rk4")[20,]
+  mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, 
+	      atol = 1e-20, method = "ode45")[20,]
+  mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20, 
+	      atol = 1e-20, method = "rk4")[20,]
 
   # The number of output times used to make a lot of difference until the
   # default for atol was adjusted