aboutsummaryrefslogtreecommitdiff
path: root/docs/articles/FOCUS_Z.Rnw
diff options
context:
space:
mode:
authorJohannes Ranke <jranke@uni-bremen.de>2016-10-26 23:18:20 +0200
committerJohannes Ranke <jranke@uni-bremen.de>2016-10-26 23:18:20 +0200
commit8f38147e145c66ebd27f5d9fcc6f00172c25872f (patch)
tree35123308ef781f6ad4b83b6d421d5e0e35d2e574 /docs/articles/FOCUS_Z.Rnw
parentd106bebafe070cb803dd7205b1581b20eaf61cb5 (diff)
Static documentation rebuilt by pkgdown::build_site()
Diffstat (limited to 'docs/articles/FOCUS_Z.Rnw')
-rw-r--r--docs/articles/FOCUS_Z.Rnw274
1 files changed, 274 insertions, 0 deletions
diff --git a/docs/articles/FOCUS_Z.Rnw b/docs/articles/FOCUS_Z.Rnw
new file mode 100644
index 00000000..5a66db24
--- /dev/null
+++ b/docs/articles/FOCUS_Z.Rnw
@@ -0,0 +1,274 @@
+%\VignetteIndexEntry{Example evaluation of FOCUS dataset Z}
+%\VignetteEngine{knitr::knitr}
+\documentclass[12pt,a4paper]{article}
+\usepackage{a4wide}
+\input{header}
+\hypersetup{
+ pdftitle = {Example evaluation of FOCUS dataset Z},
+ pdfsubject = {Manuscript},
+ pdfauthor = {Johannes Ranke},
+ colorlinks = {true},
+ linkcolor = {blue},
+ citecolor = {blue},
+ urlcolor = {red},
+ hyperindex = {true},
+ linktocpage = {true},
+}
+
+\begin{document}
+
+<<include=FALSE>>=
+require(knitr)
+opts_chunk$set(engine='R', tidy = FALSE, cache = TRUE)
+options(width=70)
+@
+
+\title{Example evaluation of FOCUS dataset Z}
+\author{\textbf{Johannes Ranke} \\[0.5cm]
+%EndAName
+Wissenschaftlicher Berater\\
+Kronacher Str. 8, 79639 Grenzach-Wyhlen, Germany\\[0.5cm]
+and\\[0.5cm]
+University of Bremen\\
+}
+\maketitle
+
+\thispagestyle{empty} \setcounter{page}{0}
+
+\clearpage
+
+\tableofcontents
+
+\textbf{Key words}: Kinetics, FOCUS, nonlinear optimisation
+
+\section{The data}
+
+The following code defines the example dataset from Appendix 7 to the FOCUS kinetics
+report \citep{FOCUSkinetics2011}, p.350.
+
+<<FOCUS_2006_Z_data, echo=TRUE, eval=TRUE>>=
+require(mkin)
+LOD = 0.5
+FOCUS_2006_Z = data.frame(
+ t = c(0, 0.04, 0.125, 0.29, 0.54, 1, 2, 3, 4, 7, 10, 14, 21,
+ 42, 61, 96, 124),
+ Z0 = c(100, 81.7, 70.4, 51.1, 41.2, 6.6, 4.6, 3.9, 4.6, 4.3, 6.8,
+ 2.9, 3.5, 5.3, 4.4, 1.2, 0.7),
+ Z1 = c(0, 18.3, 29.6, 46.3, 55.1, 65.7, 39.1, 36, 15.3, 5.6, 1.1,
+ 1.6, 0.6, 0.5 * LOD, NA, NA, NA),
+ Z2 = c(0, NA, 0.5 * LOD, 2.6, 3.8, 15.3, 37.2, 31.7, 35.6, 14.5,
+ 0.8, 2.1, 1.9, 0.5 * LOD, NA, NA, NA),
+ Z3 = c(0, NA, NA, NA, NA, 0.5 * LOD, 9.2, 13.1, 22.3, 28.4, 32.5,
+ 25.2, 17.2, 4.8, 4.5, 2.8, 4.4))
+
+FOCUS_2006_Z_mkin <- mkin_wide_to_long(FOCUS_2006_Z)
+@
+
+\section{Parent compound and one metabolite}
+
+The next step is to set up the models used for the kinetic analysis. As the
+simultaneous fit of parent and the first metabolite is usually straightforward,
+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=6>>=
+Z.2a <- mkinmod(Z0 = mkinsub("SFO", "Z1"),
+ Z1 = mkinsub("SFO"))
+m.Z.2a <- mkinfit(Z.2a, FOCUS_2006_Z_mkin, quiet = TRUE)
+plot_sep(m.Z.2a)
+summary(m.Z.2a, data = FALSE)$bpar
+@
+
+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\_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=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_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
+large value, and the backtransformed formation fraction from parent Z to Z1 is
+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}.\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_sep(m.Z.3)
+summary(m.Z.3, data = FALSE)$bpar
+@
+
+As there is only one transformation product for Z0 and no pathway
+to sink, the formation fraction is internally fixed to unity.
+
+\section{Including metabolites Z2 and Z3}
+
+As suggested in the FOCUS report, the pathway to sink was removed for metabolite Z1 as
+well in the next step. While this step appears questionable on the basis of the above results, it
+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=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_sep(m.Z.5)
+@
+
+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=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_sep(m.Z.FOCUS)
+summary(m.Z.FOCUS, data = FALSE)$bpar
+endpoints(m.Z.FOCUS)
+@
+
+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}
+
+As the FOCUS report states, there is a certain tailing of the time course of metabolite
+Z3. Also, the time course of the parent compound is not fitted very well using the
+SFO model, as residues at a certain low level remain.
+
+Therefore, an additional model is offered here, using the single first-order
+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=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_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 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_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_sep(m.Z.mkin.3)
+@
+
+This results in a much better representation of the behaviour of the parent
+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=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_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=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
+confidence intervals due to overparameterisation. As the optimized
+\texttt{k\_Z3\_bound\_free} is excessively small, it seems reasonable to fix it to
+zero.
+
+<<FOCUS_2006_Z_fits_11a, echo=TRUE>>=
+m.Z.mkin.5a <- mkinfit(Z.mkin.5, FOCUS_2006_Z_mkin,
+ parms.ini = c(m.Z.mkin.5$bparms.ode[1:7],
+ k_Z3_bound_free = 0),
+ fixed_parms = "k_Z3_bound_free",
+ quiet = TRUE)
+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>>=
+mkinparplot(m.Z.mkin.5a)
+@
+
+The endpoints obtained with this model are
+
+<<FOCUS_2006_Z_fits_11b_endpoints, echo=TRUE>>=
+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 (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}
+
+\end{document}
+% vim: set foldmethod=syntax:

Contact - Imprint