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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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

Copyright (c) 2003-2013 Apache Software Foundation