NAG Library Routine Document
g08agf (test_wilcoxon)
1
Purpose
g08agf performs the Wilcoxon signed rank test on a single sample of size $n$.
2
Specification
Fortran Interface
Subroutine g08agf ( 
n, x, xme, tail, zer, w, wnor, p, n1, wrk, ifail) 
Integer, Intent (In)  ::  n  Integer, Intent (Inout)  ::  ifail  Integer, Intent (Out)  ::  n1  Real (Kind=nag_wp), Intent (In)  ::  x(n), xme  Real (Kind=nag_wp), Intent (Out)  ::  w, wnor, p, wrk(3*n)  Character (1), Intent (In)  ::  tail, zer 

C Header Interface
#include <nagmk26.h>
void 
g08agf_ (const Integer *n, const double x[], const double *xme, const char *tail, const char *zer, double *w, double *wnor, double *p, Integer *n1, double wrk[], Integer *ifail, const Charlen length_tail, const Charlen length_zer) 

3
Description
The Wilcoxon onesample signed rank test may be used to test whether a particular sample came from a population with a specified median. It is assumed that the population distribution is symmetric. The data consists of a single sample of $n$ observations denoted by ${x}_{1},{x}_{2},\dots ,{x}_{n}$. This sample may arise from the difference between pairs of observations from two matched samples of equal size taken from two populations, in which case the test may be used to test whether the median of the first population is the same as that of the second population.
The hypothesis under test,
${\mathrm{H}}_{0}$, often called the null hypothesis, is that the median is equal to some given value
$\left({X}_{\mathrm{med}}\right)$, and this is to be tested against an alternative hypothesis
${H}_{1}$ which is
 ${H}_{1}$: population median $\text{}\ne {X}_{\mathrm{med}}$; or
 ${H}_{1}$: population median $\text{}>{X}_{\mathrm{med}}$; or
 ${H}_{1}$: population median $\text{}<{X}_{\mathrm{med}}$,
using a two tailed, upper tailed or lower tailed probability respectively. You select the alternative hypothesis by choosing the appropriate tail probability to be computed (see the description of argument
tail in
Section 5).
The Wilcoxon test differs from the Sign test (see
g08aaf) in that the magnitude of the scores is taken into account, rather than simply the direction of such scores.
The test procedure is as follows
(a) 
For each ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$, the signed difference ${d}_{i}={x}_{i}{X}_{\mathrm{med}}$ is found, where ${X}_{\mathrm{med}}$ is a given test value for the median of the sample. 
(b) 
The absolute differences $\left{d}_{i}\right$ are ranked with rank ${r}_{i}$ and any tied values of $\left{d}_{i}\right$ are assigned the average of the tied ranks. You may choose whether or not to ignore any cases where ${d}_{i}=0$ by removing them before or after ranking (see the description of the argument zer in Section 5). 
(c) 
The number of nonzero ${d}_{i}$ is found. 
(d) 
To each rank is affixed the sign of the ${d}_{i}$ to which it corresponds. Let ${s}_{i}=\mathrm{sign}\left({d}_{i}\right){r}_{i}$. 
(e) 
The sum of the positivesigned ranks, $W={\displaystyle \sum _{{s}_{i}>0}}\phantom{\rule{0.25em}{0ex}}{s}_{i}={\displaystyle \sum _{i=1}^{n}}\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({s}_{i},0.0\right)$, is calculated. 
g08agf returns
(a) 
the test statistic $W$; 
(b) 
the number ${n}_{1}$ of nonzero ${d}_{i}$; 
(c) 
the approximate Normal test statistic $z$, where

(d) 
the tail probability, $p$, corresponding to $W$, depending on the choice of the alternative hypothesis, ${H}_{1}$. 
If ${n}_{1}\le 80$, $p$ is computed exactly; otherwise, an approximation to $p$ is returned based on an approximate Normal statistic corrected for continuity according to the tail specified.
The value of $p$ can be used to perform a significance test on the median against the alternative hypothesis. Let $\alpha $ be the size of the significance test (that is, $\alpha $ is the probability of rejecting ${H}_{0}$ when ${H}_{0}$ is true). If $p<\alpha $ then the null hypothesis is rejected. Typically $\alpha $ might be $0.05$ or $0.01$.
4
References
Conover W J (1980) Practical Nonparametric Statistics Wiley
Neumann N (1988) Some procedures for calculating the distributions of elementary nonparametric teststatistics Statistical Software Newsletter 14(3) 120–126
Siegel S (1956) Nonparametric Statistics for the Behavioral Sciences McGraw–Hill
5
Arguments
 1: $\mathbf{n}$ – IntegerInput

On entry: $n$, the size of the sample.
Constraint:
${\mathbf{n}}\ge 1$.
 2: $\mathbf{x}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the sample observations, ${x}_{1},{x}_{2},\dots ,{x}_{n}$.
 3: $\mathbf{xme}$ – Real (Kind=nag_wp)Input

On entry: the median test value, ${X}_{\mathrm{med}}$.
 4: $\mathbf{tail}$ – Character(1)Input

On entry: indicates the choice of tail probability, and hence the alternative hypothesis.
 ${\mathbf{tail}}=\text{'T'}$
 A two tailed probability is calculated and the alternative hypothesis is ${\mathrm{H}}_{1}$: population median $\text{}\ne {X}_{\mathrm{med}}$.
 ${\mathbf{tail}}=\text{'U'}$
 An upper tailed probability is calculated and the alternative hypothesis is ${\mathrm{H}}_{1}$: population median $\text{}>{X}_{\mathrm{med}}$.
 ${\mathbf{tail}}=\text{'L'}$
 A lower tailed probability is calculated and the alternative hypothesis is ${\mathrm{H}}_{1}$: population median $\text{}<{X}_{\mathrm{med}}$.
Constraint:
${\mathbf{tail}}=\text{'T'}$, $\text{'U'}$ or $\text{'L'}$.
 5: $\mathbf{zer}$ – Character(1)Input

On entry: indicates whether or not to include the cases where
${d}_{i}=0.0$ in the ranking of the
${d}_{i}$s.
 ${\mathbf{zer}}=\text{'Y'}$
 All ${d}_{i}=0.0$ are included when ranking.
 ${\mathbf{zer}}=\text{'N'}$
 All ${d}_{i}=0.0$, are ignored, that is all cases where ${d}_{i}=0.0$ are removed before ranking.
Constraint:
${\mathbf{zer}}=\text{'Y'}$ or $\text{'N'}$.
 6: $\mathbf{w}$ – Real (Kind=nag_wp)Output

On exit: the Wilcoxon rank sum statistic, $W$, being the sum of the positive ranks.
 7: $\mathbf{wnor}$ – Real (Kind=nag_wp)Output

On exit: the approximate Normal test statistic,
$z$, as described in
Section 3.
 8: $\mathbf{p}$ – Real (Kind=nag_wp)Output

On exit: the tail probability,
$p$, as specified by the argument
tail.
 9: $\mathbf{n1}$ – IntegerOutput

On exit: the number of nonzero ${d}_{i}$'s, ${n}_{1}$.
 10: $\mathbf{wrk}\left(3\times {\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayWorkspace

 11: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{tail}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{tail}}=\text{'T'}$, $\text{'U'}$ or $\text{'L'}$.
On entry, ${\mathbf{zer}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{zer}}=\text{'Y'}$ or $\text{'N'}$.
 ${\mathbf{ifail}}=2$

On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 1$.
 ${\mathbf{ifail}}=3$

All elements of the sample are equal to
xme, i.e.,
$\text{variance}=0$.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
The approximation used to calculate $p$ when ${n}_{1}>80$ will return a value with a relative error of less than $10\%$ for most cases. The error may increase for cases where there are a large number of ties in the sample.
8
Parallelism and Performance
g08agf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The time taken by g08agf increases with ${n}_{1}$, until ${n}_{1}>80$, from which point on the approximation is used. The time decreases significantly at this point and increases again modestly with ${n}_{1}$ for ${n}_{1}>80$.
10
Example
This example performs the Wilcoxon signed rank test on two matched samples of size $8$, taken from two populations. The distribution of the differences between pairs of observations from the two populations is assumed to be symmetric. The test is used to test whether the medians of the two distributions of the populations are equal or not. The test statistic, the approximate Normal statistic and the two tailed probability are computed and printed.
10.1
Program Text
Program Text (g08agfe.f90)
10.2
Program Data
Program Data (g08agfe.d)
10.3
Program Results
Program Results (g08agfe.r)