Convenience wrapper plot_sep, further vignette updates

3 files changed, 94 insertions, 122 deletions

diff --git a/vignettes/FOCUS_Z.Rnw b/vignettes/FOCUS_Z.Rnw
index 8c94352c..a010a85c 100644
--- a/vignettes/FOCUS_Z.Rnw
+++ b/vignettes/FOCUS_Z.Rnw
@@ -72,31 +72,33 @@ Step 1 (SFO for parent only) is skipped here. We start with the model 2a,
 with formation and decline of metabolite Z1 and the pathway from parent
 directly to sink included (default in mkin).
 
-<<FOCUS_2006_Z_fits_1, echo=TRUE, fig.height=4>>=
-Z.2a <- mkinmod(Z0 = list(type = "SFO", to = "Z1"),
-                Z1 = list(type = "SFO"))
+<<FOCUS_2006_Z_fits_1, echo=TRUE, fig.height=6>>=
+Z.2a <- mkinmod(Z0 = mkinsub("SFO", "Z1"),
+                Z1 = mkinsub("SFO"))
 m.Z.2a <- mkinfit(Z.2a, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.2a)
-summary(m.Z.2a, data = FALSE)
+plot(m.Z.2a, show_errmin = TRUE, show_residuals = TRUE)
+summary(m.Z.2a, data = FALSE)$bpar
 @
 
-As obvious from the summary, the kinetic rate constant from parent compound Z to sink
+As obvious from the parameter summary (the \texttt{bpar} component of the 
+summary), the kinetic rate constant from parent compound Z to sink
 is negligible. Accordingly, the exact magnitude of the fitted parameter 
-\texttt{log k\_Z\_sink} is ill-defined and the covariance matrix is not returned.
-This suggests, in agreement with the analysis in the FOCUS kinetics report, to simplify 
-the model by removing the pathway to sink.
+\texttt{log k\_Z0\_sink} is ill-defined and the covariance matrix is not
+returned (not shown, would be visible in the complete summary). 
+This suggests, in agreement with the analysis in the FOCUS kinetics report, to
+simplify the model by removing the pathway to sink.
 
 A similar result can be obtained when formation fractions are used in the model 
 formulation:
 
