% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mann-whitney.R
\name{mann_whitney_test_pv}
\alias{mann_whitney_test_pv}
\title{Wilcoxon-Mann-Whitney \emph{U} test}
\usage{
mann_whitney_test_pv(
  x,
  y,
  mu = 0,
  alternative = "two.sided",
  exact = NULL,
  correct = TRUE,
  digits_rank = Inf,
  simple_output = FALSE
)
}
\arguments{
\item{x, y}{numerical vectors forming the samples to be tested or lists
of numerical vectors for multiple tests.}

\item{mu}{numerical vector or single number of hypothesised location
shift(s).}

\item{alternative}{character vector that indicates the alternative hypotheses; each value must be one of \code{"two.sided"} (the default), \code{"less"} or \code{"greater"}.}

\item{exact}{single logical value that indicates whether \eqn{p}-values are to be calculated by exact computation (\code{TRUE}) or by a continuous approximation (\code{FALSE}). \code{NULL} (the default) is allowed (see details).}

\item{correct}{either a single logical value that indicates if a continuity correction in the normal approximation is to be applied (\code{TRUE}; the default) or not (\code{FALSE}), or a single integer between 0 and 3 specifying both that a continuity correction should be used \emph{and} the number of terms of an Edgeworth expansion for a more accurate normal approximation. Ignored, if \code{exact = TRUE}.}

\item{digits_rank}{single number giving the significant digits used to compute ranks for the test statistics.}

\item{simple_output}{logical value that indicates whether an R6 class object, including the tests' parameters and support sets, i.e. all observable p-values under each null hypothesis, is to be returned (see below).}
}
\value{
If \code{simple.output = TRUE}, a vector of computed p-values is returned.
Otherwise, the output is a \code{\link{DiscreteTestResults}} R6 class object, which
also includes the p-value supports and testing parameters. These have to be
accessed by public methods, e.g. \verb{$get_pvalues()}.
}
\description{
\code{mann_whitney_test_pv()} performs an exact or approximate
Wilcoxon-Mann-Whitney \emph{U} test about the location shift between two
independent groups when the data is not necessarily normally distributed. In
contrast to \code{\link[stats:wilcox.test]{stats::wilcox.test()}}, it is vectorised and only calculates
\emph{p}-values. Furthermore, it is capable of returning the discrete \emph{p}-value
supports, i.e. all observable \emph{p}-values under a null hypothesis. Multiple
tests can be evaluated simultaneously.
}
\details{
We use a test statistic called the Wilcoxon Rank Sum Statistic, defined by
\deqn{U = \sum_{i = 1}^{n_X}{rank(X_i)} - \frac{n_X(n_X + 1)}{2},}
where \eqn{rank(X_i)} is the rank of \eqn{X_i} in the concatenated sample
of \eqn{X} and \eqn{Y}, and \eqn{n_X} and \eqn{n_Y} are the respective
sizes of the samples \eqn{X} and \eqn{Y}. Note that \eqn{U}
can range from \eqn{0} to \eqn{n_X \cdot n_Y}.
This is the same statistic used by \code{\link[stats:wilcox.test]{stats::wilcox.test()}} and
whose distribution is accessible with \code{\link{pwilcox}}.
This is also the statistic defined by the two given references.
Note, however, that it is not what is called the Mann-Whitney U Statistic
in the (English-language) Wikipedia article (as of February 12, 2026). The
latter is defined as, using our notation, \eqn{\min(U, n_X \cdot n_Y - U)}.
Using the Wikipedia notation, the Wilcoxon Rank Sum Statistic is \eqn{U_2}.

The parameters \code{x}, \code{y}, \code{mu} and \code{alternative} are vectorised. If \code{x} and
\code{y} are lists, they are replicated automatically to have the same lengths. In
case \code{x} or \code{y} are not lists, they are added to new ones, which are then
replicated to the appropriate lengths. This allows multiple hypotheses to be
tested simultaneously.

In the presence of ties, computation of the Edgeworth series (up to
\code{correct = 3}) is not possible. Therefore, numeric values of \code{correct}
are ignored and only a continuity correction is performed.

By setting \code{exact = NULL}, exact computation is performed only if both
samples sizes in a test setting are lower than or equal to 200. Otherwise,
\eqn{p}-values are computed by normal approximation.

If \code{digits_rank = Inf} (the default), \code{\link[base:rank]{rank()}} is used to
compute ranks for the tests statistics instead of
\code{\link[base:rank]{rank}}(\code{\link[base:signif]{signif(., digits_rank)}})
}
\examples{
# Constructing
set.seed(1)
r1 <- rnorm(100)
r2 <- rnorm(100, 1)

# Exact two-sided p-values and their supports
results_ex  <- mann_whitney_test_pv(r1, r2)
print(results_ex)
results_ex$get_pvalues()
results_ex$get_pvalue_supports()

# Normal-approximated one-sided p-values ("less") and their supports
results_ap  <- mann_whitney_test_pv(r1, r2, alternative = "less", exact = FALSE)
print(results_ap)
results_ap$get_pvalues()
results_ap$get_pvalue_supports()

}
\references{
Mann, H. D. & Whitney, D. R. (1947). On a Test of Whether one of Two Random
Variables is Stochastically Larger than the Other. \emph{Ann. Math. Statist.},
\emph{18}(1), pp. 50-60. \doi{10.1214/aoms/1177730491}

Hollander, M. & Wolfe, D. (1973). \emph{Nonparametric Statistical Methods}. Third
Edition. New York: Wiley. pp. 115-135. \doi{10.1002/9781119196037}
}
\seealso{
\code{\link[stats:wilcox.test]{stats::wilcox.test()}}, \code{\link{pwilcox}}, \code{\link[=wilcox_test_pv]{wilcox_test_pv()}}
}
