Class GTest
This is known in statistical genetics as the McDonald-Kreitman 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.
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptiondouble
g
(double[] expected, long[] observed) double
gDataSetsComparison
(long[] observed1, long[] observed2) Computes a G (Log-Likelihood Ratio) two sample test statistic for independence comparing frequency counts inobserved1
andobserved2
.double
gTest
(double[] expected, long[] observed) Returns the observed significance level, or p-value, associated with a G-Test for goodness of fit comparing theobserved
frequency counts to those in theexpected
array.boolean
gTest
(double[] expected, long[] observed, double alpha) Performs a G-Test (Log-Likelihood 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 p-value, associated with a G-Value (Log-Likelihood Ratio) for two sample test comparing bin frequency counts inobserved1
andobserved2
.boolean
gTestDataSetsComparison
(long[] observed1, long[] observed2, double alpha) Performs a G-Test (Log-Likelihood Ratio Test) comparing two binned data sets.double
gTestIntrinsic
(double[] expected, long[] observed) Returns the intrinsic (Hardy-Weinberg proportions) p-Value, as described in p64-69 of McDonald, J.H.double
rootLogLikelihoodRatio
(long k11, long k12, long k21, long k22) Calculates the root log-likelihood ratio for 2 state Datasets.
-
Constructor Details
-
GTest
public GTest()Empty constructor.This constructor is not strictly necessary, but it prevents spurious javadoc warnings with JDK 18 and later.
- Since:
- 3.0
-
-
Method Details
-
g
Computes the G statistic for Goodness of Fit comparingobserved
andexpected
frequency counts.This statistic can be used to perform a G test (Log-Likelihood 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:
- G-Test statistic
- Throws:
MathIllegalArgumentException
- ifobserved
has negative entriesMathIllegalArgumentException
- ifexpected
has entries that are not strictly positiveMathIllegalArgumentException
- if the array lengths do not match or are less than 2.
-
gTest
public double gTest(double[] expected, long[] observed) throws MathIllegalArgumentException, MathIllegalStateException Returns the observed significance level, or p-value, associated with a G-Test 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:
- p-value
- Throws:
MathIllegalArgumentException
- ifobserved
has negative entriesMathIllegalArgumentException
- ifexpected
has entries that are not strictly positiveMathIllegalArgumentException
- if the array lengths do not match or are less than 2.MathIllegalStateException
- if an error occurs computing the p-value.
-
gTestIntrinsic
public double gTestIntrinsic(double[] expected, long[] observed) throws MathIllegalArgumentException, MathIllegalStateException Returns the intrinsic (Hardy-Weinberg proportions) p-Value, as described in p64-69 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:
- p-value
- Throws:
MathIllegalArgumentException
- ifobserved
has negative entriesMathIllegalArgumentException
-expected
has entries that are not strictly positiveMathIllegalArgumentException
- if the array lengths do not match or are less than 2.MathIllegalStateException
- if an error occurs computing the p-value.
-
gTest
public boolean gTest(double[] expected, long[] observed, double alpha) throws MathIllegalArgumentException, MathIllegalStateException Performs a G-Test (Log-Likelihood 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:
MathIllegalArgumentException
- ifobserved
has negative entriesMathIllegalArgumentException
- ifexpected
has entries that are not strictly positiveMathIllegalArgumentException
- if the array lengths do not match or are less than 2.MathIllegalStateException
- if an error occurs computing the p-value.MathIllegalArgumentException
- 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 MathIllegalArgumentException Computes a G (Log-Likelihood 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 non-negative.
- 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:
- G-Test statistic
- Throws:
MathIllegalArgumentException
- the the lengths of the arrays do not match or their common length is less than 2MathIllegalArgumentException
- if any entry inobserved1
orobserved2
is negativeMathIllegalArgumentException
- 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 log-likelihood 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 log-likelihood ratio
-
gTestDataSetsComparison
public double gTestDataSetsComparison(long[] observed1, long[] observed2) throws MathIllegalArgumentException, MathIllegalStateException Returns the observed significance level, or p-value, associated with a G-Value (Log-Likelihood 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 p-value 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 non-negative.
- 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:
- p-value
- Throws:
MathIllegalArgumentException
- the the length of the arrays does not match or their common length is less than 2MathIllegalArgumentException
- if any of the entries inobserved1
orobserved2
are negativeMathIllegalArgumentException
- if either all counts ofobserved1
orobserved2
are zero, or if the count at some index is zero for both arraysMathIllegalStateException
- if an error occurs computing the p-value.
-
gTestDataSetsComparison
public boolean gTestDataSetsComparison(long[] observed1, long[] observed2, double alpha) throws MathIllegalArgumentException, MathIllegalStateException Performs a G-Test (Log-Likelihood 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
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.Preconditions:
- Observed counts must be non-negative.
- 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:
MathIllegalArgumentException
- the the length of the arrays does not matchMathIllegalArgumentException
- if any of the entries inobserved1
orobserved2
are negativeMathIllegalArgumentException
- if either all counts ofobserved1
orobserved2
are zero, or if the count at some index is zero for both arraysMathIllegalArgumentException
- ifalpha
is not in the range (0, 0.5]MathIllegalStateException
- if an error occurs performing the test
-