-<<FOCUS_2006_Z_fits_2, echo=TRUE, fig.height=4>>=
-Z.2a.ff <- mkinmod(Z0 = list(type = "SFO", to = "Z1"),
-                   Z1 = list(type = "SFO"),
+<<FOCUS_2006_Z_fits_2, echo=TRUE, fig.height=6>>=
+Z.2a.ff <- mkinmod(Z0 = mkinsub("SFO", "Z1"),
+                   Z1 = mkinsub("SFO"),
                    use_of_ff = "max")
 
 m.Z.2a.ff <- mkinfit(Z.2a.ff, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.2a.ff)
-summary(m.Z.2a.ff, data = FALSE)
+plot_sep(m.Z.2a.ff)
+summary(m.Z.2a.ff, data = FALSE)$bpar
 @
 
 Here, the ilr transformed formation fraction fitted in the model takes a very
@@ -105,14 +107,21 @@ practically unity. Again, the covariance matrix is not returned as the model is
 overparameterised. 
 
 The simplified model is obtained by setting the list component \texttt{sink} to
-\texttt{FALSE}. 
-
-<<FOCUS_2006_Z_fits_3, echo=TRUE, fig.height=4>>=
-Z.3 <- mkinmod(Z0 = list(type = "SFO", to = "Z1", sink = FALSE),
-               Z1 = list(type = "SFO"), use_of_ff = "max")
+\texttt{FALSE}.\footnote{If the model formulation without formation fractions
+is used, the same effect can be obtained by fixing the parameter \texttt{k\_Z\_sink}
+to a value of zero.} 
+
+In the following, we use the parameterisation with formation fractions in order
+to be able to compare with the results in the FOCUS guidance, and as it 
+makes it easier to use parameters obtained in a previous fit when adding a further 
+metabolite.
+
+<<FOCUS_2006_Z_fits_3, echo=TRUE, fig.height=6>>=
+Z.3 <- mkinmod(Z0 = mkinsub("SFO", "Z1", sink = FALSE),
+               Z1 = mkinsub("SFO"), use_of_ff = "max")
 m.Z.3 <- mkinfit(Z.3, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.3)
-summary(m.Z.3, data = FALSE)
+plot_sep(m.Z.3)
+summary(m.Z.3, data = FALSE)$bpar
 @
 
 As there is only one transformation product for Z0 and no pathway
@@ -126,54 +135,35 @@ is followed here for the purpose of comparison. Also, in the FOCUS report, it is
 assumed that there is additional empirical evidence that Z1 quickly and exclusively
 hydrolyses to Z2. 
 
-<<FOCUS_2006_Z_fits_5, echo=TRUE, fig.height=4>>=
-Z.5 <- mkinmod(Z0 = list(type = "SFO", to = "Z1", sink = FALSE),
-               Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-               Z2 = list(type = "SFO"))
+<<FOCUS_2006_Z_fits_5, echo=TRUE, fig.height=7>>=
+Z.5 <- mkinmod(Z0 = mkinsub("SFO", "Z1", sink = FALSE),
+               Z1 = mkinsub("SFO", "Z2", sink = FALSE),
+               Z2 = mkinsub("SFO"), use_of_ff = "max")
 m.Z.5 <- mkinfit(Z.5, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.5)
-summary(m.Z.5, data = FALSE)
+plot_sep(m.Z.5)
 @
 
-Finally, metabolite Z3 is added to the model. The fit is accellerated
-by using the starting parameters from the previous fit.
+Finally, metabolite Z3 is added to the model. We use the optimised
+differential equation parameter values from the previous fit in order to
+accelerate the optimization.
 
-<<FOCUS_2006_Z_fits_6, echo=TRUE, fig.height=4>>=
-Z.FOCUS <- mkinmod(Z0 = list(type = "SFO", to = "Z1", sink = FALSE),
-                   Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-                   Z2 = list(type = "SFO", to = "Z3"),
-                   Z3 = list(type = "SFO"))
+<<FOCUS_2006_Z_fits_6, echo=TRUE, fig.height=8>>=
+Z.FOCUS <- mkinmod(Z0 = mkinsub("SFO", "Z1", sink = FALSE),
+                   Z1 = mkinsub("SFO", "Z2", sink = FALSE),
+                   Z2 = mkinsub("SFO", "Z3"),
+                   Z3 = mkinsub("SFO"), 
+                   use_of_ff = "max")
 m.Z.FOCUS <- mkinfit(Z.FOCUS, FOCUS_2006_Z_mkin, 
+                     parms.ini = m.Z.5$bparms.ode,
                      quiet = TRUE)
-plot(m.Z.FOCUS)
-summary(m.Z.FOCUS, data = FALSE)
-@
-
-This is the fit corresponding to the final result chosen in Appendix 7 of the 
-FOCUS report. The residual plots can be obtained by
-
-<<FOCUS_2006_Z_residuals_6, echo=TRUE>>=
-par(mfrow = c(2, 2))
-mkinresplot(m.Z.FOCUS, "Z0", lpos = "bottomright")
-mkinresplot(m.Z.FOCUS, "Z1", lpos = "bottomright")
-mkinresplot(m.Z.FOCUS, "Z2", lpos = "bottomright")
-mkinresplot(m.Z.FOCUS, "Z3", lpos = "bottomright")
+plot_sep(m.Z.FOCUS)
+summary(m.Z.FOCUS, data = FALSE)$bpar
+endpoints(m.Z.FOCUS)
 @
 
-We can also investigate the confidence interval for the formation
-fraction from Z2 to Z3 by specifying the model using formation
-fractions.
-
-<<FOCUS_2006_Z_fits_6_ff, echo=TRUE, fig.height=4>>=
-Z.FOCUS.ff <- mkinmod(Z0 = list(type = "SFO", to = "Z1", sink = FALSE),
-                   Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-                   Z2 = list(type = "SFO", to = "Z3"),
-                   Z3 = list(type = "SFO"), 
-                   use_of_ff = "max")
-m.Z.FOCUS.ff <- mkinfit(Z.FOCUS.ff, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.FOCUS.ff)
-summary(m.Z.FOCUS.ff, data = FALSE)
-@
+This fit corresponds to the final result chosen in Appendix 7 of the FOCUS
+report. Confidence intervals returned by mkin are based on internally
+transformed parameters, however.
 
 \section{Using the SFORB model for parent and metabolites}
 
@@ -186,38 +176,26 @@ reversible binding (SFORB) model for metabolite Z3. As expected, the $\chi^2$
 error level is lower for metabolite Z3 using this model and the graphical 
 fit for Z3 is improved. However, the covariance matrix is not returned.
 
-<<FOCUS_2006_Z_fits_7, echo=TRUE, fig.height=4>>=
-Z.mkin.1 <- mkinmod(Z0 = list(type = "SFO", to = "Z1", sink = FALSE),
-                    Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-                    Z2 = list(type = "SFO", to = "Z3"),
-                    Z3 = list(type = "SFORB"))
+<<FOCUS_2006_Z_fits_7, echo=TRUE, fig.height=8>>=
+Z.mkin.1 <- mkinmod(Z0 = mkinsub("SFO", "Z1", sink = FALSE),
+                    Z1 = mkinsub("SFO", "Z2", sink = FALSE),
+                    Z2 = mkinsub("SFO", "Z3"),
+                    Z3 = mkinsub("SFORB"))
 m.Z.mkin.1 <- mkinfit(Z.mkin.1, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.mkin.1)
-summary(m.Z.mkin.1, data = FALSE)
+plot_sep(m.Z.mkin.1)
+summary(m.Z.mkin.1, data = FALSE)$cov.unscaled
 @
 
 Therefore, a further stepwise model building is performed starting from the
-stage of parent and one metabolite, starting from the assumption that the model
+stage of parent and two metabolites, starting from the assumption that the model
 fit for the parent compound can be improved by using the SFORB model.
 
-<<FOCUS_2006_Z_fits_8, echo=TRUE, fig.height=4>>=
-Z.mkin.2 <- mkinmod(Z0 = list(type = "SFORB", to = "Z1", sink = FALSE),
-                    Z1 = list(type = "SFO"))
-m.Z.mkin.2 <- mkinfit(Z.mkin.2, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.mkin.2)
-summary(m.Z.mkin.2, data = FALSE)
-@
-
-When metabolite Z2 is added, the additional sink for Z1 is turned off again,
-for the same reasons as in the original analysis.
-
-<<FOCUS_2006_Z_fits_9, echo=TRUE, fig.height=4>>=
-Z.mkin.3 <- mkinmod(Z0 = list(type = "SFORB", to = "Z1", sink = FALSE),
-                    Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-                    Z2 = list(type = "SFO"))
+<<FOCUS_2006_Z_fits_9, echo=TRUE, fig.height=8>>=
+Z.mkin.3 <- mkinmod(Z0 = mkinsub("SFORB", "Z1", sink = FALSE),
+                    Z1 = mkinsub("SFO", "Z2", sink = FALSE),
+                    Z2 = mkinsub("SFO"))
 m.Z.mkin.3 <- mkinfit(Z.mkin.3, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.mkin.3)
-summary(m.Z.mkin.3, data = FALSE)
+plot_sep(m.Z.mkin.3)
 @
 
 This results in a much better representation of the behaviour of the parent 
@@ -226,29 +204,30 @@ compound Z0.
 Finally, Z3 is added as well. These models appear overparameterised (no
 covariance matrix returned) if the sink for Z1 is left in the models.
 
-<<FOCUS_2006_Z_fits_10, echo=TRUE, fig.height=4>>=
-Z.mkin.4 <- mkinmod(Z0 = list(type = "SFORB", to = "Z1", sink = FALSE),
-                    Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-                    Z2 = list(type = "SFO", to = "Z3"),
-                    Z3 = list(type = "SFO"))
+<<FOCUS_2006_Z_fits_10, echo=TRUE, fig.height=8>>=
+Z.mkin.4 <- mkinmod(Z0 = mkinsub("SFORB", "Z1", sink = FALSE),
+                    Z1 = mkinsub("SFO", "Z2", sink = FALSE),
+                    Z2 = mkinsub("SFO", "Z3"),
+                    Z3 = mkinsub("SFO"))
 m.Z.mkin.4 <- mkinfit(Z.mkin.4, FOCUS_2006_Z_mkin, 
+                      parms.ini = m.Z.mkin.3$bparms.ode,
                       quiet = TRUE)
-plot(m.Z.mkin.4)
-summary(m.Z.mkin.4, data = FALSE)
+plot_sep(m.Z.mkin.4)
 @
 
 The error level of the fit, but especially of metabolite Z3, can be improved if
 the SFORB model is chosen for this metabolite, as this model is capable of
 representing the tailing of the metabolite decline phase.
 
-<<FOCUS_2006_Z_fits_11, echo=TRUE, fig.height=4>>=
-Z.mkin.5 <- mkinmod(Z0 = list(type = "SFORB", to = "Z1", sink = FALSE),
-                    Z1 = list(type = "SFO", to = "Z2", sink = FALSE),
-                    Z2 = list(type = "SFO", to = "Z3"),
-                    Z3 = list(type = "SFORB"))
-m.Z.mkin.5 <- mkinfit(Z.mkin.5, FOCUS_2006_Z_mkin, quiet = TRUE)
-plot(m.Z.mkin.5)
-summary(m.Z.mkin.5, data = FALSE)$bpar
+<<FOCUS_2006_Z_fits_11, echo=TRUE, fig.height=8>>=
+Z.mkin.5 <- mkinmod(Z0 = mkinsub("SFORB", "Z1", sink = FALSE),
+                    Z1 = mkinsub("SFO", "Z2", sink = FALSE),
+                    Z2 = mkinsub("SFO", "Z3"),
+                    Z3 = mkinsub("SFORB"))
+m.Z.mkin.5 <- mkinfit(Z.mkin.5, FOCUS_2006_Z_mkin, 
+                      parms.ini = m.Z.mkin.4$bparms.ode[1:4],
+                      quiet = TRUE)
+plot_sep(m.Z.mkin.5)
 @
 
 The summary view of the backtransformed parameters shows that we get no
@@ -258,12 +237,18 @@ zero.
 
 <<FOCUS_2006_Z_fits_11a, echo=TRUE>>=
 m.Z.mkin.5a <- mkinfit(Z.mkin.5, FOCUS_2006_Z_mkin, 
-                       parms.ini = c(k_Z3_bound_free = 0),
+                       parms.ini = c(m.Z.mkin.5$bparms.ode[1:7],
+                                     k_Z3_bound_free = 0),
                        fixed_parms = "k_Z3_bound_free",
                        quiet = TRUE)
-summary(m.Z.mkin.5a, data = FALSE)$bpar
+plot_sep(m.Z.mkin.5a)
 @
 
+As expected, the residual plots for Z0 and Z3 are more random than in the case of the 
+all SFO model for which they were shown above. In conclusion, the model
+\texttt{Z.mkin.5a} is proposed as the best-fit model for the dataset from
+Appendix 7 of the FOCUS report.
+
 A graphical representation of the confidence intervals can finally be obtained.
 
 <<FOCUS_2006_Z_fits_11b, echo=TRUE>>=
@@ -277,21 +262,10 @@ endpoints(m.Z.mkin.5a)
 @
 
 It is clear the degradation rate of Z3 towards the end of the experiment 
-is very low as DT50\_Z3\_b2 is reported to be infinity.  However, this appears to
-be a feature of the data.
-
-<<FOCUS_2006_Z_residuals_11>>=
-par(mfrow = c(2, 2))
-mkinresplot(m.Z.mkin.5, "Z0", lpos = "bottomright")
-mkinresplot(m.Z.mkin.5, "Z1", lpos = "bottomright")
-mkinresplot(m.Z.mkin.5, "Z2", lpos = "bottomright")
-mkinresplot(m.Z.mkin.5, "Z3", lpos = "bottomright")
-@
-
-As expected, the residual plots are much more random than in the case of the 
-all SFO model for which they were shown above. In conclusion, the model
-\texttt{Z.mkin.5} is proposed as the best-fit model for the dataset from
-Appendix 7 of the FOCUS report.
+is very low as DT50\_Z3\_b2 (the second Eigenvalue of the system of two differential 
+equations representing the SFORB system for Z3, corresponding to the slower rate
+constant of the DFOP model) is reported to be infinity.  However, this appears
+to be a feature of the data.
 
 \bibliographystyle{plainnat}
 \bibliography{references}
diff --git a/vignettes/compiled_models.Rmd b/vignettes/compiled_models.Rmd
index 97ef081e..03604cc7 100644
--- a/vignettes/compiled_models.Rmd
+++ b/vignettes/compiled_models.Rmd
@@ -4,10 +4,9 @@ author: "Johannes Ranke"
 date: "`r Sys.Date()`"

 output:

   html_document:

-    css: mkin_vignettes.css

     toc: true

+    toc_float: true

     mathjax: null

-    theme: united

 vignette: >

   %\VignetteIndexEntry{Performance benefit by using compiled model definitions in mkin}

   %\VignetteEngine{knitr::rmarkdown}

diff --git a/vignettes/mkin.Rmd b/vignettes/mkin.Rmd
index f2e1adb4..03e8548a 100644
--- a/vignettes/mkin.Rmd
+++ b/vignettes/mkin.Rmd
@@ -52,8 +52,7 @@ d_SFO_SFO_SFO_err <- add_err(d_SFO_SFO_SFO, function(x) 3, n = 1, seed = 1234567
 
 f_SFO_SFO_SFO <- mkinfit(m_SFO_SFO_SFO, d_SFO_SFO_SFO_err[[1]], quiet = TRUE)
 
-plot.mkinfit(f_SFO_SFO_SFO, sep_obs = TRUE, show_residuals = TRUE, show_errmin = TRUE,
-             lpos = c("topright", "bottomright", "bottomright"))
+plot_sep(f_SFO_SFO_SFO, lpos = c("topright", "bottomright", "bottomright"))
 ```
 
 # Background