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.

4 files changed, 61 insertions, 85 deletions

diff --git a/man/mkinmod.Rd b/man/mkinmod.Rd
index 98623201..e5b1c8f3 100644
--- a/man/mkinmod.Rd
+++ b/man/mkinmod.Rd
@@ -1,7 +1,9 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/mkinmod.R
+% Please edit documentation in R/mkinmod.R, R/mkinsub.R
 \name{mkinmod}
 \alias{mkinmod}
+\alias{print.mkinmod}
+\alias{mkinsub}
 \title{Function to set up a kinetic model with one or more state variables}
 \usage{
 mkinmod(
@@ -11,6 +13,10 @@ mkinmod(
   quiet = FALSE,
   verbose = FALSE
 )
+
+\method{print}{mkinmod}(x, ...)
+
+mkinsub(submodel, to = NULL, sink = TRUE, full_name = NA)
 }
 \arguments{
 \item{...}{For each observed variable, a list as obtained by \code{\link[=mkinsub]{mkinsub()}}
@@ -25,13 +31,14 @@ variables to which a transfer is to be assumed in the model.
 If the argument \code{use_of_ff} is set to "min"
 (default) and the model for the compartment is "SFO" or "SFORB", an
 additional \code{\link[=mkinsub]{mkinsub()}} argument can be \code{sink = FALSE}, effectively
-fixing the flux to sink to zero.}
+fixing the flux to sink to zero.
+In print.mkinmod, this argument is currently not used.}
 
 \item{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.}
 
 \item{speclist}{The specification of the observed variables and their
 submodel types and pathways can be given as a single list using this
@@ -41,6 +48,22 @@ argument. Default is NULL.}
 
 \item{verbose}{If \code{TRUE}, passed to \code{\link[inline:cfunction]{inline::cfunction()}} if
 applicable to give detailed information about the C function being built.}
+
+\item{x}{An \code{\link{mkinmod}} object.}
+
+\item{submodel}{Character vector of length one to specify the submodel type.
+See \code{\link{mkinmod}} for the list of allowed submodel names.}
+
+\item{to}{Vector of the names of the state variable to which a
+transformation shall be included in the model.}
+
+\item{sink}{Should a pathway to sink be included in the model in addition to
+the pathways to other state variables?}
+
+\item{full_name}{An optional name to be used e.g. for plotting fits
+performed with the model.  You can use non-ASCII characters here, but then
+your R code will not be portable, \emph{i.e.} may produce unintended plot
+results on other operating systems or system configurations.}
 }
 \value{
 A list of class \code{mkinmod} for use with \code{\link[=mkinfit]{mkinfit()}},
@@ -68,11 +91,19 @@ represented by one.
 If generated, a compiled function calculating the derivatives as
 returned by cfunction.
 }
+
+A list for use with \code{\link{mkinmod}}.
 }
 \description{
 This function is usually called using a call to \code{\link[=mkinsub]{mkinsub()}} for each observed
 variable, specifying the corresponding submodel as well as outgoing pathways
 (see examples).
+
+Print mkinmod objects in a way that the user finds his way to get to its
+components.
+
+This is a convenience function to set up the lists used as arguments for
+\code{\link{mkinmod}}.
 }
 \details{
 For the definition of model types and their parameters, the equations given
@@ -103,6 +134,11 @@ SFO_SFO <- mkinmod(
   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"),
@@ -123,13 +159,20 @@ m_synth_DFOP_par <- mkinmod(
  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,
   quiet = TRUE)
 }
 
+
+  m_synth_SFO_lin <- mkinmod(parent = list(type = "SFO", to = "M1"),
+                             M1 = list(type = "SFO", to = "M2"),
+                             M2 = list(type = "SFO"), use_of_ff = "max")
+
+  print(m_synth_SFO_lin)
+
 }
 \references{
 FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
diff --git a/man/mkinsub.Rd b/man/mkinsub.Rd
deleted file mode 100644
index 81615a00..00000000
--- a/man/mkinsub.Rd
+++ /dev/null
@@ -1,52 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/mkinsub.R
-\name{mkinsub}
-\alias{mkinsub}
-\title{Function to set up a kinetic submodel for one state variable}
-\usage{
-mkinsub(submodel, to = NULL, sink = TRUE, full_name = NA)
-}
-\arguments{
-\item{submodel}{Character vector of length one to specify the submodel type.
-See \code{\link{mkinmod}} for the list of allowed submodel names.}
-
-\item{to}{Vector of the names of the state variable to which a
-transformation shall be included in the model.}
-
-\item{sink}{Should a pathway to sink be included in the model in addition to
-the pathways to other state variables?}
-
-\item{full_name}{An optional name to be used e.g. for plotting fits
-performed with the model.  You can use non-ASCII characters here, but then
-your R code will not be portable, \emph{i.e.} may produce unintended plot
-results on other operating systems or system configurations.}
-}
-\value{
-A list for use with \code{\link{mkinmod}}.
-}
-\description{
-This is a convenience function to set up the lists used as arguments for
-\code{\link{mkinmod}}.
-}
-\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"))
- }
-}
-\author{
-Johannes Ranke
-}
diff --git a/man/mmkin.Rd b/man/mmkin.Rd
index 80360cd7..9b836242 100644
--- a/man/mmkin.Rd
+++ b/man/mmkin.Rd
@@ -76,6 +76,17 @@ plot_sep(fits.0[[1, 1]])
 # 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)
 }
 
 }
diff --git a/man/print.mkinmod.Rd b/man/print.mkinmod.Rd
deleted file mode 100644
index 4e44cde6..00000000
--- a/man/print.mkinmod.Rd
+++ /dev/null
@@ -1,26 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/mkinmod.R
-\name{print.mkinmod}
-\alias{print.mkinmod}
-\title{Print mkinmod objects}
-\usage{
-\method{print}{mkinmod}(x, ...)
-}
-\arguments{
-\item{x}{An \code{\link{mkinmod}} object.}
-
-\item{\dots}{Not used.}
-}
-\description{
-Print mkinmod objects in a way that the user finds his way to get to its
-components.
-}
-\examples{
-
-  m_synth_SFO_lin <- mkinmod(parent = list(type = "SFO", to = "M1"),
-                             M1 = list(type = "SFO", to = "M2"),
-                             M2 = list(type = "SFO"), use_of_ff = "max")
-
-  print(m_synth_SFO_lin)
-
-}