org.apache.commons.math3.stat.inference

## Class WilcoxonSignedRankTest

- java.lang.Object
- - org.apache.commons.math3.stat.inference.WilcoxonSignedRankTest

    public class WilcoxonSignedRankTest
    extends Object

An implementation of the Wilcoxon signed-rank test.

Version:
  $Id: WilcoxonSignedRankTest.java 1416643 2012-12-03 19:37:14Z tn $

### Field Summary

Fields
`private NaturalRanking` `naturalRanking` Ranking algorithm.

### Constructor Summary

Constructors
Constructor and Description
`WilcoxonSignedRankTest()` Create a test instance where NaN's are left in place and ties get the average of applicable ranks.
`WilcoxonSignedRankTest(NaNStrategy nanStrategy, TiesStrategy tiesStrategy)` Create a test instance using the given strategies for NaN's and ties.

### Method Summary

Methods
`private double[]` `calculateAbsoluteDifferences(double[] z)` Calculates |z[i]| for all i
`private double` `calculateAsymptoticPValue(double Wmin, int N)`
`private double[]` `calculateDifferences(double[] x, double[] y)` Calculates y[i] - x[i] for all i
`private double` `calculateExactPValue(double Wmax, int N)` Algorithm inspired by http://www.fon.hum.uva.nl/Service/Statistics/Signed_Rank_Algorihms.html#C by Rob van Son, Institute of Phonetic Sciences & IFOTT, University of Amsterdam
`private void` `ensureDataConformance(double[] x, double[] y)` Ensures that the provided arrays fulfills the assumptions.
`double` `wilcoxonSignedRank(double[] x, double[] y)` Computes the Wilcoxon signed ranked statistic comparing mean for two related samples or repeated measurements on a single sample.
`double` `wilcoxonSignedRankTest(double[] x, double[] y, boolean exactPValue)` Returns the observed significance level, or p-value, associated with a Wilcoxon signed ranked statistic comparing mean for two related samples or repeated measurements on a single sample.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### naturalRanking

    private NaturalRanking naturalRanking

Ranking algorithm.

### Constructor Detail

#### WilcoxonSignedRankTest

    public WilcoxonSignedRankTest()

Create a test instance where NaN's are left in place and ties get the average of applicable ranks. Use this unless you are very sure of what you are doing.

#### WilcoxonSignedRankTest

    public WilcoxonSignedRankTest(NaNStrategy nanStrategy,
                          TiesStrategy tiesStrategy)

Create a test instance using the given strategies for NaN's and ties. Only use this if you are sure of what you are doing.

Parameters:
  `nanStrategy` - specifies the strategy that should be used for Double.NaN's
  `tiesStrategy` - specifies the strategy that should be used for ties

### Method Detail

#### ensureDataConformance

    private void ensureDataConformance(double[] x,
                             double[] y)
                                throws NullArgumentException,
                                       NoDataException,
                                       DimensionMismatchException

Ensures that the provided arrays fulfills the assumptions.

Parameters:
  `x` - first sample
  `y` - second sample
Throws:
  `NullArgumentException` - if `x` or `y` are `null`.
  `NoDataException` - if `x` or `y` are zero-length.
  `DimensionMismatchException` - if `x` and `y` do not have the same length.

#### calculateDifferences

    private double[] calculateDifferences(double[] x,
                                double[] y)

Calculates y[i] - x[i] for all i

Parameters:
  `x` - first sample
  `y` - second sample
Returns:
  z = y - x

#### calculateAbsoluteDifferences

    private double[] calculateAbsoluteDifferences(double[] z)
                                           throws NullArgumentException,
                                                  NoDataException

Calculates |z[i]| for all i

Parameters:
  `z` - sample
Returns:
  |z|
Throws:
  `NullArgumentException` - if `z` is `null`
  `NoDataException` - if `z` is zero-length.

#### wilcoxonSignedRank

    public double wilcoxonSignedRank(double[] x,
                            double[] y)
                              throws NullArgumentException,
                                     NoDataException,
                                     DimensionMismatchException

Computes the Wilcoxon signed ranked statistic comparing mean for two related samples or repeated measurements on a single sample.

This statistic can be used to perform a Wilcoxon signed ranked test evaluating the null hypothesis that the two related samples or repeated measurements on a single sample has equal mean.

Let Xi denote the i'th individual of the first sample and Yi the related i'th individual in the second sample. Let Zi = Yi - Xi.

Preconditions:

- The differences Zi must be independent.
- Each Zi comes from a continuous population (they must be identical) and is symmetric about a common median.
- The values that Xi and Yi represent are ordered, so the comparisons greater than, less than, and equal to are meaningful.

Parameters:
  `x` - the first sample
  `y` - the second sample
Returns:
  wilcoxonSignedRank statistic (the larger of W+ and W-)
Throws:
  `NullArgumentException` - if `x` or `y` are `null`.
  `NoDataException` - if `x` or `y` are zero-length.
  `DimensionMismatchException` - if `x` and `y` do not have the same length.

#### calculateExactPValue

    private double calculateExactPValue(double Wmax,
                              int N)

Algorithm inspired by http://www.fon.hum.uva.nl/Service/Statistics/Signed_Rank_Algorihms.html#C by Rob van Son, Institute of Phonetic Sciences & IFOTT, University of Amsterdam

Parameters:
  `Wmax` - largest Wilcoxon signed rank value
  `N` - number of subjects (corresponding to x.length)
Returns:
  two-sided exact p-value

#### calculateAsymptoticPValue

    private double calculateAsymptoticPValue(double Wmin,
                                   int N)

Parameters:
  `Wmin` - smallest Wilcoxon signed rank value
  `N` - number of subjects (corresponding to x.length)
Returns:
  two-sided asymptotic p-value

#### wilcoxonSignedRankTest

    public double wilcoxonSignedRankTest(double[] x,
                                double[] y,
                                boolean exactPValue)
                                  throws NullArgumentException,
                                         NoDataException,
                                         DimensionMismatchException,
                                         NumberIsTooLargeException,
                                         ConvergenceException,
                                         MaxCountExceededException

Returns the observed significance level, or p-value, associated with a Wilcoxon signed ranked statistic comparing mean for two related samples or repeated measurements on a single sample.

Let Xi denote the i'th individual of the first sample and Yi the related i'th individual in the second sample. Let Zi = Yi - Xi.

Preconditions:

- The differences Zi must be independent.
- Each Zi comes from a continuous population (they must be identical) and is symmetric about a common median.
- The values that Xi and Yi represent are ordered, so the comparisons greater than, less than, and equal to are meaningful.

Parameters:
  `x` - the first sample
  `y` - the second sample
  `exactPValue` - if the exact p-value is wanted (only works for x.length <= 30, if true and x.length > 30, this is ignored because calculations may take too long)
Returns:
  p-value
Throws:
  `NullArgumentException` - if `x` or `y` are `null`.
  `NoDataException` - if `x` or `y` are zero-length.
  `DimensionMismatchException` - if `x` and `y` do not have the same length.
  `NumberIsTooLargeException` - if `exactPValue` is `true` and `x.length` > 30
  `ConvergenceException` - if the p-value can not be computed due to a convergence error
  `MaxCountExceededException` - if the maximum number of iterations is exceeded