Class GTest
 java.lang.Object

 org.apache.commons.math4.legacy.stat.inference.GTest

public class GTest extends Object
Implements G Test statistics.This is known in statistical genetics as the McDonaldKreitman test. The implementation handles both known and unknown distributions.
Two samples tests can be used when the distribution is unknown a priori but provided by one sample, or when the hypothesis under test is that the two samples come from the same underlying distribution.
 Since:
 3.1


Constructor Summary
Constructors Constructor Description GTest()

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description double
g(double[] expected, long[] observed)
double
gDataSetsComparison(long[] observed1, long[] observed2)
Computes a G (LogLikelihood Ratio) two sample test statistic for independence comparing frequency counts inobserved1
andobserved2
.double
gTest(double[] expected, long[] observed)
Returns the observed significance level, or pvalue, associated with a GTest for goodness of fit comparing theobserved
frequency counts to those in theexpected
array.boolean
gTest(double[] expected, long[] observed, double alpha)
Performs a GTest (LogLikelihood Ratio Test) for goodness of fit evaluating the null hypothesis that the observed counts conform to the frequency distribution described by the expected counts, with significance levelalpha
.double
gTestDataSetsComparison(long[] observed1, long[] observed2)
Returns the observed significance level, or pvalue, associated with a GValue (LogLikelihood Ratio) for two sample test comparing bin frequency counts inobserved1
andobserved2
.boolean
gTestDataSetsComparison(long[] observed1, long[] observed2, double alpha)
Performs a GTest (LogLikelihood Ratio Test) comparing two binned data sets.double
gTestIntrinsic(double[] expected, long[] observed)
Returns the intrinsic (HardyWeinberg proportions) pValue, as described in p6469 of McDonald, J.H.double
rootLogLikelihoodRatio(long k11, long k12, long k21, long k22)
Calculates the root loglikelihood ratio for 2 state Datasets.



Constructor Detail

GTest
public GTest()


Method Detail

g
public double g(double[] expected, long[] observed) throws NotPositiveException, NotStrictlyPositiveException, DimensionMismatchException
Computes the G statistic for Goodness of Fit comparingobserved
andexpected
frequency counts.This statistic can be used to perform a G test (LogLikelihood Ratio Test) evaluating the null hypothesis that the observed counts follow the expected distribution.
Preconditions:
 Expected counts must all be positive.
 Observed counts must all be ≥ 0.
 The observed and expected arrays must have the same length and their common length must be at least 2.
If any of the preconditions are not met, a
MathIllegalArgumentException
is thrown.Note:This implementation rescales the
expected
array if necessary to ensure that the sum of the expected and observed counts are equal. Parameters:
observed
 array of observed frequency countsexpected
 array of expected frequency counts Returns:
 GTest statistic
 Throws:
NotPositiveException
 ifobserved
has negative entriesNotStrictlyPositiveException
 ifexpected
has entries that are not strictly positiveDimensionMismatchException
 if the array lengths do not match or are less than 2.

gTest
public double gTest(double[] expected, long[] observed) throws NotPositiveException, NotStrictlyPositiveException, DimensionMismatchException, MaxCountExceededException
Returns the observed significance level, or pvalue, associated with a GTest for goodness of fit comparing theobserved
frequency counts to those in theexpected
array.The number returned is the smallest significance level at which one can reject the null hypothesis that the observed counts conform to the frequency distribution described by the expected counts.
The probability returned is the tail probability beyond
g(expected, observed)
in the ChiSquare distribution with degrees of freedom one less than the common length ofexpected
andobserved
.Preconditions:
 Expected counts must all be positive.
 Observed counts must all be ≥ 0.
 The observed and expected arrays must have the same length and their common length must be at least 2.
If any of the preconditions are not met, a
MathIllegalArgumentException
is thrown.Note:This implementation rescales the
expected
array if necessary to ensure that the sum of the expected and observed counts are equal. Parameters:
observed
 array of observed frequency countsexpected
 array of expected frequency counts Returns:
 pvalue
 Throws:
NotPositiveException
 ifobserved
has negative entriesNotStrictlyPositiveException
 ifexpected
has entries that are not strictly positiveDimensionMismatchException
 if the array lengths do not match or are less than 2.MaxCountExceededException
 if an error occurs computing the pvalue.

