Add functionality to plot the error model

by plotting squared residuals against predicted values, and
showing the variance function used in the fitted error model.

Rebuild docs

3 files changed, 106 insertions, 7 deletions

diff --git a/man/mkinerrplot.Rd b/man/mkinerrplot.Rd
new file mode 100644
index 00000000..4cbb5eb7
--- /dev/null
+++ b/man/mkinerrplot.Rd
@@ -0,0 +1,75 @@
+\name{mkinerrplot}
+\alias{mkinerrplot}
+\title{
+  Function to plot squared residuals and the error model for an mkin object
+}
+\description{
+  This function plots the squared residuals for the specified subset of the
+  observed variables from an mkinfit object. In addition, one or more
+  dashed line(s) show the fitted error model.
+  A combined plot of the fitted model and this error model plot can be
+  obtained with \code{\link{plot.mkinfit}}
+  using the argument \code{show_errplot = TRUE}.
+}
+\usage{
+  mkinerrplot(object,
+    obs_vars = names(object$mkinmod$map),
+    xlim = c(0, 1.1 * max(object$data$predicted)),
+    xlab = "Predicted", ylab = "Squared residual",
+    maxy = "auto", legend= TRUE, lpos = "topright",
+    col_obs = "auto", pch_obs = "auto",
+    ...)
+}
+\arguments{
+  \item{object}{
+    A fit represented in an \code{\link{mkinfit}} object.
+  }
+  \item{obs_vars}{
+    A character vector of names of the observed variables for which residuals
+    should be plotted. Defaults to all observed variables in the model
+  }
+  \item{xlim}{
+    plot range in x direction.
+  }
+  \item{xlab}{
+    Label for the x axis.
+  }
+  \item{ylab}{
+    Label for the y axis.
+  }
+  \item{maxy}{
+    Maximum value of the residuals. This is used for the scaling of
+    the y axis and defaults to "auto".
+  }
+  \item{legend}{
+    Should a legend be plotted?
+  }
+  \item{lpos}{
+    Where should the legend be placed? Default is "topright". Will be passed on to
+    \code{\link{legend}}.
+  }
+  \item{col_obs}{
+    Colors for the observed variables.
+  }
+  \item{pch_obs}{
+    Symbols to be used for the observed variables.
+  }
+  \item{\dots}{
+   further arguments passed to \code{\link{plot}}.
+  }
+}
+\value{
+  Nothing is returned by this function, as it is called for its side effect, namely to produce a plot.
+}
+\author{
+  Johannes Ranke
+}
+\seealso{
+ \code{\link{mkinplot}}, for a way to plot the data and the fitted lines of the
+ mkinfit object.  }
+\examples{
+model <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"))
+fit <- mkinfit(model, FOCUS_2006_D, error_model = "tc", quiet = TRUE)
+mkinerrplot(fit)
+}
+\keyword{ hplot }
diff --git a/man/plot.mkinfit.Rd b/man/plot.mkinfit.Rd
index 733cdf76..9514c5e5 100644
--- a/man/plot.mkinfit.Rd
+++ b/man/plot.mkinfit.Rd
@@ -10,7 +10,7 @@
   the observed data together with the solution of the fitted model.
 
   If the current plot device is a \code{\link[tikzDevice]{tikz}} device,
-  then latex is being used for the formatting of the chi2 error level, 
+  then latex is being used for the formatting of the chi2 error level,
   if \code{show_errmin = TRUE}.
 }
 \usage{
@@ -22,7 +22,9 @@
   col_obs = 1:length(obs_vars), pch_obs = col_obs,
   lty_obs = rep(1, length(obs_vars)),
   add = FALSE, legend = !add,
-  show_residuals = FALSE, maxabs = "auto",
+  show_residuals = FALSE,
+  show_errplot = FALSE,
+  maxabs = "auto",
   sep_obs = FALSE, rel.height.middle = 0.9,
   lpos = "topright", inset = c(0.05, 0.05),
   show_errmin = FALSE, errmin_digits = 3, \dots)
