1 files changed, 38 insertions, 17 deletions
diff --git a/R/mkinerrmin.R b/R/mkinerrmin.R
index ce4877d2..0b647b81 100644
--- a/R/mkinerrmin.R
+++ b/R/mkinerrmin.R
@@ -1,22 +1,43 @@
-# Copyright (C) 2010-2019 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 <http://www.gnu.org/licenses/>
 if(getRversion() >= '2.15.1') utils::globalVariables(c("name", "value_mean"))
 
+#' Calculate the minimum error to assume in order to pass the variance test
+#' 
+#' This function finds the smallest relative error still resulting in passing
+#' the chi-squared test as defined in the FOCUS kinetics report from 2006.
+#' 
+#' This function is used internally by \code{\link{summary.mkinfit}}.
+#' 
+#' @param fit an object of class \code{\link{mkinfit}}.
+#' @param alpha The confidence level chosen for the chi-squared test.
+#' @importFrom stats qchisq aggregate
+#' @return A dataframe with the following components: \item{err.min}{The
+#' relative error, expressed as a fraction.} \item{n.optim}{The number of
+#' optimised parameters attributed to the data series.} \item{df}{The number of
+#' remaining degrees of freedom for the chi2 error level calculations.  Note
+#' that mean values are used for the chi2 statistic and therefore every time
+#' point with observed values in the series only counts one time.} The
+#' dataframe has one row for the total dataset and one further row for each
+#' observed state variable in the model.
+#' @references FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
+#' and Degradation Kinetics from Environmental Fate Studies on Pesticides in EU
+#' Registration} Report of the FOCUS Work Group on Degradation Kinetics, EC
+#' Document Reference Sanco/10058/2005 version 2.0, 434 pp,
+#' \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
+#' @keywords manip
+#' @examples
+#' 
+#' SFO_SFO = mkinmod(parent = mkinsub("SFO", to = "m1"),
+#'                   m1 = mkinsub("SFO"),
+#'                   use_of_ff = "max")
+#' 
+#' fit_FOCUS_D = mkinfit(SFO_SFO, FOCUS_2006_D, quiet = TRUE)
+#' round(mkinerrmin(fit_FOCUS_D), 4)
+#' \dontrun{
+#'   fit_FOCUS_E = mkinfit(SFO_SFO, FOCUS_2006_E, quiet = TRUE)
+#'   round(mkinerrmin(fit_FOCUS_E), 4)
+#' }
+#' 
+#' @export
 mkinerrmin <- function(fit, alpha = 0.05)
 {
   parms.optim <- fit$par