% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conover_test.R
\name{conover_test}
\alias{conover_test}
\title{Conover's All-Pairs Rank Comparison Test}
\usage{
conover_test(
  data,
  formula,
  p.adjust.method = "holm",
  ref.group = NULL,
  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{p.adjust.method}{method to adjust p values for multiple comparisons.
Used when pairwise comparisons are performed. Allowed values include "holm",
"hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". If you don't
want to adjust the p value (not recommended), use p.adjust.method = "none".}

\item{ref.group}{a character string specifying the reference group. If
specified, for a given grouping variable, each of the group levels will be
compared to the reference (control) group, and the p-value adjustment is
computed over only these comparisons. Note that, like \code{dunn_test()},
\code{conover_test()} does not support \code{ref.group = "all"}.}

\item{detailed}{logical value. Default is FALSE. If TRUE, a detailed result is
shown.}
}
\value{
return a data frame with some of the following columns: \itemize{
 \item \code{.y.}: the y (outcome) variable used in the test. \item
 \code{group1,group2}: the compared groups in the pairwise tests. \item
 \code{n1,n2}: Sample counts. \item \code{estimate}: mean ranks difference.
 \item \code{estimate1, estimate2}: show the mean rank values of the two
 groups, respectively. \item \code{statistic}: Test statistic (t-value) used
 to compute the p-value. \item \code{df}: degrees of freedom (\eqn{N - k},
 the same for every comparison). \item \code{p}: p-value. \item \code{p.adj}:
 the adjusted p-value. \item \code{method}: the statistical test used to
 compare groups. \item \code{p.adj.signif}: the significance level of the
 adjusted p-values. }

 The \strong{returned object has an attribute called args}, which is a list
 holding the test arguments.
}
\description{
Performs Conover's test (also known as the Conover-Iman test) for
 pairwise multiple comparisons of the ranked data, following a significant
 Kruskal-Wallis test. It is closely related to \code{\link{dunn_test}()}, but
 uses the pooled within-group rank variance and refers the test statistic to a
 \emph{t}-distribution (with \eqn{N - k} degrees of freedom) instead of the
 standard normal distribution. The Conover-Iman test is generally more
 powerful than Dunn's test, but should only be used as a post-hoc procedure
 when the Kruskal-Wallis test is itself significant (Conover, 1999).

 If a reference group is specified (via \code{ref.group}), then each of the
 remaining group levels is compared only to the reference (control) group, and
 the p-value adjustment for multiple comparisons is computed over only these
 \code{k - 1} comparisons (instead of all \code{k(k - 1)/2} pairwise
 comparisons), exactly as for \code{\link{dunn_test}()}.
}
\details{
The Conover-Iman pairwise statistic for comparing groups \eqn{i} and
 \eqn{j} is \deqn{t_{ij} = \frac{\bar{R}_i - \bar{R}_j}{\sqrt{S^2 \,
 \frac{N - 1 - H}{N - k} \left(\frac{1}{n_i} + \frac{1}{n_j}\right)}}} where
 \eqn{\bar{R}} are the mean ranks, \eqn{H} is the (tie-corrected)
 Kruskal-Wallis statistic, \eqn{N} is the total sample size, \eqn{k} is the
 number of groups, and \eqn{S^2} is the variance of the ranks
 (\eqn{S^2 = N(N+1)/12} when there are no ties; otherwise
 \eqn{S^2 = \frac{1}{N - 1}\left(\sum r^2 - \frac{N(N+1)^2}{4}\right)}). The
 statistic is referred to a \emph{t}-distribution with \eqn{N - k} degrees of
 freedom.
}
\examples{
# Simple test
ToothGrowth \%>\% conover_test(len ~ dose)

# Comparison against a reference (control) group
# each group is compared to the reference; the p-value
# adjustment corrects for only these k - 1 comparisons
ToothGrowth \%>\% conover_test(len ~ dose, ref.group = "0.5")

# Grouped data
ToothGrowth \%>\%
  group_by(supp) \%>\%
  conover_test(len ~ dose)
}
\references{
Conover, W. J. (1999) Practical Nonparametric Statistics, 3rd
 edition. Wiley.

 Conover, W. J. and Iman, R. L. (1979) On multiple-comparisons procedures.
 Technical Report LA-7677-MS, Los Alamos Scientific Laboratory.
}
\seealso{
\code{\link{dunn_test}}, \code{\link{kruskal_test}}
}