@@ -69,10 +71,16 @@ plot_sep(fit, sep_obs = TRUE,  show_residuals = TRUE, show_errmin = TRUE, \dots)
   }
   \item{show_residuals}{
     Should residuals be shown? If only one plot of the fits is shown, the
-    residual plot is in the lower third of the plot? Otherwise, i.e. if
+    residual plot is in the lower third of the plot. Otherwise, i.e. if
     "sep_obs" is given, the residual plots will be located to the right of
     the plots of the fitted curves.
   }
+  \item{show_errplot}{
+    Should squared residuals and the error model be shown? If only one plot of
+    the fits is shown, this plot is in the lower third of the plot.
+    Otherwise, i.e. if "sep_obs" is given, the residual plots will be located
+    to the right of the plots of the fitted curves.
+  }
   \item{maxabs}{
     Maximum absolute value of the residuals. This is used for the scaling of
     the y axis and defaults to "auto".
@@ -109,9 +117,10 @@ plot_sep(fit, sep_obs = TRUE,  show_residuals = TRUE, show_errmin = TRUE, \dots)
 # parent to sink included
 SFO_SFO <- mkinmod(parent = mkinsub("SFO", "m1", full = "Parent"),
                    m1 = mkinsub("SFO", full = "Metabolite M1" ))
-fit <- mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE)
+fit <- mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE, error_model = "tc")
 plot(fit)
 plot(fit, show_residuals = TRUE)
+plot(fit, show_errplot = TRUE)
 
 # Show the observed variables separately
 plot(fit, sep_obs = TRUE, lpos = c("topright", "bottomright"))
@@ -122,6 +131,10 @@ plot(fit, sep_obs = TRUE, show_residuals = TRUE, lpos = c("topright", "bottomrig
 
 # The same can be obtained with less typing, using the convenience function plot_sep
 plot_sep(fit, lpos = c("topright", "bottomright"))
+
+# Show the observed variables separately, with the error model
+plot(fit, sep_obs = TRUE, show_errplot = TRUE, lpos = c("topright", "bottomright"),
+     show_errmin = TRUE)
 }
 \author{
   Johannes Ranke
diff --git a/man/plot.mmkin.Rd b/man/plot.mmkin.Rd
index b3312292..44e5e4c7 100644
--- a/man/plot.mmkin.Rd
+++ b/man/plot.mmkin.Rd
@@ -12,8 +12,9 @@
   then latex is being used for the formatting of the chi2 error level.
 }
 \usage{
-\method{plot}{mmkin}(x, main = "auto", legends = 1, errmin_var = "All data", errmin_digits = 3,
-              cex = 0.7, rel.height.middle = 0.9, ...)
+\method{plot}{mmkin}(x, main = "auto", legends = 1,
+  resplot = c("time", "errmod"), errmin_var = "All data", errmin_digits = 3,
+  cex = 0.7, rel.height.middle = 0.9, ...)
 }
 \arguments{
   \item{x}{
@@ -25,6 +26,11 @@
   \item{legends}{
     An index for the fits for which legends should be shown.
 }
+  \item{resplot}{
+    Should the residuals plotted against time, using \code{\link{mkinresplot}},
+    or as squared residuals against predicted values, with the error model,
+    using \code{\link{mkinerrplot}}.
+}
   \item{errmin_var}{
     The variable for which the FOCUS chi2 error value should be shown.
 }
@@ -48,10 +54,11 @@
   Johannes Ranke
 }
 \examples{
+  \dontrun{
   # Only use one core not to offend CRAN checks
   fits <- mmkin(c("FOMC", "HS"),
                 list("FOCUS B" = FOCUS_2006_B, "FOCUS C" = FOCUS_2006_C), # named list for titles
-                cores = 1, quiet = TRUE)
+                cores = 1, quiet = TRUE, error_model = "tc")
   plot(fits[, "FOCUS C"])
   plot(fits["FOMC", ])
 
@@ -59,4 +66,8 @@
   # height should be smaller than the plot width (this is not possible for the html pages
   # generated by pkgdown, as far as I know).
   plot(fits["FOMC", "FOCUS C"]) # same as plot(fits[1, 2])
+
+  # Show the error models
+  plot(fits["FOMC", ], resplot = "errmod")
+  }
 }