gTestIntrinsic
public double gTestIntrinsic(double[] expected, long[] observed) throws NotPositiveException, NotStrictlyPositiveException, DimensionMismatchException, MaxCountExceededException
Returns the intrinsic (HardyWeinberg proportions) pValue, as described in p6469 of McDonald, J.H. 2009. Handbook of Biological Statistics (2nd ed.). Sparky House Publishing, Baltimore, Maryland.The probability returned is the tail probability beyond
g(expected, observed)
in the ChiSquare distribution with degrees of freedom two less than the common length ofexpected
andobserved
. Parameters:
observed
 array of observed frequency countsexpected
 array of expected frequency counts Returns:
 pvalue
 Throws:
NotPositiveException
 ifobserved
has negative entriesNotStrictlyPositiveException
expected
has entries that are not strictly positiveDimensionMismatchException
 if the array lengths do not match or are less than 2.MaxCountExceededException
 if an error occurs computing the pvalue.

gTest
public boolean gTest(double[] expected, long[] observed, double alpha) throws NotPositiveException, NotStrictlyPositiveException, DimensionMismatchException, OutOfRangeException, MaxCountExceededException
Performs a GTest (LogLikelihood Ratio Test) for goodness of fit evaluating the null hypothesis that the observed counts conform to the frequency distribution described by the expected counts, with significance levelalpha
. Returns true iff the null hypothesis can be rejected with100 * (1  alpha)
percent confidence.Example:
To test the hypothesis thatobserved
followsexpected
at the 99% level, usegTest(expected, observed, 0.01)
Returns true iff
gTestGoodnessOfFitPValue(expected, observed)
< alphaPreconditions:
 Expected counts must all be positive.
 Observed counts must all be ≥ 0.
 The observed and expected arrays must have the same length and their common length must be at least 2.

0 < alpha < 0.5
If any of the preconditions are not met, a
MathIllegalArgumentException
is thrown.Note:This implementation rescales the
expected
array if necessary to ensure that the sum of the expected and observed counts are equal. Parameters:
observed
 array of observed frequency countsexpected
 array of expected frequency countsalpha
 significance level of the test Returns:
 true iff null hypothesis can be rejected with confidence 1  alpha
 Throws:
NotPositiveException
 ifobserved
has negative entriesNotStrictlyPositiveException
 ifexpected
has entries that are not strictly positiveDimensionMismatchException
 if the array lengths do not match or are less than 2.MaxCountExceededException
 if an error occurs computing the pvalue.OutOfRangeException
 if alpha is not strictly greater than zero and less than or equal to 0.5

gDataSetsComparison
public double gDataSetsComparison(long[] observed1, long[] observed2) throws DimensionMismatchException, NotPositiveException, ZeroException
Computes a G (LogLikelihood Ratio) two sample test statistic for independence comparing frequency counts in
observed1
andobserved2
. The sums of frequency counts in the two samples are not required to be the same. The formula used to compute the test statistic is2 * totalSum * [H(rowSums) + H(colSums)  H(k)]
where
H
is the Shannon Entropy of the random variable formed by viewing the elements of the argument array as incidence counts;
k
is a matrix with rows[observed1, observed2]
;
rowSums, colSums
are the row/col sums ofk
;
andtotalSum
is the overall sum of all entries ink
.This statistic can be used to perform a G test evaluating the null hypothesis that both observed counts are independent
Preconditions:
 Observed counts must be nonnegative.
 Observed counts for a specific bin must not both be zero.
 Observed counts for a specific sample must not all be 0.
 The arrays
observed1
andobserved2
must have the same length and their common length must be at least 2.
If any of the preconditions are not met, a
MathIllegalArgumentException
is thrown. Parameters:
observed1
 array of observed frequency counts of the first data setobserved2
 array of observed frequency counts of the second data set Returns:
 GTest statistic
 Throws:
DimensionMismatchException
 the lengths of the arrays do not match or their common length is less than 2NotPositiveException
 if any entry inobserved1
orobserved2
is negativeZeroException
 if either all counts ofobserved1
orobserved2
are zero, or if the count at the same index is zero for both arrays.

