wilcox_test: Wilcoxon Tests

In rstatix: Pipe-Friendly Framework for Basic Statistical Tests

Wilcoxon Tests

Description

Provides a pipe-friendly framework to performs one and two sample Wilcoxon tests.

See the Datanovia tutorial Wilcoxon Test in R for a worked walkthrough.

Usage

wilcox_test(
  data,
  formula,
  comparisons = NULL,
  ref.group = NULL,
  p.adjust.method = "holm",
  paired = FALSE,
  exact = NULL,
  alternative = "two.sided",
  mu = 0,
  conf.level = 0.95,
  detailed = FALSE,
  id = NULL,
  error.as.na = FALSE,
  effect.size = FALSE
)

pairwise_wilcox_test(
  data,
  formula,
  comparisons = NULL,
  ref.group = NULL,
  p.adjust.method = "holm",
  detailed = FALSE,
  ...,
  effect.size = FALSE
)

Arguments

data	a data.frame containing the variables in the formula.
formula	a formula of the form x ~ group where x is a numeric variable giving the data values and group is a factor with one or multiple levels giving the corresponding groups. For example, formula = TP53 ~ cancer_group.
comparisons	A list of length-2 vectors specifying the groups of interest to be compared. For example to compare groups "A" vs "B" and "B" vs "C", the argument is as follow: comparisons = list(c("A", "B"), c("B", "C"))
ref.group	a character string specifying the reference group. If specified, for a given grouping variable, each of the group levels will be compared to the reference group (i.e. control group). If ref.group = "all", pairwise two sample tests are performed for comparing each grouping variable levels against all (i.e. basemean).
p.adjust.method	method to adjust p values for multiple comparisons. Used when pairwise comparisons are performed. Allowed values include "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". If you don't want to adjust the p value (not recommended), use p.adjust.method = "none".
paired	a logical indicating whether you want a paired test.
exact	a logical indicating whether an exact p-value should be computed.
alternative	a character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater" or "less". You can specify just the initial letter.
mu	a number specifying an optional parameter used to form the null hypothesis.
conf.level	confidence level of the interval.
detailed	logical value. Default is FALSE. If TRUE, a detailed result is shown.
id	(optional) character string specifying the column that contains the sample/subject identifier, used only for a paired test (paired = TRUE). When supplied, observations of the two compared groups are matched by id (instead of by row order), and only subjects present in both groups are used. For more than two groups, the matching is done independently for each pairwise comparison, so different comparisons can be based on different numbers of pairs (per-comparison pairwise deletion). This makes paired tests work when some observations are missing or the groups have unequal sizes. The default (id = NULL) keeps the previous behaviour (groups paired in row order).
error.as.na	logical. If TRUE, a comparison that cannot be computed (for example a group with fewer than two observations, or data that are essentially constant) returns an NA result row with a warning instead of stopping with an error; the other comparisons (or groups, for a grouped analysis) are still computed. Default is FALSE (the comparison errors as before).
effect.size	logical. Default is FALSE. If TRUE, a rank effect-size column is added: for an independent-samples test cliff.delta (Cliff's delta) and its magnitude; for a paired test the matched-pairs rank.biserial correlation (no magnitude, as no threshold set is calibrated for it), computed on the same paired differences the test used (matched by id when supplied). Not defined for a one-sample test.
...	other arguments to be passed to the function wilcox.test.

Details

- pairwise_wilcox_test() applies the standard two sample Wilcoxon test to all possible pairs of groups. This method calls the wilcox.test(), so extra arguments are accepted.

- If a list of comparisons is specified, the result of the pairwise tests is filtered to keep only the comparisons of interest.The p-value is adjusted after filtering.

- For a grouped data, if pairwise test is performed, then the p-values are adjusted for each group level independently.

- a nonparametric confidence interval and an estimator for the pseudomedian (one-sample case) or for the difference of the location parameters x-y is computed, where x and y are the compared samples or groups. The column estimate and the confidence intervals are displayed in the test result when the option detailed = TRUE is specified in the wilcox_test() and pairwise_wilcox_test() functions. Read more about the calculation of the estimate in the details section of the R base function wilcox.test() documentation by typing ?wilcox.test in the R console.

- With effect.size = TRUE, an independent-samples test is annotated with Cliff's delta and a paired test with the matched-pairs rank-biserial correlation, (R^+ - R^-)/(R^+ + R^-) over the signed ranks of the paired differences (Kerby, 2014).

Value

return a data frame with some of the following columns:

• .y.: the y variable used in the test.

• group1,group2: the compared groups in the pairwise tests.

• n,n1,n2: Sample counts.

• statistic: Test statistic used to compute the p-value.

• p: p-value.

• p.adj: the adjusted p-value.

• method: the statistical test used to compare groups.

• p.signif, p.adj.signif: the significance level of p-values and adjusted p-values, respectively.

• estimate: an estimate of the location parameter (Only present if argument detailed = TRUE). This corresponds to the pseudomedian (for one-sample case) or to the difference of the location parameter (for two-samples case).

  • The pseudomedian of a distribution F is the median of the distribution of (u+v)/2, where u and v are independent, each with distribution F. If F is symmetric, then the pseudomedian and median coincide.

  • Note that in the two-sample case the estimator for the difference in location parameters does not estimate the difference in medians (a common misconception) but rather the median of the difference between a sample from x and a sample from y.

• conf.low, conf.high: a confidence interval for the location parameter. (Only present if argument conf.int = TRUE.)

The returned object has an attribute called args, which is a list holding the test arguments.

Functions

• wilcox_test(): Wilcoxon test

• pairwise_wilcox_test(): performs pairwise two sample Wilcoxon test.

Note

When a ref.group is specified, the reference group is taken as group1 and the other group as group2, and the comparison is computed as group1 versus group2 (i.e. ref.group versus the other group), following the wilcox.test convention. With detailed = TRUE, the estimate is the Hodges-Lehmann location shift of group1 relative to group2, so a positive estimate means the reference group is shifted higher; flip its sign (mutate(estimate = -estimate)) if you want a positive sign to mean "higher in the non-reference group". (The statistic is the rank-sum/signed-rank W, which is not a signed difference.)

References

Kerby, D. S. (2014). The simple difference formula: An approach to teaching nonparametric correlation. Comprehensive Psychology, 3, 11.IT.3.1.

See Also

The Datanovia tutorial: Wilcoxon Test in R.

Examples

# Load data
#:::::::::::::::::::::::::::::::::::::::
data("ToothGrowth")
df <- ToothGrowth

# One-sample test
#:::::::::::::::::::::::::::::::::::::::::
df %>% wilcox_test(len ~ 1, mu = 0)


# Two-samples unpaired test
#:::::::::::::::::::::::::::::::::::::::::
df %>% wilcox_test(len ~ supp)

# Two-samples paired test
#:::::::::::::::::::::::::::::::::::::::::
df %>% wilcox_test (len ~ supp, paired = TRUE)

# Compare supp levels after grouping the data by "dose"
#::::::::::::::::::::::::::::::::::::::::
df %>%
  group_by(dose) %>%
  wilcox_test(data =., len ~ supp) %>%
  adjust_pvalue(method = "bonferroni") %>%
  add_significance("p.adj")

# pairwise comparisons
#::::::::::::::::::::::::::::::::::::::::
# As dose contains more than two levels ==>
# pairwise test is automatically performed.
df %>% wilcox_test(len ~ dose)

# Comparison against reference group
#::::::::::::::::::::::::::::::::::::::::
# each level is compared to the ref group
df %>% wilcox_test(len ~ dose, ref.group = "0.5")

# Comparison against all
#::::::::::::::::::::::::::::::::::::::::
df %>% wilcox_test(len ~ dose, ref.group = "all")

rstatix documentation built on July 24, 2026, 1:06 a.m.