% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sign.r
\name{sign_test_pv}
\alias{sign_test_pv}
\title{Sign Tests}
\usage{
sign_test_pv(
  x,
  y = NULL,
  mu = 0,
  alternative = "two.sided",
  exact = TRUE,
  correct = TRUE,
  simple_output = FALSE
)
}
\arguments{
\item{x}{numerical vector forming the sample to be tested or a list of
numerical vectors for multiple tests.}

\item{y}{numerical vector forming the second sample to be tested or a
list of numerical vectors for multiple tests; if \code{y = NULL}
(the default), the one-sample version is performed; for
two-sample tests, all sample pairs must have the same length.}

\item{mu}{numerical vector of hypothesised median(s) for one-sample
tests or median(s) of differences for two-sample tests.}

\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}; the default) or by a continuous approximation (\code{FALSE}).}

\item{correct}{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}). Ignored, if \code{exact = TRUE}.}

\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{sign_test_pv()} performs an exact or approximate sign test about the median
of a distribution. It supports both one-sample and two-sample paired tests.
In contrast to other implementations, it is vectorised, only calculates
\emph{p}-values, and offers a normal approximation of their computation.
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. In two-sided tests, several procedures of obtaining
the respective \emph{p}-values are implemented.
}
\details{
For the \strong{one-sample} case, the sign test counts the number of observations
in \code{x} that exceed the hypothesised median \code{mu}. Observations exactly equal
to \code{mu} (ties) are discarded. Under the null hypothesis, the number of
positive signs follows a Binomial(\eqn{n}, 0.5) distribution, where \eqn{n}
is the number of non-tied observations.

For the \strong{two-sample paired} case (when \code{y} is supplied), the pairwise
differences \eqn{d_i = x_i - y_i - \mu} are computed first. The sign test is
then applied to these differences.

If \code{x} is a list, multiple tests are evaluated simultaneously. The parameters
\code{x}, \code{y} (if supplied and a list), \code{mu}, and \code{alternative} are vectorised.
They are replicated automatically to have the same lengths. This allows
multiple hypotheses to be tested simultaneously.

The sign test is a special case of the binomial test. In contrast to
\code{\link[=binom_test_pv]{binom_test_pv()}}, \code{sign_test_pv()} does not allow specifying exact
two-sided \emph{p}-value calculation procedures. The reason is that the exact sign
test always tests for a probability of 0.5, in which case all these exact
two-sided \emph{p}-value computation methods yield exactly the same results.
}
\examples{
# One-sample sign test: test whether median equals 3
x <- c(1, 5, 2, 7, 6, 8, 4)
results_1s <- sign_test_pv(x, mu = 3)
print(results_1s)
results_1s$get_pvalues()
results_1s$get_pvalue_supports()

# Paired two-sample sign test: test whether difference of medians equals 1
x2 <- c(6, 8, 2, 4, 5)
y2 <- c(3, 5, 4, 2, 6)
results_2s <- sign_test_pv(x2, y2, mu = 1)
print(results_2s)
results_2s$get_pvalues()

# Multiple tests simultaneously, one-sided p-values (one-sample, list input)
xs <- list(c(1, 5, 2, 7, 6, 8, 4), c(2, 4, 6, 1, 9))
results_l <- sign_test_pv(xs, mu = c(3, 5), alternative = "greater")
print(results_l)
results_l$get_pvalues()

# Normal-approximated (one-sample, list input)
results_a <- sign_test_pv(xs, mu = c(3, 5), exact = FALSE)
print(results_a)
results_a$get_pvalues()

}
\references{
Dixon, W. J. and Mood, A. M. (1946). The statistical sign test.
\emph{Journal of the American Statistical Association}, \strong{41}(236),
pp. 557–566. \doi{10.1080/01621459.1946.10501898}
}
\seealso{
\code{\link[=binom_test_pv]{binom_test_pv()}}, \code{\link[stats:binom.test]{stats::binom.test()}}
}
