\HeaderA{kruskal.test}{Kruskal-Wallis Rank Sum Test}{kruskal.test}
\methaliasA{kruskal.test.default}{kruskal.test}{kruskal.test.default}
\methaliasA{kruskal.test.formula}{kruskal.test}{kruskal.test.formula}
\keyword{htest}{kruskal.test}
\begin{Description}\relax
Performs a Kruskal-Wallis rank sum test.
\end{Description}
\begin{Usage}
\begin{verbatim}
kruskal.test(x, ...)

## Default S3 method:
kruskal.test(x, g, ...)

## S3 method for class 'formula':
kruskal.test(formula, data, subset, na.action, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a numeric vector of data values, or a list of numeric data
vectors.
\item[\code{g}] a vector or factor object giving the group for the
corresponding elements of \code{x}.  Ignored if \code{x} is a
list.
\item[\code{formula}] a formula of the form \code{lhs \textasciitilde{} rhs} where \code{lhs}
gives the data values and \code{rhs} the corresponding groups.
\item[\code{data}] an optional matrix or data frame (or similar: see
\code{\LinkA{model.frame}{model.frame}}) containing the variables in the
formula \code{formula}.  By default the variables are taken from
\code{environment(formula)}.
\item[\code{subset}] an optional vector specifying a subset of observations
to be used.
\item[\code{na.action}] a function which indicates what should happen when
the data contain \code{NA}s.  Defaults to
\code{getOption("na.action")}.
\item[\code{...}] further arguments to be passed to or from methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{kruskal.test} performs a Kruskal-Wallis rank sum test of the
null that the location parameters of the distribution of \code{x}
are the same in each group (sample).  The alternative is that they
differ in at least one.

If \code{x} is a list, its elements are taken as the samples to be
compared, and hence have to be numeric data vectors.  In this case,
\code{g} is ignored, and one can simply use \code{kruskal.test(x)}
to perform the test.  If the samples are not yet contained in a
list, use \code{kruskal.test(list(x, ...))}.

Otherwise, \code{x} must be a numeric data vector, and \code{g} must
be a vector or factor object of the same length as \code{x} giving
the group for the corresponding elements of \code{x}.
\end{Details}
\begin{Value}
A list with class \code{"htest"} containing the following components:
\begin{ldescription}
\item[\code{statistic}] the Kruskal-Wallis rank sum statistic.
\item[\code{parameter}] the degrees of freedom of the approximate
chi-squared distribution of the test statistic.
\item[\code{p.value}] the p-value of the test.
\item[\code{method}] the character string \code{"Kruskal-Wallis rank sum test"}.
\item[\code{data.name}] a character string giving the names of the data.
\end{ldescription}
\end{Value}
\begin{References}\relax
Myles Hollander \& Douglas A. Wolfe (1973),
\emph{Nonparametric statistical inference}.
New York: John Wiley \& Sons.
Pages 115--120.
\end{References}
\begin{SeeAlso}\relax
The Wilcoxon rank sum test (\code{\LinkA{wilcox.test}{wilcox.test}}) as the special
case for two samples;
\code{\LinkA{lm}{lm}} together with \code{\LinkA{anova}{anova}} for performing
one-way location analysis under normality assumptions; with Student's
t test (\code{\LinkA{t.test}{t.test}}) as the special case for two samples.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Hollander & Wolfe (1973), 116.
## Mucociliary efficiency from the rate of removal of dust in normal
##  subjects, subjects with obstructive airway disease, and subjects
##  with asbestosis.
x <- c(2.9, 3.0, 2.5, 2.6, 3.2) # normal subjects
y <- c(3.8, 2.7, 4.0, 2.4)      # with obstructive airway disease
z <- c(2.8, 3.4, 3.7, 2.2, 2.0) # with asbestosis
kruskal.test(list(x, y, z))
## Equivalently,
x <- c(x, y, z)
g <- factor(rep(1:3, c(5, 4, 5)),
            labels = c("Normal subjects",
                       "Subjects with obstructive airway disease",
                       "Subjects with asbestosis"))
kruskal.test(x, g)

## Formula interface.
boxplot(Ozone ~ Month, data = airquality)
kruskal.test(Ozone ~ Month, data = airquality)
\end{ExampleCode}
\end{Examples}

