From 71d43b104999d7aee96d35ff2a9006f739d2df60 Mon Sep 17 00:00:00 2001
From: Johannes Ranke <jranke@uni-bremen.de>
Date: Tue, 1 Jul 2014 23:23:52 +0200
Subject: Support formation fractions without sink pathway, updates

---
 man/mkinfit.Rd            | 13 ++++++++----
 man/mkinparplot.Rd        |  5 ++---
 man/transform_odeparms.Rd | 50 ++++++++++++++++++++++++++++++++++++++---------
 3 files changed, 52 insertions(+), 16 deletions(-)

(limited to 'man')

diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index 823ceeec..bd7f73b7 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -94,11 +94,16 @@ mkinfit(mkinmod, observed,
     "lsoda" is performant, but sometimes fails to converge.
   }
   \item{method.modFit}{
-    The optimisation method passed to \code{\link{modFit}}. The default "Marq"
+    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.
+    \code{minpack.lm} and usually needs the least number of iterations.
+
+    For more complex problems where local minima occur, the "Port" algorithm is
+    recommended as it is less prone to get trapped in local minima and depends
+    less on starting values for parameters.  However, it needs more iterations.
+
+    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
diff --git a/man/mkinparplot.Rd b/man/mkinparplot.Rd
index 60103b89..f40a96d1 100644
--- a/man/mkinparplot.Rd
+++ b/man/mkinparplot.Rd
@@ -25,11 +25,10 @@
 
 \examples{
 model <- mkinmod(
-  T245 = list(type = "SFO", to = c("phenol")),
+  T245 = list(type = "SFO", to = c("phenol"), sink = FALSE),
   phenol = list(type = "SFO", to = c("anisole")),
   anisole = list(type = "SFO"), use_of_ff = "max")
-fit <- mkinfit(model, subset(mccall81_245T, soil == "Commerce"), 
-  parms.ini = c(f_phenol_to_anisole = 1), fixed_parms = "f_phenol_to_anisole")
+fit <- mkinfit(model, subset(mccall81_245T, soil == "Commerce"))
 \dontrun{mkinparplot(fit)}
 }
 \keyword{ hplot }
diff --git a/man/transform_odeparms.Rd b/man/transform_odeparms.Rd
index c52fb4f1..ea0b5024 100644
--- a/man/transform_odeparms.Rd
+++ b/man/transform_odeparms.Rd
@@ -11,10 +11,15 @@
   simple log transformation is used. For compositional parameters, such as
   the formations fractions that should always sum up to 1 and can not be
   negative, the \code{\link{ilr}} transformation is used.
+
+  The transformation of sets of formation fractions is fragile, as it supposes
+  the same ordering of the components in forward and backward transformation.
+  This is no problem for the internal use in \code{\link{mkinfit}}.
 }
 \usage{
-transform_odeparms(parms, mod_vars, transform_rates = TRUE, transform_fractions = TRUE)
-backtransform_odeparms(transparms, mod_vars, 
+transform_odeparms(parms, mkinmod, 
+                   transform_rates = TRUE, transform_fractions = TRUE)
+backtransform_odeparms(transparms, mkinmod, 
                        transform_rates = TRUE, transform_fractions = TRUE)
 }
 \arguments{
@@ -24,9 +29,11 @@ backtransform_odeparms(transparms, mod_vars,
   \item{transparms}{
     Transformed parameters of kinetic models as used in the fitting procedure.
   }
-  \item{mod_vars}{
-    Names of the state variables in the kinetic model. These are used for 
-    grouping the formation fractions before \code{\link{ilr}} transformation.  
+  \item{mkinmod}{
+    The kinetic model of class \code{\link{mkinmod}}, containing the names of
+    the model variables that are needed for grouping the formation fractions
+    before \code{\link{ilr}} transformation, the parameter names and 
+    the information if the pathway to sink is included in the model. 
   }
   \item{transform_rates}{
     Boolean specifying if kinetic rate constants should be transformed in the
@@ -59,11 +66,36 @@ SFO_SFO <- mkinmod(
   m1 = list(type = "SFO"))
 # Fit the model to the FOCUS example dataset D using defaults
 fit <- mkinfit(SFO_SFO, FOCUS_2006_D)
+fit.2 <- mkinfit(SFO_SFO, FOCUS_2006_D, transform_rates = FALSE)
 summary(fit, data=FALSE) # See transformed and backtransformed parameters
+summary(fit.2, data=FALSE) 
 initials <- fit$start$value
-transformed <- fit$start$transformed
-names(initials) <- names(transformed) <- rownames(fit$start)
-transform_odeparms(initials, c("parent", "m1"))
-backtransform_odeparms(transformed, c("parent", "m1"))
+names(initials) <- rownames(fit$start)
+transformed <- fit$start_transformed$value
+names(transformed) <- rownames(fit$start_transformed)
+transform_odeparms(initials, SFO_SFO)
+backtransform_odeparms(transformed, SFO_SFO)
+
+# The case of formation fractions
+SFO_SFO.ff <- mkinmod(
+  parent = list(type = "SFO", to = "m1", sink = TRUE),
+  m1 = list(type = "SFO"),
+  use_of_ff = "max")
+
+fit.ff <- mkinfit(SFO_SFO.ff, FOCUS_2006_D)
+summary(fit.ff, data = FALSE)
+initials <- c("f_parent_to_m1" = 0.5)
+transformed <- transform_odeparms(initials, SFO_SFO.ff)
+backtransform_odeparms(transformed, SFO_SFO.ff)
+
+# And without sink
+SFO_SFO.ff.2 <- mkinmod(
+  parent = list(type = "SFO", to = "m1", sink = FALSE),
+  m1 = list(type = "SFO"),
+  use_of_ff = "max")
+
+
+fit.ff.2 <- mkinfit(SFO_SFO.ff.2, FOCUS_2006_D)
+summary(fit.ff.2, data = FALSE)
 }
 \keyword{ manip }
-- 
cgit v1.2.1