Depend on parallel, doc improvements

By depending on parallel instead of importing it, functions to set up
and stop a cluster are always available when mkin is loaded.

The use of multicore processing in mmkin on Windows is now documented in
the help file, which brings mkin closer to a version 1.0 #9.

3 files changed, 24 insertions, 25 deletions

diff --git a/R/mkinmod.R b/R/mkinmod.R
index a410c02d..1af72db5 100644
--- a/R/mkinmod.R
+++ b/R/mkinmod.R
@@ -29,11 +29,12 @@
 #'   (default) and the model for the compartment is "SFO" or "SFORB", an
 #'   additional [mkinsub()] argument can be \code{sink = FALSE}, effectively
 #'   fixing the flux to sink to zero.
+#'   In print.mkinmod, this argument is currently not used.
 #' @param use_of_ff Specification of the use of formation fractions in the
-#'   model equations and, if applicable, the coefficient matrix. If "min", a
-#'   minimum use of formation fractions is made in order to avoid fitting the
-#'   product of formation fractions and rate constants. If "max", formation
-#'   fractions are always used.
+#'   model equations and, if applicable, the coefficient matrix.  If "max",
+#'   formation fractions are always used (default).  If "min", a minimum use of
+#'   formation fractions is made, i.e. each pathway to a metabolite has its
+#'   own rate constant. 
 #' @param speclist The specification of the observed variables and their
 #'   submodel types and pathways can be given as a single list using this
 #'   argument. Default is NULL.
@@ -91,6 +92,11 @@
 #'   m1 = mkinsub("SFO"))
 #'
 #' \dontrun{
+#' # Now supplying full names used for plotting
+#'  SFO_SFO.2 <- mkinmod(
+#'    parent = mkinsub("SFO", "m1", full_name = "Test compound"),
+#'    m1 = mkinsub("SFO", full_name = "Metabolite M1"))
+#'
 #' # The above model used to be specified like this, before the advent of mkinsub()
 #' SFO_SFO <- mkinmod(
 #'   parent = list(type = "SFO", to = "m1"),
@@ -111,7 +117,7 @@
 #'  parent = mkinsub("DFOP", c("M1", "M2")),
 #'  M1 = mkinsub("SFO"),
 #'  M2 = mkinsub("SFO"),
-#'  use_of_ff = "max", quiet = TRUE)
+#'  quiet = TRUE)
 #'
 #' fit_DFOP_par_c <- mkinfit(m_synth_DFOP_par,
 #'   synthetic_data_for_UBA_2014[[12]]$data,
@@ -451,8 +457,8 @@ mkinmod <- function(..., use_of_ff = "max", speclist = NULL, quiet = FALSE, verb
 #' Print mkinmod objects in a way that the user finds his way to get to its
 #' components.
 #'
+#' @rdname mkinmod
 #' @param x An \code{\link{mkinmod}} object.
-#' @param \dots Not used.
 #' @examples
 #'
 #'   m_synth_SFO_lin <- mkinmod(parent = list(type = "SFO", to = "M1"),
diff --git a/R/mkinsub.R b/R/mkinsub.R
index f87c230a..886f712c 100644
--- a/R/mkinsub.R
+++ b/R/mkinsub.R
@@ -3,6 +3,7 @@
 #' This is a convenience function to set up the lists used as arguments for
 #' \code{\link{mkinmod}}.
 #' 
+#' @rdname mkinmod
 #' @param submodel Character vector of length one to specify the submodel type.
 #'   See \code{\link{mkinmod}} for the list of allowed submodel names.
 #' @param to Vector of the names of the state variable to which a
@@ -14,25 +15,6 @@
 #'   your R code will not be portable, \emph{i.e.} may produce unintended plot
 #'   results on other operating systems or system configurations.
 #' @return A list for use with \code{\link{mkinmod}}.
-#' @author Johannes Ranke
-#' @examples
-#' 
-#' # One parent compound, one metabolite, both single first order.
-#' SFO_SFO <- mkinmod(
-#'   parent = list(type = "SFO", to = "m1"),
-#'   m1 = list(type = "SFO"))
-#' 
-#' # The same model using mkinsub
-#' SFO_SFO.2 <- mkinmod(
-#'   parent = mkinsub("SFO", "m1"),
-#'   m1 = mkinsub("SFO"))
-#' 
-#' \dontrun{
-#'   # Now supplying full names
-#'   SFO_SFO.2 <- mkinmod(
-#'     parent = mkinsub("SFO", "m1", full_name = "Test compound"),
-#'     m1 = mkinsub("SFO", full_name = "Metabolite M1"))
-#'  }
 #' @export
 mkinsub <- function(submodel, to = NULL, sink = TRUE, full_name = NA)
 {
diff --git a/R/mmkin.R b/R/mmkin.R
index 96453e1d..bb111efe 100644
--- a/R/mmkin.R
+++ b/R/mmkin.R
@@ -60,6 +60,17 @@
 #' # Plotting with mmkin (single brackets, extracting an mmkin object) does not
 #' # allow to plot the observed variables separately
 #' plot(fits.0[1, 1])
+#'
+#' # On Windows, we can use multiple cores by making a cluster using the parallel
+#' # package, which gets loaded with mkin, and passing it to mmkin, e.g.
+#' cl <- makePSOCKcluster(12)
+#' f <- mmkin(c("SFO", "FOMC", "DFOP"),
+#'   list(A = FOCUS_2006_A, B = FOCUS_2006_B, C = FOCUS_2006_C, D = FOCUS_2006_D),
+#'   cluster = cl, quiet = TRUE)
+#' print(f)
+#' # We get false convergence for the FOMC fit to FOCUS_2006_A because this
+#' # dataset is really SFO, and the FOMC fit is overparameterised
+#' stopCluster(cl)
 #' }
 #'
 #' @export mmkin