diff --git a/R/anova.drc.R b/R/anova.drc.R index 57438bb..1962aa0 100644 --- a/R/anova.drc.R +++ b/R/anova.drc.R @@ -1,35 +1,58 @@ -#' @title ANOVA for dose-response model fits +#' @title ANOVA Model Comparison for Dose-Response Models #' #' @description -#' \code{anova} produces an analysis of variance table for one or two -#' non-linear model fits. +#' Compares two nested dose-response model fits using a likelihood-ratio test +#' (for binomial data) or an F-test (for continuous data). Two \code{drc} +#' objects must be provided. For a lack-of-fit test of a single model, use +#' \code{\link{modelFit}} instead. #' -#' @param object an object of class 'drc'. -#' @param ... additional arguments. +#' @param object an object of class \sQuote{drc}. +#' @param ... a second object of class \sQuote{drc} to compare against +#' \code{object}. Exactly two models must be supplied; passing a single +#' model will result in an error directing the user to +#' \code{\link{modelFit}}. #' @param details logical indicating whether or not details on the models -#' compared should be displayed. Default is TRUE (details are displayed). +#' compared should be displayed. Default is \code{TRUE} (details are +#' displayed). #' @param test a character string specifying the test statistic to be applied. -#' Use \code{"od"} to assess overdispersion for binomial data. +#' For continuous data the default is \code{"F"} (F-test); for binomial data +#' the default is \code{"Chisq"} (likelihood-ratio test). Use \code{"Chisq"} +#' to force a likelihood-ratio test for continuous data. #' -#' @return An object of class 'anova'. +#' @return An object of class \sQuote{anova} (inheriting from +#' \code{data.frame}) with columns for model degrees of freedom, residual +#' sum of squares (or log-likelihood), the difference in degrees of freedom, +#' the test statistic, and the p-value. #' #' @details -#' Specifying only a single object gives a test for lack-of-fit, comparing the -#' non-linear regression model to a more general one-way or two-way ANOVA -#' model. +#' Two \code{drc} objects must be specified. The function performs a test for +#' reduction from the larger to the smaller model. This only makes statistical +#' sense if the models are nested, that is: one model is a submodel of the +#' other model. #' -#' If two objects are specified a test for reduction from the larger to the -#' smaller model is given. (This only makes statistical sense if the models are -#' nested, that is: one model is a submodel of the other model.) +#' For continuous data an F-test is used by default. For binomial data a +#' likelihood-ratio (chi-square) test is used by default. +#' +#' If a single model is passed, the function raises an error. To assess the +#' fit of a single dose-response model (lack-of-fit test comparing the model +#' to a more general ANOVA model), use \code{\link{modelFit}} instead. #' #' @examples -#' ## Comparing Weibull three- and four-parameter models using an F test +#' ## Comparing two nested models (two-model comparison) #' ryegrass.m1 <- drm(rootl ~ conc, data = ryegrass, fct = W1.4()) #' ryegrass.m2 <- drm(rootl ~ conc, data = ryegrass, fct = W1.3()) #' anova(ryegrass.m2, ryegrass.m1) #' #' anova(ryegrass.m2, ryegrass.m1, details = FALSE) # without details #' +#' ## For a lack-of-fit test on a single model, use modelFit(): +#' modelFit(ryegrass.m1) +#' +#' @seealso \code{\link{modelFit}} for lack-of-fit testing of a single model, +#' \code{\link{drm}} for fitting dose-response models, +#' \code{\link{logLik.drc}} for log-likelihood extraction, +#' \code{\link{summary.drc}} for model summaries. +#' #' @author Christian Ritz #' #' @keywords models nonlinear diff --git a/docs/reference/anova.drc.md b/docs/reference/anova.drc.md index 7499a4e..4482cf6 100644 --- a/docs/reference/anova.drc.md +++ b/docs/reference/anova.drc.md @@ -1,7 +1,9 @@ -# ANOVA for dose-response model fits +# ANOVA Model Comparison for Dose-Response Models -`anova` produces an analysis of variance table for one or two non-linear -model fits. +Compares two nested dose-response model fits using a likelihood-ratio test +(for binomial data) or an F-test (for continuous data). Two `drc` +objects must be provided. For a lack-of-fit test of a single model, use +`modelFit()` instead. ## Usage @@ -18,31 +20,50 @@ anova(object, ..., details = TRUE, test = NULL) - ...: - additional arguments. + a second object of class 'drc' to compare against + `object`. Exactly two models must be supplied; passing a single + model will result in an error directing the user to + `modelFit()`. - details: logical indicating whether or not details on the models compared - should be displayed. Default is TRUE (details are displayed). + should be displayed. Default is `TRUE` (details are displayed). - test: - a character string specifying the test statistic to be applied. Use - `"od"` to assess overdispersion for binomial data. + a character string specifying the test statistic to be applied. + For continuous data the default is `"F"` (F-test); for binomial data + the default is `"Chisq"` (likelihood-ratio test). Use `"Chisq"` + to force a likelihood-ratio test for continuous data. ## Value -An object of class 'anova'. +An object of class 'anova' (inheriting from `data.frame`) with columns +for model degrees of freedom, residual sum of squares (or +log-likelihood), the difference in degrees of freedom, the test +statistic, and the p-value. ## Details -Specifying only a single object gives a test for lack-of-fit, comparing -the non-linear regression model to a more general one-way or two-way -ANOVA model. +Two `drc` objects must be specified. The function performs a test for +reduction from the larger to the smaller model. This only makes +statistical sense if the models are nested, that is: one model is a +submodel of the other model. -If two objects are specified a test for reduction from the larger to the -smaller model is given. (This only makes statistical sense if the models -are nested, that is: one model is a submodel of the other model.) +For continuous data an F-test is used by default. For binomial data a +likelihood-ratio (chi-square) test is used by default. + +If a single model is passed, the function raises an error. To assess the +fit of a single dose-response model (lack-of-fit test comparing the model +to a more general ANOVA model), use `modelFit()` instead. + +## See Also + +`modelFit()` for lack-of-fit testing of a single model, +`drm()` for fitting dose-response models, +`logLik.drc()` for log-likelihood extraction, +`summary.drc()` for model summaries. ## Author @@ -51,7 +72,7 @@ Christian Ritz ## Examples ``` r -## Comparing Weibull three- and four-parameter models using an F test +## Comparing two nested models (two-model comparison) ryegrass.m1 <- drm(rootl ~ conc, data = ryegrass, fct = W1.4()) ryegrass.m2 <- drm(rootl ~ conc, data = ryegrass, fct = W1.3()) anova(ryegrass.m2, ryegrass.m1) @@ -73,4 +94,7 @@ anova(ryegrass.m2, ryegrass.m1, details = FALSE) # without details #> ModelDf RSS Df F value p value #> 1st model 21 8.9520 #> 2nd model 20 6.0242 1 9.7205 0.0054 + +## For a lack-of-fit test on a single model, use modelFit(): +modelFit(ryegrass.m1) ``` diff --git a/man/anova.drc.Rd b/man/anova.drc.Rd index cbe17d8..ea9f064 100644 --- a/man/anova.drc.Rd +++ b/man/anova.drc.Rd @@ -2,45 +2,69 @@ % Please edit documentation in R/anova.drc.R \name{anova.drc} \alias{anova.drc} -\title{ANOVA for dose-response model fits} +\title{ANOVA Model Comparison for Dose-Response Models} \usage{ \method{anova}{drc}(object, ..., details = TRUE, test = NULL) } \arguments{ -\item{object}{an object of class 'drc'.} +\item{object}{an object of class \sQuote{drc}.} -\item{...}{additional arguments.} +\item{...}{a second object of class \sQuote{drc} to compare against +\code{object}. Exactly two models must be supplied; passing a single +model will result in an error directing the user to +\code{\link{modelFit}}.} \item{details}{logical indicating whether or not details on the models -compared should be displayed. Default is TRUE (details are displayed).} +compared should be displayed. Default is \code{TRUE} (details are +displayed).} \item{test}{a character string specifying the test statistic to be applied. -Use \code{"od"} to assess overdispersion for binomial data.} +For continuous data the default is \code{"F"} (F-test); for binomial data +the default is \code{"Chisq"} (likelihood-ratio test). Use \code{"Chisq"} +to force a likelihood-ratio test for continuous data.} } \value{ -An object of class 'anova'. +An object of class \sQuote{anova} (inheriting from +\code{data.frame}) with columns for model degrees of freedom, residual +sum of squares (or log-likelihood), the difference in degrees of freedom, +the test statistic, and the p-value. } \description{ -\code{anova} produces an analysis of variance table for one or two -non-linear model fits. +Compares two nested dose-response model fits using a likelihood-ratio test +(for binomial data) or an F-test (for continuous data). Two \code{drc} +objects must be provided. For a lack-of-fit test of a single model, use +\code{\link{modelFit}} instead. } \details{ -Specifying only a single object gives a test for lack-of-fit, comparing the -non-linear regression model to a more general one-way or two-way ANOVA -model. +Two \code{drc} objects must be specified. The function performs a test for +reduction from the larger to the smaller model. This only makes statistical +sense if the models are nested, that is: one model is a submodel of the +other model. -If two objects are specified a test for reduction from the larger to the -smaller model is given. (This only makes statistical sense if the models are -nested, that is: one model is a submodel of the other model.) +For continuous data an F-test is used by default. For binomial data a +likelihood-ratio (chi-square) test is used by default. + +If a single model is passed, the function raises an error. To assess the +fit of a single dose-response model (lack-of-fit test comparing the model +to a more general ANOVA model), use \code{\link{modelFit}} instead. } \examples{ -## Comparing Weibull three- and four-parameter models using an F test +## Comparing two nested models (two-model comparison) ryegrass.m1 <- drm(rootl ~ conc, data = ryegrass, fct = W1.4()) ryegrass.m2 <- drm(rootl ~ conc, data = ryegrass, fct = W1.3()) anova(ryegrass.m2, ryegrass.m1) anova(ryegrass.m2, ryegrass.m1, details = FALSE) # without details +## For a lack-of-fit test on a single model, use modelFit(): +modelFit(ryegrass.m1) + +} +\seealso{ +\code{\link{modelFit}} for lack-of-fit testing of a single model, +\code{\link{drm}} for fitting dose-response models, +\code{\link{logLik.drc}} for log-likelihood extraction, +\code{\link{summary.drc}} for model summaries. } \author{ Christian Ritz