Package org.apache.commons.statistics.inference

Class WilcoxonSignedRankTest

java.lang.Object
org.apache.commons.statistics.inference.WilcoxonSignedRankTest
public final class WilcoxonSignedRankTest extends Object
Implements the Wilcoxon signed-rank test.
Since:
1.1
See Also:

  • Method Details

    • withDefaults

      public static WilcoxonSignedRankTest withDefaults()
      Return an instance using the default options.
      Returns:
      default instance

    • with

      public WilcoxonSignedRankTest with(AlternativeHypothesis v)
      Return an instance with the configured alternative hypothesis.
      Parameters:
      v - Value.
      Returns:
      an instance

    • with

      public WilcoxonSignedRankTest with(PValueMethod v)
      Return an instance with the configured p-value method.
      Parameters:
      v - Value.
      Returns:
      an instance
      Throws:
      IllegalArgumentException - if the value is not in the allowed options or is null

    • with

      public WilcoxonSignedRankTest with(ContinuityCorrection v)
      Return an instance with the configured continuity correction.

      If enabled, adjust the Wilcoxon rank statistic by 0.5 towards the mean value when computing the z-statistic if a normal approximation is used to compute the p-value.

      Parameters:
      v - Value.
      Returns:
      an instance

    • withMu

      public WilcoxonSignedRankTest withMu(double v)
      Return an instance with the configured expected difference mu.
      Parameters:
      v - Value.
      Returns:
      an instance
      Throws:
      IllegalArgumentException - if the value is not finite

    • statistic

      public double statistic(double[] z)
      Computes the Wilcoxon signed ranked statistic comparing the differences between sample values z = x - y to mu.

      This method handles matching samples z[i] == mu (no difference) by including them in the ranking of samples but excludes them from the test statistic (signed-rank zero procedure).

      Parameters:
      z - Signed differences between sample values.
      Returns:
      Wilcoxon positive-rank sum statistic (W+)
      Throws:
      IllegalArgumentException - if z is zero-length; contains NaN values; or all differences are equal to the expected difference
      See Also:

    • statistic

      public double statistic(double[] x, double[] y)
      Computes the Wilcoxon signed ranked statistic comparing the differences between two related samples or repeated measurements on a single sample.

      This method handles matching samples x[i] - mu == y[i] (no difference) by including them in the ranking of samples but excludes them from the test statistic (signed-rank zero procedure).

      This method is functionally equivalent to creating an array of differences z = x - y and calling statistic(z); the implementation may use an optimised method to compute the differences and rank statistic if mu != 0.

      Parameters:
      x - First sample values.
      y - Second sample values.
      Returns:
      Wilcoxon positive-rank sum statistic (W+)
      Throws:
      IllegalArgumentException - if x or y are zero-length; are not the same length; contain NaN values; or x[i] == y[i] for all data
      See Also:

    • test

      public WilcoxonSignedRankTest.Result test(double[] z)
      Performs a Wilcoxon signed ranked statistic comparing the differences between sample values z = x - y to mu.

      This method handles matching samples z[i] == mu (no difference) by including them in the ranking of samples but excludes them from the test statistic (signed-rank zero procedure).

      The test is defined by the AlternativeHypothesis.

      • 'two-sided': the distribution of the difference is not symmetric about mu.
      • 'greater': the distribution of the difference is stochastically greater than a distribution symmetric about mu.
      • 'less': the distribution of the difference is stochastically less than a distribution symmetric about mu.

      If the p-value method is auto an exact p-value is computed if the samples contain less than 50 values; otherwise a normal approximation is used.

      Computation of the exact p-value is only valid if there are no matching samples z[i] == mu and no tied ranks in the data; otherwise the p-value resorts to the asymptotic Cureton approximation using a tie correction and an optional continuity correction.

      Note: Computation of the exact p-value requires the sample size <= 1023. Exact computation requires tabulation of values not exceeding size n(n+1)/2 and computes in Order(n*n/2). Maximum memory usage is approximately 4 MiB.

      Parameters:
      z - Differences between sample values.
      Returns:
      test result
      Throws:
      IllegalArgumentException - if z is zero-length; contains NaN values; or all differences are zero
      See Also:

    • test

      public WilcoxonSignedRankTest.Result test(double[] x, double[] y)
      Performs a Wilcoxon signed ranked statistic comparing mean for two related samples or repeated measurements on a single sample.

      This method handles matching samples x[i] - mu == y[i] (no difference) by including them in the ranking of samples but excludes them from the test statistic (signed-rank zero procedure).

      This method is functionally equivalent to creating an array of differences z = x - y and calling test(z); the implementation may use an optimised method to compute the differences and rank statistic if mu != 0.

      Parameters:
      x - First sample values.
      y - Second sample values.
      Returns:
      test result
      Throws:
      IllegalArgumentException - if x or y are zero-length; are not the same length; contain NaN values; or x[i] - mu == y[i] for all data
      See Also: