% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/friedman_conover_test.R
\name{friedman_conover_test}
\alias{friedman_conover_test}
\title{Conover's All-Pairs Comparisons Test for Friedman Rank Sums}
\usage{
friedman_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{a ~ b | c}, where \code{a}
(numeric) is the dependent variable name; \code{b} is the within-subjects
factor variable (the treatment); and \code{c} is the column name containing
the individuals/subjects (block) identifier. Should be unique per individual.}

\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". Default is
"holm".}

\item{ref.group}{a character string specifying the reference treatment. If
specified, each of the treatment levels is compared to the reference
(control), and the p-value adjustment is computed over only these
comparisons.}

\item{detailed}{logical value. If TRUE, returns the rank-sum estimate and the
test method in the output.}
}
\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 treatments in the pairwise tests. \item
 \code{n1,n2}: the number of blocks (subjects) contributing to each treatment.
 \item \code{estimate}: the rank-sum difference. \item \code{estimate1,
 estimate2}: the rank sums of the two treatments, respectively. \item
 \code{statistic}: Test statistic (t-value) used to compute the p-value. \item
 \code{df}: degrees of freedom (\eqn{(b - 1)(k - 1)}). \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 all-pairs comparison test (also known as the
 Durbin-Conover test) for a two-way balanced complete block design, following
 a significant Friedman rank sum test. It is the repeated-measures analogue of
 Conover's test for the Kruskal-Wallis design: the
 within-block ranks are compared pairwise using the pooled rank variance and
 the statistic is referred to a \emph{t}-distribution with \eqn{(b - 1)(k - 1)}
 degrees of freedom (\eqn{b} blocks, \eqn{k} treatments). It should only be
 used as a post-hoc procedure when the Friedman test is itself significant
 (Conover, 1999).

 If a reference group is specified (via \code{ref.group}), then each of the
 remaining treatments is compared only to the reference (control) treatment,
 and the p-value adjustment for multiple comparisons is computed over only
 these \code{k - 1} comparisons (as for \code{\link{dunn_test}()}).
}
\details{
For a balanced complete block design with \eqn{b} blocks and \eqn{k}
 treatments, the observations within each block are ranked. Let \eqn{R_j} be
 the sum of the within-block ranks for treatment \eqn{j} and let \eqn{A =
 \sum r^2} be the sum of the squared within-block ranks. The pairwise
 statistic for treatments \eqn{i} and \eqn{j} is \deqn{t_{ij} =
 \frac{R_i - R_j}{\sqrt{\dfrac{2\,(b\,A - \sum_j R_j^2)}{(b - 1)(k - 1)}}}}
 referred to a \emph{t}-distribution with \eqn{(b - 1)(k - 1)} degrees of
 freedom. This is the Conover (1999) post-hoc, also known as the
 Durbin-Conover test.
}
\examples{
# A balanced complete block design: 3 treatments measured on 6 subjects
df <- data.frame(
  id        = factor(rep(1:6, 3)),
  treatment = factor(rep(c("A", "B", "C"), each = 6)),
  score     = c(4, 6, 3, 5, 4, 5,    7, 8, 6, 7, 9, 6,    6, 9, 7, 8, 8, 9)
)

# Omnibus Friedman test
df \%>\% friedman_test(score ~ treatment | id)

# Conover (Durbin-Conover) all-pairs post-hoc
df \%>\% friedman_conover_test(score ~ treatment | id)

# Comparison against a reference (control) treatment
df \%>\% friedman_conover_test(score ~ treatment | id, ref.group = "A")
}
\references{
Conover, W. J. (1999) Practical Nonparametric Statistics, 3rd
 edition. Wiley.
}
\seealso{
\code{\link{friedman_test}}, \code{\link{friedman_nemenyi_test}},
  \code{\link{friedman_effsize}}
}
