wilcox_test_pv: Wilcoxon's signed-rank test

In DiscreteTests: Vectorised Computation of P-Values and Their Supports for Several Discrete Statistical Tests

Wilcoxon's signed-rank test

Description

wilcox_test_pv() performs an exact or approximate Wilcoxon signed-rank test about the location of a population on a single sample or the differences between two paired groups when the data is not necessarily normally distributed. In contrast to stats::wilcox.test(), it is vectorised and only calculates p-values. Furthermore, it is capable of returning the discrete p-value supports, i.e. all observable p-values under a null hypothesis. Multiple tests can be evaluated simultaneously.

Usage

wilcox_test_pv(
  x,
  y = NULL,
  mu = 0,
  alternative = "two.sided",
  exact = NULL,
  correct = TRUE,
  digits_rank = Inf,
  zero_method = "pratt",
  simple_output = FALSE
)

Arguments

x	numerical vector forming the sample to be tested or a list of numerical vectors for multiple tests.
y	numerical vector forming the second sample to be tested or a list of numerical vectors for multiple tests; if y = NULL (the default), the one-sample version is performed; for two-sample tests, all sample pairs must have the same length.
mu	numerical vector or single number of hypothesised location(s) for one-sample tests or location shift(s) for two-sample tests.
alternative	character vector that indicates the alternative hypotheses; each value must be one of "two.sided" (the default), "less" or "greater".
exact	single logical value that indicates whether p-values are to be calculated by exact computation (TRUE) or by a continuous approximation (FALSE). NULL (the default) is allowed (see details).
correct	either a single logical value that indicates if a continuity correction in the normal approximation is to be applied (TRUE; the default) or not (FALSE), or a single integer between 0 and 3 specifying both that a continuity correction should be used and the number of terms of an Edgeworth expansion for a more accurate normal approximation. Ignored, if exact = TRUE.
digits_rank	single number giving the significant digits used to compute ranks for the test statistics.
zero_method	character vector or single string specifying how zero differences are handled; must either be "pratt" (the default) or "wilcoxon". With "pratt", zero differences are included when computing ranks, but excluded from the test statistic; with "wilcoxon", zero differences are discarded entirely before ranking (the original Wilcoxon approach).
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).

Details

The parameters x, mu, alternative and zero_method are vectorised. If x is a list, they are replicated automatically to have the same lengths. In case x is not a list, it is added to one, which is then replicated to the appropriate length. This allows multiple hypotheses to be tested simultaneously.

By setting exact = NULL, exact computation is performed only if the sample size in a test setting is smaller than or equal to 200. Otherwise, p-values are computed by normal approximation.

The used test statistics W is also known as T+ and is defined as the sum of ranks of all strictly positive values of the sample x.

If digits_rank = Inf (the default), rank() is used to compute ranks for the tests statistics instead of rank(signif(., digits_rank))

Value

If simple.output = TRUE, a vector of computed p-values is returned. Otherwise, the output is a DiscreteTestResults R6 class object, which also includes the p-value supports and testing parameters. These have to be accessed by public methods, e.g. ⁠$get_pvalues()⁠.

References

Hollander, M. & Wolfe, D. (1973). Nonparametric Statistical Methods. Third Edition. New York: Wiley. pp. 40-55. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/9781119196037")}

See Also

stats::wilcox.test(), mann_whitney_test_pv()

Examples

# Constructing
set.seed(1)
r1 <- rnorm(200)
r2 <- rnorm(200, 1)
r3 <- rnorm(200, 2)

## One-sample tests
#  Exact two-sided p-values and their supports
results_ex_1s <- wilcox_test_pv(r1)
print(results_ex_1s)
results_ex_1s$get_pvalues()
results_ex_1s$get_pvalue_supports()

#  Multiple normal-approximated one-sided tests ("greater")
results_ap_1s <- wilcox_test_pv(list(r1, r2), alternative = "greater", exact = FALSE)
print(results_ap_1s)
results_ap_1s$get_pvalues()
results_ap_1s$get_pvalue_supports()

## Two-sample-tests
#  Normal-approximated one-sided p-values ("less") and their supports
results_ap_2s <- wilcox_test_pv(r1, r2, alternative = "less", exact = FALSE)
print(results_ap_2s)
results_ap_2s$get_pvalues()
results_ap_2s$get_pvalue_supports()

#  Multiple exact two-sided tests ("greater")
results_ex_2s <- wilcox_test_pv(list(r1, r3), r2)
print(results_ex_2s)
results_ex_2s$get_pvalues()
results_ex_2s$get_pvalue_supports()

DiscreteTests documentation built on Sept. 2, 2026, 9:06 a.m.