Use roxygen for functions and methods

1 files changed, 100 insertions, 19 deletions

diff --git a/R/mkinpredict.R b/R/mkinpredict.R
index c36d724a..8949e800 100644
--- a/R/mkinpredict.R
+++ b/R/mkinpredict.R
@@ -1,22 +1,99 @@
-# Copyright (C) 2010-2016,2018,2019 Johannes Ranke
-# Some lines in this code are copyright (C) 2013 Eurofins Regulatory AG
-# Contact: jranke@uni-bremen.de
-
-# This file is part of the R package mkin
-
-# mkin is free software: you can redistribute it and/or modify it under the
-# terms of the GNU General Public License as published by the Free Software
-# Foundation, either version 3 of the License, or (at your option) any later
-# version.
-
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
-# details.
-
-# You should have received a copy of the GNU General Public License along with
-# this program. If not, see <http://www.gnu.org/licenses/>
-
+#' Produce predictions from a kinetic model using specific parameters
+#' 
+#' This function produces a time series for all the observed variables in a
+#' kinetic model as specified by \code{\link{mkinmod}}, using a specific set of
+#' kinetic parameters and initial values for the state variables.
+#' 
+#' @aliases mkinpredict mkinpredict.mkinmod mkinpredict.mkinfit
+#' @param x A kinetic model as produced by \code{\link{mkinmod}}, or a kinetic
+#'   fit as fitted by \code{\link{mkinfit}}. In the latter case, the fitted
+#'   parameters are used for the prediction.
+#' @param odeparms A numeric vector specifying the parameters used in the
+#'   kinetic model, which is generally defined as a set of ordinary
+#'   differential equations.
+#' @param odeini A numeric vectory containing the initial values of the state
+#'   variables of the model. Note that the state variables can differ from the
+#'   observed variables, for example in the case of the SFORB model.
+#' @param outtimes A numeric vector specifying the time points for which model
+#'   predictions should be generated.
+#' @param solution_type The method that should be used for producing the
+#'   predictions. This should generally be "analytical" if there is only one
+#'   observed variable, and usually "deSolve" in the case of several observed
+#'   variables. The third possibility "eigen" is faster but not applicable to
+#'   some models e.g.  using FOMC for the parent compound.
+#' @param method.ode The solution method passed via \code{\link{mkinpredict}}
+#'   to \code{\link{ode}} in case the solution type is "deSolve". The default
+#'   "lsoda" is performant, but sometimes fails to converge.
+#' @param use_compiled If set to \code{FALSE}, no compiled version of the
+#'   \code{\link{mkinmod}} model is used, even if is present.
+#' @param atol Absolute error tolerance, passed to \code{\link{ode}}. Default
+#'   is 1e-8, lower than in \code{\link{lsoda}}.
+#' @param rtol Absolute error tolerance, passed to \code{\link{ode}}. Default
+#'   is 1e-10, much lower than in \code{\link{lsoda}}.
+#' @param map_output Boolean to specify if the output should list values for
+#'   the observed variables (default) or for all state variables (if set to
+#'   FALSE).
+#' @param \dots Further arguments passed to the ode solver in case such a
+#'   solver is used.
+#' @import deSolve
+#' @importFrom inline getDynLib
+#' @return A matrix in the same format as the output of \code{\link{ode}}.
+#' @author Johannes Ranke
+#' @examples
+#' 
+#'   SFO <- mkinmod(degradinol = mkinsub("SFO"))
+#'   # Compare solution types
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         solution_type = "analytical")
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         solution_type = "deSolve")
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         solution_type = "deSolve", use_compiled = FALSE)
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         solution_type = "eigen")
+#' 
+#' 
+#'   # Compare integration methods to analytical solution
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         solution_type = "analytical")[21,]
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         method = "lsoda")[21,]
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         method = "ode45")[21,]
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100), 0:20,
+#'         method = "rk4")[21,]
+#'  # rk4 is not as precise here
+#' 
+#'   # The number of output times used to make a lot of difference until the
+#'   # default for atol was adjusted
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100),
+#'         seq(0, 20, by = 0.1))[201,]
+#'   mkinpredict(SFO, c(k_degradinol_sink = 0.3), c(degradinol = 100),
+#'         seq(0, 20, by = 0.01))[2001,]
+#' 
+#'   # Check compiled model versions - they are faster than the eigenvalue based solutions!
+#'   SFO_SFO = mkinmod(parent = list(type = "SFO", to = "m1"),
+#'                     m1 = list(type = "SFO"))
+#'   system.time(
+#'     print(mkinpredict(SFO_SFO, c(k_parent_m1 = 0.05, k_parent_sink = 0.1, k_m1_sink = 0.01),
+#'                 c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+#'                 solution_type = "eigen")[201,]))
+#'   system.time(
+#'     print(mkinpredict(SFO_SFO, c(k_parent_m1 = 0.05, k_parent_sink = 0.1, k_m1_sink = 0.01),
+#'                 c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+#'                 solution_type = "deSolve")[201,]))
+#'   system.time(
+#'     print(mkinpredict(SFO_SFO, c(k_parent_m1 = 0.05, k_parent_sink = 0.1, k_m1_sink = 0.01),
+#'                 c(parent = 100, m1 = 0), seq(0, 20, by = 0.1),
+#'                 solution_type = "deSolve", use_compiled = FALSE)[201,]))
+#' 
+#'   \dontrun{
+#'     # Predict from a fitted model
+#'     f <- mkinfit(SFO_SFO, FOCUS_2006_C)
+#'     head(mkinpredict(f))
+#'   }
+#' 
+#' @export
 mkinpredict <- function(x, odeparms, odeini,
   outtimes = seq(0, 120, by = 0.1),
   solution_type = "deSolve",
@@ -27,6 +104,8 @@ mkinpredict <- function(x, odeparms, odeini,
   UseMethod("mkinpredict", x)
 }
 
+#' @rdname mkinpredict
+#' @export
 mkinpredict.mkinmod <- function(x,
   odeparms = c(k_parent_sink = 0.1),
   odeini = c(parent = 100),
@@ -164,6 +243,8 @@ mkinpredict.mkinmod <- function(x,
   }
 }
 
+#' @rdname mkinpredict
+#' @export
 mkinpredict.mkinfit <- function(x,
   odeparms = x$bparms.ode,
   odeini = x$bparms.state,