Class WilcoxonSignedRankTest
- Since:
- 1.1
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Result for the Wilcoxon signed-rank test. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final AlternativeHypothesis
Alternative hypothesis.private static final int
Limit on sample size for the exact p-value computation for the auto mode.private final boolean
Perform continuity correction.private static final WilcoxonSignedRankTest
Default instance.private static final int
Limit on sample size for the exact p-value computation.private final double
Expected location shift.private final PValueMethod
Method to compute the p-value.private static final RankingAlgorithm
Ranking instance. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
WilcoxonSignedRankTest
(AlternativeHypothesis alternative, PValueMethod method, boolean continuityCorrection, double mu) -
Method Summary
Modifier and TypeMethodDescriptionprivate static double[]
calculateAbsoluteDifferences
(double[] z) Calculates |z[i]| for all i.private static double
calculateAsymptoticPValue
(double wPlus, int n, double z, double c, AlternativeHypothesis alternative, boolean continuityCorrection) Compute the asymptotic p-value using the Cureton normal approximation.private static double[]
calculateDifferences
(double mu, double[] x, double[] y) Calculates x[i] - mu - y[i] for all i.private static double
calculateExactPValue
(int w1, int n, AlternativeHypothesis alternative) Compute the exact p-value.(package private) static double
calculateTieCorrection
(double[] ranks) Calculate the tie correction.private static double
calculateW
(double[] obs, double[] ranks) Calculate the Wilcoxon positive-rank sum statistic.private static double
cdf
(int w1, int w2, int n) Compute the cumulative density function of the Wilcoxon signed rank W+ statistic.private static void
checkSamples
(double[] x, double[] y) Ensures that the provided arrays fulfil the assumptions.private static double
computeCdf
(int t, int n) Compute the cumulative density function for the distribution of the Wilcoxon signed rank statistic.private static double
computeStatistic
(double[] z, double mu) Computes the Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.private WilcoxonSignedRankTest.Result
computeTest
(double[] z, double expectedMu) Performs a Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.private static int
countZeros
(double[] z) Count the number of zeros in the data.private static PValueMethod
selectMethod
(PValueMethod method, int n) Select the method to compute the p-value.private static double
sf
(int w1, int w2, int n) Compute the survival function of the Wilcoxon signed rank W+ statistic.double
statistic
(double[] z) Computes the Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.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.test
(double[] z) Performs a Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.test
(double[] x, double[] y) Performs a Wilcoxon signed ranked statistic comparing mean for two related samples or repeated measurements on a single sample.Return an instance with the configured alternative hypothesis.Return an instance with the configured continuity correction.with
(PValueMethod v) Return an instance with the configured p-value method.static WilcoxonSignedRankTest
Return an instance using the default options.withMu
(double v) Return an instance with the configured expected differencemu
.
-
Field Details
-
EXACT_LIMIT
private static final int EXACT_LIMITLimit on sample size for the exact p-value computation.- See Also:
-
AUTO_LIMIT
private static final int AUTO_LIMITLimit on sample size for the exact p-value computation for the auto mode.- See Also:
-
RANKING
Ranking instance. -
DEFAULT
Default instance. -
alternative
Alternative hypothesis. -
pValueMethod
Method to compute the p-value. -
continuityCorrection
private final boolean continuityCorrectionPerform continuity correction. -
mu
private final double muExpected location shift.
-
-
Constructor Details
-
WilcoxonSignedRankTest
private WilcoxonSignedRankTest(AlternativeHypothesis alternative, PValueMethod method, boolean continuityCorrection, double mu) - Parameters:
alternative
- Alternative hypothesis.method
- P-value method.continuityCorrection
- true to perform continuity correction.mu
- Expected location shift.
-
-
Method Details
-
withDefaults
Return an instance using the default options.- Returns:
- default instance
-
with
Return an instance with the configured alternative hypothesis.- Parameters:
v
- Value.- Returns:
- an instance
-
with
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
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
Return an instance with the configured expected differencemu
.- 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 valuesz = x - y
tomu
.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
- ifz
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 callingstatistic(z)
; the implementation may use an optimised method to compute the differences and rank statistic ifmu != 0
.- Parameters:
x
- First sample values.y
- Second sample values.- Returns:
- Wilcoxon positive-rank sum statistic (W+)
- Throws:
IllegalArgumentException
- ifx
ory
are zero-length; are not the same length; contain NaN values; orx[i] == y[i]
for all data- See Also:
-
test
Performs a Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.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 sizen(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
- ifz
is zero-length; contains NaN values; or all differences are zero- See Also:
- 'two-sided': the distribution of the difference is not symmetric about
-
test
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 callingtest(z)
; the implementation may use an optimised method to compute the differences and rank statistic ifmu != 0
.- Parameters:
x
- First sample values.y
- Second sample values.- Returns:
- test result
- Throws:
IllegalArgumentException
- ifx
ory
are zero-length; are not the same length; contain NaN values; orx[i] - mu == y[i]
for all data- See Also:
-
computeStatistic
private static double computeStatistic(double[] z, double mu) Computes the Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.- Parameters:
z
- Signed differences between sample values.mu
- Expected difference.- Returns:
- Wilcoxon positive-rank sum statistic (W+)
- Throws:
IllegalArgumentException
- ifz
is zero-length; contains NaN values; or all differences are equal to the expected difference- See Also:
-
computeTest
Performs a Wilcoxon signed ranked statistic comparing the differences between sample valuesz = x - y
tomu
.- Parameters:
z
- Differences between sample values.expectedMu
- Expected difference.- Returns:
- test result
- Throws:
IllegalArgumentException
- ifz
is zero-length; contains NaN values; or all differences are zero
-
checkSamples
private static void checkSamples(double[] x, double[] y) Ensures that the provided arrays fulfil the assumptions.- Parameters:
x
- First sample.y
- Second sample.- Throws:
IllegalArgumentException
- ifx
ory
are zero-length; or do not have the same length
-
calculateDifferences
private static double[] calculateDifferences(double mu, double[] x, double[] y) Calculates x[i] - mu - y[i] for all i.- Parameters:
mu
- Expected difference.x
- First sample.y
- Second sample.- Returns:
- z = x - y
-
calculateAbsoluteDifferences
private static double[] calculateAbsoluteDifferences(double[] z) Calculates |z[i]| for all i.- Parameters:
z
- Sample.- Returns:
- |z|
-
calculateW
private static double calculateW(double[] obs, double[] ranks) Calculate the Wilcoxon positive-rank sum statistic.- Parameters:
obs
- Observed signed value.ranks
- Ranks (including averages for ties).- Returns:
- Wilcoxon positive-rank sum statistic (W+)
-
countZeros
private static int countZeros(double[] z) Count the number of zeros in the data.- Parameters:
z
- Input data.- Returns:
- the zero count
- Throws:
IllegalArgumentException
- if the data is all zeros
-
calculateTieCorrection
static double calculateTieCorrection(double[] ranks) Calculate the tie correction. Destructively modifies ranks (by sorting).c = sum(t^3 - t)
where t is the size of each group of tied observations.
- Parameters:
ranks
- Ranks- Returns:
- the tie correction
-
selectMethod
Select the method to compute the p-value.- Parameters:
method
- P-value method.n
- Size of the data.- Returns:
- p-value method.
-
calculateAsymptoticPValue
private static double calculateAsymptoticPValue(double wPlus, int n, double z, double c, AlternativeHypothesis alternative, boolean continuityCorrection) Compute the asymptotic p-value using the Cureton normal approximation. This corrects for zeros in the signed-rank zero procedure and/or ties corrected using the average method.- Parameters:
wPlus
- Wilcoxon signed rank value (W+).n
- Number of subjects.z
- Count of number of zerosc
- Tie-correctionalternative
- Alternative hypothesis.continuityCorrection
- true to use a continuity correction.- Returns:
- two-sided asymptotic p-value
-
calculateExactPValue
Compute the exact p-value.This computation requires that no zeros or ties are found in the data. The input value n is limited to 1023.
- Parameters:
w1
- Wilcoxon signed rank value (W+, or W-).n
- Number of subjects.alternative
- Alternative hypothesis.- Returns:
- exact p-value (two-sided, greater, or less using the options)
-
cdf
private static double cdf(int w1, int w2, int n) Compute the cumulative density function of the Wilcoxon signed rank W+ statistic. The W- statistic is passed for convenience to exploit symmetry in the distribution.- Parameters:
w1
- Wilcoxon W+ statisticw2
- Wilcoxon W- statisticn
- Number of subjects.- Returns:
Pr(X <= k)
-
sf
private static double sf(int w1, int w2, int n) Compute the survival function of the Wilcoxon signed rank W+ statistic. The W- statistic is passed for convenience to exploit symmetry in the distribution.- Parameters:
w1
- Wilcoxon W+ statisticw2
- Wilcoxon W- statisticn
- Number of subjects.- Returns:
Pr(X <= k)
-
computeCdf
private static double computeCdf(int t, int n) Compute the cumulative density function for the distribution of the Wilcoxon signed rank statistic. This is a discrete distribution and is only valid when no zeros or ties are found in the data.This should be called with the lower of W+ or W- for computational efficiency. The input value n is limited to 1023.
Uses recursion to compute the density for
X <= t
and sums the values. See: https://en.wikipedia.org/wiki/Wilcoxon_signed-rank_test#Computing_the_null_distribution- Parameters:
t
- Smallest Wilcoxon signed rank value (W+, or W-).n
- Number of subjects.- Returns:
Pr(T <= t)
-