rootLogLikelihoodRatio
public double rootLogLikelihoodRatio(long k11, long k12, long k21, long k22)
Calculates the root loglikelihood ratio for 2 state Datasets. SeegDataSetsComparison(long[], long[] )
.Given two events A and B, let k11 be the number of times both events occur, k12 the incidence of B without A, k21 the count of A without B, and k22 the number of times neither A nor B occurs. What is returned by this method is
(sgn) sqrt(gValueDataSetsComparison({k11, k12}, {k21, k22})
where
sgn
is 1 ifk11 / (k11 + k12) < k21 / (k21 + k22))
;
1 otherwise.Signed root LLR has two advantages over the basic LLR: a) it is positive where k11 is bigger than expected, negative where it is lower b) if there is no difference it is asymptotically normally distributed. This allows one to talk about "number of standard deviations" which is a more common frame of reference than the chi^2 distribution.
 Parameters:
k11
 number of times the two events occurred together (AB)k12
 number of times the second event occurred WITHOUT the first event (notA,B)k21
 number of times the first event occurred WITHOUT the second event (A, notB)k22
 number of times something else occurred (i.e. was neither of these events (notA, notB) Returns:
 root loglikelihood ratio

gTestDataSetsComparison
public double gTestDataSetsComparison(long[] observed1, long[] observed2) throws DimensionMismatchException, NotPositiveException, ZeroException, MaxCountExceededException
Returns the observed significance level, or pvalue, associated with a GValue (LogLikelihood Ratio) for two sample test comparing bin frequency counts in
observed1
andobserved2
.The number returned is the smallest significance level at which one can reject the null hypothesis that the observed counts conform to the same distribution.
See
gTest(double[], long[])
for details on how the pvalue is computed. The degrees of of freedom used to perform the test is one less than the common length of the input observed count arrays.Preconditions:
 Observed counts must be nonnegative.
 Observed counts for a specific bin must not both be zero.
 Observed counts for a specific sample must not all be 0.
 The arrays
observed1
andobserved2
must have the same length and their common length must be at least 2.
If any of the preconditions are not met, a
MathIllegalArgumentException
is thrown. Parameters:
observed1
 array of observed frequency counts of the first data setobserved2
 array of observed frequency counts of the second data set Returns:
 pvalue
 Throws:
DimensionMismatchException
 the length of the arrays does not match or their common length is less than 2NotPositiveException
 if any of the entries inobserved1
orobserved2
are negativeZeroException
 if either all counts ofobserved1
orobserved2
are zero, or if the count at some index is zero for both arraysMaxCountExceededException
 if an error occurs computing the pvalue.

gTestDataSetsComparison
public boolean gTestDataSetsComparison(long[] observed1, long[] observed2, double alpha) throws DimensionMismatchException, NotPositiveException, ZeroException, OutOfRangeException, MaxCountExceededException
Performs a GTest (LogLikelihood Ratio Test) comparing two binned data sets. The test evaluates the null hypothesis that the two lists of observed counts conform to the same frequency distribution, with significance level
alpha
. Returns true iff the null hypothesis can be rejected with 100 * (1  alpha) percent confidence.See
Preconditions:gDataSetsComparison(long[], long[])
for details on the formula used to compute the G (LLR) statistic used in the test andgTest(double[], long[])
for information on how the observed significance level is computed. The degrees of of freedom used to perform the test is one less than the common length of the input observed count arrays. Observed counts must be nonnegative.
 Observed counts for a specific bin must not both be zero.
 Observed counts for a specific sample must not all be 0.
 The arrays
observed1
andobserved2
must have the same length and their common length must be at least 2. 0 < alpha < 0.5
If any of the preconditions are not met, a
MathIllegalArgumentException
is thrown. Parameters:
observed1
 array of observed frequency counts of the first data setobserved2
 array of observed frequency counts of the second data setalpha
 significance level of the test Returns:
 true iff null hypothesis can be rejected with confidence 1  alpha
 Throws:
DimensionMismatchException
 the length of the arrays does not matchNotPositiveException
 if any of the entries inobserved1
orobserved2
are negativeZeroException
 if either all counts ofobserved1
orobserved2
are zero, or if the count at some index is zero for both arraysOutOfRangeException
 ifalpha
is not in the range (0, 0.5]MaxCountExceededException
 if an error occurs performing the test

