More detailed documentation of the result dataframe returned

by drfit and drcfit.



git-svn-id: http://kriemhild.uft.uni-bremen.de/svn/drfit@99 d1b72e20-2ee0-0310-a1c4-ad5adbbefcdc

2 files changed, 148 insertions, 58 deletions

diff --git a/man/drcfit.Rd b/man/drcfit.Rd
index 2da0418..b10418a 100644
--- a/man/drcfit.Rd
+++ b/man/drcfit.Rd
@@ -25,11 +25,10 @@
     the fitting procedure, although it will be plotted.}
   \item{probit}{
     A boolean defining if cumulative density curves of normal distributions
-    \code{\link{pnorm}} are fitted against the decadic logarithm of the dose.
-    Default ist TRUE.
+    are fitted against the decadic logarithm of the dose.  Default ist TRUE.
     Note that the parameter definitions used in the model are different to the
     ones used in \code{\link{drfit}}. Parameter e from \code{\link{LN.2}} is listed
-    as a here, and parameter b from LN.2 is listed as b.}
+    as a here, and parameter b from there is listed as b.}
   \item{logit}{
     A boolean defining if cumulative density curves of logistic distributions
     \code{\link{plogis}} are fitted to the decadic logarithm of the dose.
@@ -66,27 +65,74 @@
   }
 }
 \value{
-  \item{results}{
-    A data frame containing at least one line for each substance. If the data
-    did not show a mean response < 0.5 at the highest dose level, the
-    modeltype is set to \dQuote{inactive}. If the mean response at the lowest
-    dose is smaller than 0.5, the modeltype is set to \dQuote{active}. In
-    both cases, no fitting procedure is carried out.  Every successful fit is
-    reported in one line. Parameters of the fitted curves are only reported
-    if the fitted ED50 is not higher than the highest dose. 
+  A dataframe with the attribute \code{models} holding a list of the fitted
+  dose-response models of class \code{\link{nls}}. The dataframe has at least
+  one line for each substance. 
 
-    \code{ndl} is the number of dose levels in the raw data, \code{n} is the
-    total number of data points in the raw data used for the fit
-    \code{lld} is the decadic logarithm of the lowest dose and
-    \code{lhd} is the decadic logarithm of the highest dose.
- 
-    If the parameter \code{showED50} was set to TRUE, the ED50 values and their
-    confidence intervals are also included on the original dose scale.
-
-    If one or more response leves were specified in the argument \code{EDx},
-    the corresponding dose levels are given, together with their confidence
-    intervals.
+  The following variables are in the dataframe:
+  \item{Substance}{
+    The name of the substance
+  }
+  \item{ndl}{
+    The number of dose levels in the raw data
+  }
+  \item{n}{
+    The total number of data points in the raw data used for the fit
+  }
+  \item{lld}{
+    The decadic logarithm of the lowest dose
+  }
+  \item{lhd}{
+    The total number of data points in the raw data used for the fit
+  }
+  \item{mtype}{
+    If the data did not show a mean response < 0.5 at the highest dose level,
+    the modeltype is set to \dQuote{inactive}. If the mean response at the
+    lowest dose is smaller than 0.5, the modeltype is set to \dQuote{active}.
+    In both cases, no fitting procedure is carried out. If the fitted ED50 
+    is higher than the highest dose, \dQuote{no fit} is given here.
+  }
+  \item{logED50}{
+    The decadic logarithm of the ED50
+  }
+  \item{low \%}{
+    The lower bound of the confidence interval of log ED50. 
+    The name of the column depends on the requested confidence \code{level}.
   }
+  \item{high \%}{
+    The higher bound of the confidence interval of log ED50.
+    The name of the column depends on the requested confidence \code{level}.
+  }
+  \item{unit}{
+    The unit used for the dose levels in the dose-response data
+  }
+  \item{sigma}{
+    The square root of the estimated variance of the random error as returned
+    by \code{\link{summary.drc}}.
+  }
+  \item{a}{
+    For the linlogit model, this is the parameter e from \code{\link{BC.4}}.
+    For the probit and the logit model, this is the ED50. For the weibull 
+    model, this is parameter e from \code{\link{W1.2}}. Note that the Weibull 
+    model is fitted to the untransformed data.
+  }
+  \item{b}{
+    For the linlogit, probit, logit and weibull models, these are the
+    parameters b from \code{\link{BC.4}}, \code{\link{LN.2}}, 
+    \code{\link{LL.2}} and \code{\link{W1.2}}, respectively.
+    Note that the parameter definitions (and in the case of Weibull, the model
+    used) are different to the ones used in \code{\link{drfit}}. 
+  }
+  \item{c}{
+    Only the \dQuote{linlogit} fit produces a third parameter \code{c}, which is
+    the parameter f from the \code{\link{BC.4}} function.
+  }
+  If the parameter \code{showED50} was set to TRUE, the ED50 values and their
+  confidence intervals are also included on the original dose scale.
+
+  If one or more response leves were specified in the argument \code{EDx},
+  the corresponding dose levels are given in addition, together with their
+  confidence intervals as calculated by \code{\link{ED}} from the drc package.
 }
 \examples{
 data(antifoul)
@@ -101,9 +147,10 @@ format(r, digits = 2)
   \code{\link{IM1xVibrio}}.
 }
 \author{
-  Johannes Ranke 
-  \email{jranke@uni-bremen.de} 
+  Johannes Ranke \email{jranke@uni-bremen.de} 
   \url{http://www.uft.uni-bremen.de/chemie/ranke}
+  The functionality of the drc package used under the hood in this function
+  was written by Christian Ritz.
 }
 \keyword{models}
 \keyword{regression}
diff --git a/man/drfit.Rd b/man/drfit.Rd
index fe84a91..3729550 100644
--- a/man/drfit.Rd
+++ b/man/drfit.Rd
@@ -40,7 +40,9 @@
   \item{weibull}{
     A boolean defining if the cumulative density curves of weibull distributions
     (\code{\link{pweibull}} with additionall location parameter and scale=1)
-    are fitted to the decadic logarithm of the dose. Default is FALSE.}
+    are fitted to the decadic logarithm of the dose. Default is FALSE.
+    Note that the weibull distribution is fitted here to the log transformed doses
+    which appears to be an uncommon approach.}
   \item{linlogit}{
     A boolean defining if the linear-logistic function
     \code{\link{linlogitf}} as defined by van Ewijk and Hoekstra 1993 is
@@ -83,41 +85,79 @@
   }
 }
 \value{
-  \item{results}{
-    A data frame containing at least one line for each substance. If the data
-    did not show a mean response < 0.5 at the highest dose level, the
-    modeltype is set to \dQuote{inactive}. If the mean response at the lowest
-    dose is smaller than 0.5, the modeltype is set to \dQuote{active}. In
-    both cases, no fitting procedure is carried out.  Every successful fit is
-    reported in one line. Parameters of the fitted curves are only reported
-    if the fitted ED50 is not higher than the highest dose. 
+  A dataframe with the attribute \code{models} holding a list of the fitted
+  dose-response models of class \code{\link{nls}}. The dataframe has at least
+  one line for each substance. 
 
-    \code{ndl} is the number of dose levels in the raw data, \code{n} is the
-    total number of data points in the raw data used for the fit
-    \code{lld} is the decadic logarithm of the lowest dose and
-    \code{lhd} is the decadic logarithm of the highest dose.  For the
-    \dQuote{linlogit}, \dQuote{logit} and \dQuote{probit} models, the
-    parameter \code{a} that is reported coincides with the logED50, i.e the
-    logED50 is one of the model parameters that is being fitted. Therefore,
-    a confidence interval for the confidence level \code{level} is calculated
-    using the \code{\link[MASS:confint]{confint.nls}} function and listed.
-    In the case of the \dQuote{weibull} model, \code{a} is a
-    location parameter.  Parameter \code{b} in the case of the
-    \dQuote{linlogit} fit is the variable b from the \code{\link{linlogitf}}
-    function. In the case of \dQuote{probit} fit it is the standard deviation
-    of the fitted normal distribution, in the case of the \dQuote{logit} fit
-    it is the \code{scale} parameter in the \code{\link{plogis}} function,
-    and in the \dQuote{weibull} fit it is the \code{shape} parameter of the
-    fitted \code{\link{pweibull}} function. Only the \dQuote{linlogit} fit
-    produces a third parameter \code{c} which is the variable f from the
-    \code{\link{linlogitf}} function.
- 
-    If the parameter \code{showED50} was set to TRUE, the ED50 values and their
-    confidence intervals are also included on the original dose scale.
-
-    If one or more response leves were specified in the argument \code{EDx},
-    the corresponding dose levels are given in addition.
+  For the \dQuote{linlogit}, \dQuote{logit} and \dQuote{probit} models, the
+  parameter \code{a} that is reported coincides with the logED50, i.e the
+  logED50 is one of the model parameters that is being fitted. Therefore,
+  a confidence interval for the confidence level \code{level} is calculated
+  using the \code{\link[MASS:confint]{confint.nls}} function and listed.
+  
+  The following variables are in the dataframe:
+  \item{Substance}{
+    The name of the substance
+  }
+  \item{ndl}{
+    The number of dose levels in the raw data
+  }
+  \item{n}{
+    The total number of data points in the raw data used for the fit
+  }
+  \item{lld}{
+    The decadic logarithm of the lowest dose
+  }
+  \item{lhd}{
+    The total number of data points in the raw data used for the fit
+  }
+  \item{mtype}{
+    If the data did not show a mean response < 0.5 at the highest dose level,
+    the modeltype is set to \dQuote{inactive}. If the mean response at the
+    lowest dose is smaller than 0.5, the modeltype is set to \dQuote{active}.
+    In both cases, no fitting procedure is carried out. If the fitted ED50 
+    is higher than the highest dose, \dQuote{no fit} is given here.
+  }
+  \item{logED50}{
+    The decadic logarithm of the ED50
+  }
+  \item{low \%}{
+    The lower bound of the confidence interval of log ED50. 
+    The name of the column depends on the requested confidence \code{level}.
   }
+  \item{high \%}{
+    The higher bound of the confidence interval of log ED50.
+    The name of the column depends on the requested confidence \code{level}.
+  }
+  \item{unit}{
+    The unit used for the dose levels in the dose-response data
+  }
+  \item{sigma}{
+    The square root of the estimated variance of the random error as returned
+    by \code{\link{summary.nls}}.
+  }
+  \item{a}{
+    For the \dQuote{linlogit}, \dQuote{logit} and \dQuote{probit} models, the
+    parameter \code{a} coincides with the logED50.  In the case of the
+    \dQuote{weibull} model, \code{a} is a location parameter. 
+  }
+  \item{b}{
+    Parameter \code{b} in the case of the \dQuote{linlogit} fit is the variable
+    b from the \code{\link{linlogitf}} function. In the case of \dQuote{probit}
+    fit it is the standard deviation of the fitted normal distribution, in the
+    case of the \dQuote{logit} fit it is the \code{scale} parameter in the
+    \code{\link{plogis}} function, and in the \dQuote{weibull} fit it is the
+    \code{shape} parameter of the fitted \code{\link{pweibull}} function.
+  }
+  \item{c}{
+    Only the \dQuote{linlogit} fit produces a third parameter \code{c} which is
+    the variable f from the \code{\link{linlogitf}} function.
+  }
+  If the parameter \code{showED50} was set to TRUE, the ED50 values and their
+  confidence intervals are also included on the original dose scale.
+
+  If one or more response leves were specified in the argument \code{EDx},
+  the corresponding dose levels are given in addition.
 }
 \examples{
 data(antifoul)
@@ -130,6 +170,9 @@ format(r, digits = 2)
   Further examples are given in help pages to the datasets
   \code{\link{antifoul}}, \code{\link{IM1xIPC81}} and
   \code{\link{IM1xVibrio}}.
+  Since version 0.6.1 of this package, there is a drop-in replacement function
+  \code{\link{drcfit}} which internally uses the drc package and also gives
+  confidence intervals for EDx values via this package.
 }
 \author{
   Johannes Ranke