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:

Wilcoxon signed-rank test (Wikipedia)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	WilcoxonSignedRankTest.Result	Result for the Wilcoxon signed-rank test.

Method Summary

Modifier and Type	Method	Description
double	statistic(double[] z)	Computes the Wilcoxon signed ranked statistic comparing the differences between sample values z = x - y to mu.
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.
WilcoxonSignedRankTest.Result	test(double[] z)	Performs a Wilcoxon signed ranked statistic comparing the differences between sample values z = x - y to mu.
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.
WilcoxonSignedRankTest	with(AlternativeHypothesis v)	Return an instance with the configured alternative hypothesis.
WilcoxonSignedRankTest	with(ContinuityCorrection v)	Return an instance with the configured continuity correction.
WilcoxonSignedRankTest	with(PValueMethod v)	Return an instance with the configured p-value method.
static WilcoxonSignedRankTest	withDefaults()	Return an instance using the default options.
WilcoxonSignedRankTest	withMu(double v)	Return an instance with the configured expected difference mu.

Methods inherited from class java.lang.Object

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

Method Detail

withDefaults

public static WilcoxonSignedRankTest withDefaults()

Return an instance using the default options.

• AlternativeHypothesis.TWO_SIDED
• PValueMethod.AUTO
• ContinuityCorrection.ENABLED
• mu = 0

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:

withMu(double)

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:

withMu(double)

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:

withMu(double), with(AlternativeHypothesis), with(ContinuityCorrection)

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:

statistic(double[], double[]), test(double[])