From 189aad5e39df513075fc7c7a64e646b1a354bc4c Mon Sep 17 00:00:00 2001 From: ranke Date: Tue, 25 Feb 2014 21:26:05 +0000 Subject: 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 --- man/drcfit.Rd | 95 ++++++++++++++++++++++++++++++++++++------------- man/drfit.Rd | 111 ++++++++++++++++++++++++++++++++++++++++------------------ 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 -- cgit v1.2.1