DiscreteTests (version 0.3.0)

wilcox_test_pv: 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,
  simple_output = FALSE
)

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().

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 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

logical value that indicates whether p-values are to be calculated by exact computation (TRUE; the default) or by a continuous approximation (FALSE).

correct

logical value that indicates if a continuity correction is to be applied (TRUE; the default) or not (FALSE). Ignored, if exact = TRUE.

digits_rank,

single number giving the significant digits used to compute ranks for the test statistics.

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 and alternative 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.

In the presence of ties or observations that are equal to mu, computation of exact p-values is not possible. Therefore, exact is ignored in these cases and p-values of the respective test settings are calculated by a normal approximation.

By setting exact = NULL, exact computation is performed if the sample in a test setting does not have any ties or zeros and if the sample size is lower than or equal to 200.

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))

References

Hollander, M. & Wolfe, D. (1973). Nonparametric Statistical Methods. Third Edition. New York: Wiley. pp. 40-55. 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()