From 0a3eb0893cb4bd1b12f07a79069d1c7f5e991495 Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Fri, 25 Oct 2019 00:37:42 +0200 Subject: Use roxygen for functions and methods --- R/add_err.R | 96 +++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 21 deletions(-) (limited to 'R/add_err.R') diff --git a/R/add_err.R b/R/add_err.R index b2a1808e..a523e9c2 100644 --- a/R/add_err.R +++ b/R/add_err.R @@ -1,24 +1,78 @@ -# Copyright (C) 2015-2018 Johannes Ranke -# 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 - -add_err = function(prediction, sdfunc, secondary = c("M1", "M2"), - n = 1000, LOD = 0.1, reps = 2, - digits = 1, seed = NA) +#' Add normally distributed errors to simulated kinetic degradation data +#' +#' Normally distributed errors are added to data predicted for a specific +#' degradation model using \code{\link{mkinpredict}}. The variance of the error +#' may depend on the predicted value and is specified as a standard deviation. +#' +#' @param prediction A prediction from a kinetic model as produced by +#' \code{\link{mkinpredict}}. +#' @param sdfunc A function taking the predicted value as its only argument and +#' returning a standard deviation that should be used for generating the +#' random error terms for this value. +#' @param secondary The names of state variables that should have an initial +#' value of zero +#' @param n The number of datasets to be generated. +#' @param LOD The limit of detection (LOD). Values that are below the LOD after +#' adding the random error will be set to NA. +#' @param reps The number of replicates to be generated within the datasets. +#' @param digits The number of digits to which the values will be rounded. +#' @param seed The seed used for the generation of random numbers. If NA, the +#' seed is not set. +#' @importFrom stats rnorm +#' @return A list of datasets compatible with \code{\link{mmkin}}, i.e. the +#' components of the list are datasets compatible with \code{\link{mkinfit}}. +#' @author Johannes Ranke +#' @references Ranke J and Lehmann R (2015) To t-test or not to t-test, that is +#' the question. XV Symposium on Pesticide Chemistry 2-4 September 2015, +#' Piacenza, Italy +#' http://chem.uft.uni-bremen.de/ranke/posters/piacenza_2015.pdf +#' @examples +#' +#' # The kinetic model +#' m_SFO_SFO <- mkinmod(parent = mkinsub("SFO", "M1"), +#' M1 = mkinsub("SFO"), use_of_ff = "max") +#' +#' # Generate a prediction for a specific set of parameters +#' sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120) +#' +#' # This is the prediction used for the "Type 2 datasets" on the Piacenza poster +#' # from 2015 +#' d_SFO_SFO <- mkinpredict(m_SFO_SFO, +#' c(k_parent = 0.1, f_parent_to_M1 = 0.5, +#' k_M1 = log(2)/1000), +#' c(parent = 100, M1 = 0), +#' sampling_times) +#' +#' # Add an error term with a constant (independent of the value) standard deviation +#' # of 10, and generate three datasets +#' d_SFO_SFO_err <- add_err(d_SFO_SFO, function(x) 10, n = 3, seed = 123456789 ) +#' +#' # Name the datasets for nicer plotting +#' names(d_SFO_SFO_err) <- paste("Dataset", 1:3) +#' +#' # Name the model in the list of models (with only one member in this case) for +#' # nicer plotting later on. Be quiet and use only one core not to offend CRAN +#' # checks +#' \dontrun{ +#' f_SFO_SFO <- mmkin(list("SFO-SFO" = m_SFO_SFO), +#' d_SFO_SFO_err, cores = 1, +#' quiet = TRUE) +#' +#' plot(f_SFO_SFO) +#' +#' # We would like to inspect the fit for dataset 3 more closely +#' # Using double brackets makes the returned object an mkinfit object +#' # instead of a list of mkinfit objects, so plot.mkinfit is used +#' plot(f_SFO_SFO[[3]], show_residuals = TRUE) +#' +#' # If we use single brackets, we should give two indices (model and dataset), +#' # and plot.mmkin is used +#' plot(f_SFO_SFO[1, 3]) +#' } +#' +#' @export +add_err <- function(prediction, sdfunc, secondary = c("M1", "M2"), + n = 1000, LOD = 0.1, reps = 2, digits = 1, seed = NA) { if (!is.na(seed)) set.seed(seed) -- cgit v1.2.1