% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dunnett_test.R
\name{dunnett_test}
\alias{dunnett_test}
\title{Dunnett's Many-to-One Comparisons Test}
\usage{
dunnett_test(
  data,
  formula,
  ref.group = NULL,
  conf.level = 0.95,
  detailed = FALSE
)
}
\arguments{
\item{data}{a data.frame containing the variables in the formula.}

\item{formula}{a formula of the form \code{x ~ group} where \code{x} is a
numeric variable giving the data values and \code{group} is a factor with
one or multiple levels giving the corresponding groups. For example,
\code{formula = TP53 ~ cancer_group}.}

\item{ref.group}{a character string specifying the reference (control) group.
Each remaining group level is compared against this group. If \code{NULL}
(default), the first level of the grouping variable is used as the control.}

\item{conf.level}{confidence level of the (simultaneous) confidence intervals.}

\item{detailed}{logical value. Default is FALSE. If TRUE, a detailed result is
shown.}
}
\value{
a data frame with some of the following columns: \itemize{ \item
 \code{.y.}: the outcome variable used in the test. \item
 \code{group1,group2}: the compared groups; \code{group1} is the control
 (reference) and \code{group2} is the treatment, consistent with the
 \code{ref.group} convention of \code{t_test()}/\code{wilcox_test()}/
 \code{dunn_test()}/\code{emmeans_test()}. \item \code{n1,n2}: sample sizes of
 the control and treatment groups. \item \code{estimate}: the estimated mean
 difference \code{group1 - group2} (control minus treatment). \item
 \code{conf.low,conf.high}: simultaneous confidence interval for the
 difference. \item \code{statistic}: the t-statistic. \item \code{df}:
 degrees of freedom. \item \code{p.adj}: the Dunnett-adjusted p-value. \item
 \code{method}: the statistical test used. \item \code{p.adj.signif}: the
 significance level of the adjusted p-value. } The estimate, confidence
 interval, se and method columns are returned only when \code{detailed =
 TRUE}.

 The \strong{returned object has an attribute called args}, which is a list
 holding the test arguments.
}
\description{
Performs Dunnett's test for comparing each of several treatment
 groups against a single control (reference) group. Unlike all-pairwise
 post-hoc tests, Dunnett's procedure controls the family-wise error rate over
 only the \code{k - 1} treatment-vs-control comparisons, using the exact
 multivariate-t distribution (which accounts for the correlation between the
 comparisons that share the control group).

 This is a pipe-friendly wrapper around \code{emmeans::emmeans()} +
 \code{emmeans::contrast()} (with \code{adjust = "mvt"}), so the
 \code{emmeans} package must be installed. The results match
 \code{DescTools::DunnettTest()} and \code{multcomp::glht(..., mcp(... =
 "Dunnett"))}.
}
\examples{
# Compare each dose to the control dose ("0.5")
ToothGrowth \%>\% dunnett_test(len ~ dose)

# Detailed output (estimate + simultaneous confidence interval)
ToothGrowth \%>\% dunnett_test(len ~ dose, detailed = TRUE)

# Grouped data
ToothGrowth \%>\%
  group_by(supp) \%>\%
  dunnett_test(len ~ dose)
}
\references{
Dunnett, C. W. (1955) A multiple comparison procedure for comparing
 several treatments with a control. Journal of the American Statistical
 Association, 50, 1096-1121.
}
\seealso{
\code{\link{tukey_hsd}()}, \code{\link{games_howell_test}()},
 \code{\link{emmeans_test}()}
}
