GTest.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.math4.legacy.stat.inference;

  18. import org.apache.commons.statistics.distribution.ChiSquaredDistribution;
  19. import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
  20. import org.apache.commons.math4.legacy.exception.MaxCountExceededException;
  21. import org.apache.commons.math4.legacy.exception.NotPositiveException;
  22. import org.apache.commons.math4.legacy.exception.NotStrictlyPositiveException;
  23. import org.apache.commons.math4.legacy.exception.OutOfRangeException;
  24. import org.apache.commons.math4.legacy.exception.ZeroException;
  25. import org.apache.commons.math4.legacy.exception.util.LocalizedFormats;
  26. import org.apache.commons.math4.core.jdkmath.JdkMath;
  27. import org.apache.commons.math4.legacy.core.MathArrays;

  28. /**
  29.  * Implements <a href="http://en.wikipedia.org/wiki/G-test">G Test</a>
  30.  * statistics.
  31.  *
  32.  * <p>This is known in statistical genetics as the McDonald-Kreitman test.
  33.  * The implementation handles both known and unknown distributions.</p>
  34.  *
  35.  * <p>Two samples tests can be used when the distribution is unknown <i>a priori</i>
  36.  * but provided by one sample, or when the hypothesis under test is that the two
  37.  * samples come from the same underlying distribution.</p>
  38.  *
  39.  * @since 3.1
  40.  */
  41. public class GTest {

  42.     /**
  43.      * Computes the <a href="http://en.wikipedia.org/wiki/G-test">G statistic
  44.      * for Goodness of Fit</a> comparing {@code observed} and {@code expected}
  45.      * frequency counts.
  46.      *
  47.      * <p>This statistic can be used to perform a G test (Log-Likelihood Ratio
  48.      * Test) evaluating the null hypothesis that the observed counts follow the
  49.      * expected distribution.</p>
  50.      *
  51.      * <p><strong>Preconditions</strong>: <ul>
  52.      * <li>Expected counts must all be positive. </li>
  53.      * <li>Observed counts must all be &ge; 0. </li>
  54.      * <li>The observed and expected arrays must have the same length and their
  55.      * common length must be at least 2. </li></ul>
  56.      *
  57.      * <p>If any of the preconditions are not met, a
  58.      * {@code MathIllegalArgumentException} is thrown.</p>
  59.      *
  60.      * <p><strong>Note:</strong>This implementation rescales the
  61.      * {@code expected} array if necessary to ensure that the sum of the
  62.      * expected and observed counts are equal.</p>
  63.      *
  64.      * @param observed array of observed frequency counts
  65.      * @param expected array of expected frequency counts
  66.      * @return G-Test statistic
  67.      * @throws NotPositiveException if {@code observed} has negative entries
  68.      * @throws NotStrictlyPositiveException if {@code expected} has entries that
  69.      * are not strictly positive
  70.      * @throws DimensionMismatchException if the array lengths do not match or
  71.      * are less than 2.
  72.      */
  73.     public double g(final double[] expected, final long[] observed)
  74.             throws NotPositiveException, NotStrictlyPositiveException,
  75.             DimensionMismatchException {

  76.         if (expected.length < 2) {
  77.             throw new DimensionMismatchException(expected.length, 2);
  78.         }
  79.         if (expected.length != observed.length) {
  80.             throw new DimensionMismatchException(expected.length, observed.length);
  81.         }
  82.         MathArrays.checkPositive(expected);
  83.         MathArrays.checkNonNegative(observed);

  84.         double sumExpected = 0d;
  85.         double sumObserved = 0d;
  86.         for (int i = 0; i < observed.length; i++) {
  87.             sumExpected += expected[i];
  88.             sumObserved += observed[i];
  89.         }
  90.         double ratio = 1d;
  91.         boolean rescale = false;
  92.         if (JdkMath.abs(sumExpected - sumObserved) > 10E-6) {
  93.             ratio = sumObserved / sumExpected;
  94.             rescale = true;
  95.         }
  96.         double sum = 0d;
  97.         for (int i = 0; i < observed.length; i++) {
  98.             final double dev = rescale ?
  99.                     JdkMath.log((double) observed[i] / (ratio * expected[i])) :
  100.                         JdkMath.log((double) observed[i] / expected[i]);
  101.             sum += ((double) observed[i]) * dev;
  102.         }
  103.         return 2d * sum;
  104.     }

  105.     /**
  106.      * Returns the <i>observed significance level</i>, or <a href=
  107.      * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue"> p-value</a>,
  108.      * associated with a G-Test for goodness of fit comparing the
  109.      * {@code observed} frequency counts to those in the {@code expected} array.
  110.      *
  111.      * <p>The number returned is the smallest significance level at which one
  112.      * can reject the null hypothesis that the observed counts conform to the
  113.      * frequency distribution described by the expected counts.</p>
  114.      *
  115.      * <p>The probability returned is the tail probability beyond
  116.      * {@link #g(double[], long[]) g(expected, observed)}
  117.      * in the ChiSquare distribution with degrees of freedom one less than the
  118.      * common length of {@code expected} and {@code observed}.</p>
  119.      *
  120.      * <p> <strong>Preconditions</strong>: <ul>
  121.      * <li>Expected counts must all be positive. </li>
  122.      * <li>Observed counts must all be &ge; 0. </li>
  123.      * <li>The observed and expected arrays must have the
  124.      * same length and their common length must be at least 2.</li>
  125.      * </ul>
  126.      *
  127.      * <p>If any of the preconditions are not met, a
  128.      * {@code MathIllegalArgumentException} is thrown.</p>
  129.      *
  130.      * <p><strong>Note:</strong>This implementation rescales the
  131.      * {@code expected} array if necessary to ensure that the sum of the
  132.      *  expected and observed counts are equal.</p>
  133.      *
  134.      * @param observed array of observed frequency counts
  135.      * @param expected array of expected frequency counts
  136.      * @return p-value
  137.      * @throws NotPositiveException if {@code observed} has negative entries
  138.      * @throws NotStrictlyPositiveException if {@code expected} has entries that
  139.      * are not strictly positive
  140.      * @throws DimensionMismatchException if the array lengths do not match or
  141.      * are less than 2.
  142.      * @throws MaxCountExceededException if an error occurs computing the
  143.      * p-value.
  144.      */
  145.     public double gTest(final double[] expected, final long[] observed)
  146.             throws NotPositiveException, NotStrictlyPositiveException,
  147.             DimensionMismatchException, MaxCountExceededException {

  148.         // pass a null rng to avoid unneeded overhead as we will not sample from this distribution
  149.         final ChiSquaredDistribution distribution =
  150.                 ChiSquaredDistribution.of(expected.length - 1.0);
  151.         return distribution.survivalProbability(g(expected, observed));
  152.     }

  153.     /**
  154.      * Returns the intrinsic (Hardy-Weinberg proportions) p-Value, as described
  155.      * in p64-69 of McDonald, J.H. 2009. Handbook of Biological Statistics
  156.      * (2nd ed.). Sparky House Publishing, Baltimore, Maryland.
  157.      *
  158.      * <p> The probability returned is the tail probability beyond
  159.      * {@link #g(double[], long[]) g(expected, observed)}
  160.      * in the ChiSquare distribution with degrees of freedom two less than the
  161.      * common length of {@code expected} and {@code observed}.</p>
  162.      *
  163.      * @param observed array of observed frequency counts
  164.      * @param expected array of expected frequency counts
  165.      * @return p-value
  166.      * @throws NotPositiveException if {@code observed} has negative entries
  167.      * @throws NotStrictlyPositiveException {@code expected} has entries that are
  168.      * not strictly positive
  169.      * @throws DimensionMismatchException if the array lengths do not match or
  170.      * are less than 2.
  171.      * @throws MaxCountExceededException if an error occurs computing the
  172.      * p-value.
  173.      */
  174.     public double gTestIntrinsic(final double[] expected, final long[] observed)
  175.             throws NotPositiveException, NotStrictlyPositiveException,
  176.             DimensionMismatchException, MaxCountExceededException {

  177.         // pass a null rng to avoid unneeded overhead as we will not sample from this distribution
  178.         final ChiSquaredDistribution distribution =
  179.                 ChiSquaredDistribution.of(expected.length - 2.0);
  180.         return distribution.survivalProbability(g(expected, observed));
  181.     }

  182.     /**
  183.      * Performs a G-Test (Log-Likelihood Ratio Test) for goodness of fit
  184.      * evaluating the null hypothesis that the observed counts conform to the
  185.      * frequency distribution described by the expected counts, with
  186.      * significance level {@code alpha}. Returns true iff the null
  187.      * hypothesis can be rejected with {@code 100 * (1 - alpha)} percent confidence.
  188.      *
  189.      * <p><strong>Example:</strong><br> To test the hypothesis that
  190.      * {@code observed} follows {@code expected} at the 99% level,
  191.      * use </p><p>
  192.      * {@code gTest(expected, observed, 0.01)}</p>
  193.      *
  194.      * <p>Returns true iff {@link #gTest(double[], long[])
  195.      *  gTestGoodnessOfFitPValue(expected, observed)} &lt; alpha</p>
  196.      *
  197.      * <p><strong>Preconditions</strong>: <ul>
  198.      * <li>Expected counts must all be positive. </li>
  199.      * <li>Observed counts must all be &ge; 0. </li>
  200.      * <li>The observed and expected arrays must have the same length and their
  201.      * common length must be at least 2.
  202.      * <li> {@code 0 < alpha < 0.5} </li></ul>
  203.      *
  204.      * <p>If any of the preconditions are not met, a
  205.      * {@code MathIllegalArgumentException} is thrown.</p>
  206.      *
  207.      * <p><strong>Note:</strong>This implementation rescales the
  208.      * {@code expected} array if necessary to ensure that the sum of the
  209.      * expected and observed counts are equal.</p>
  210.      *
  211.      * @param observed array of observed frequency counts
  212.      * @param expected array of expected frequency counts
  213.      * @param alpha significance level of the test
  214.      * @return true iff null hypothesis can be rejected with confidence 1 -
  215.      * alpha
  216.      * @throws NotPositiveException if {@code observed} has negative entries
  217.      * @throws NotStrictlyPositiveException if {@code expected} has entries that
  218.      * are not strictly positive
  219.      * @throws DimensionMismatchException if the array lengths do not match or
  220.      * are less than 2.
  221.      * @throws MaxCountExceededException if an error occurs computing the
  222.      * p-value.
  223.      * @throws OutOfRangeException if alpha is not strictly greater than zero
  224.      * and less than or equal to 0.5
  225.      */
  226.     public boolean gTest(final double[] expected, final long[] observed,
  227.             final double alpha)
  228.             throws NotPositiveException, NotStrictlyPositiveException,
  229.             DimensionMismatchException, OutOfRangeException, MaxCountExceededException {

  230.         if (alpha <= 0 || alpha > 0.5) {
  231.             throw new OutOfRangeException(LocalizedFormats.OUT_OF_BOUND_SIGNIFICANCE_LEVEL,
  232.                     alpha, 0, 0.5);
  233.         }
  234.         return gTest(expected, observed) < alpha;
  235.     }

  236.     /**
  237.      * Calculates the <a href=
  238.      * "http://en.wikipedia.org/wiki/Entropy_%28information_theory%29">Shannon
  239.      * entropy</a> for 2 Dimensional Matrix.  The value returned is the entropy
  240.      * of the vector formed by concatenating the rows (or columns) of {@code k}
  241.      * to form a vector. See {@link #entropy(long[])}.
  242.      *
  243.      * @param k 2 Dimensional Matrix of long values (for ex. the counts of a
  244.      * trials)
  245.      * @return Shannon Entropy of the given Matrix
  246.      *
  247.      */
  248.     private double entropy(final long[][] k) {
  249.         double h = 0d;
  250.         double sumK = 0d;
  251.         for (int i = 0; i < k.length; i++) {
  252.             for (int j = 0; j < k[i].length; j++) {
  253.                 sumK += (double) k[i][j];
  254.             }
  255.         }
  256.         for (int i = 0; i < k.length; i++) {
  257.             for (int j = 0; j < k[i].length; j++) {
  258.                 if (k[i][j] != 0) {
  259.                     final double pIJ = (double) k[i][j] / sumK;
  260.                     h += pIJ * JdkMath.log(pIJ);
  261.                 }
  262.             }
  263.         }
  264.         return -h;
  265.     }

  266.     /**
  267.      * Calculates the <a href="http://en.wikipedia.org/wiki/Entropy_%28information_theory%29">
  268.      * Shannon entropy</a> for a vector.  The values of {@code k} are taken to be
  269.      * incidence counts of the values of a random variable. What is returned is <br>
  270.      * &sum;p<sub>i</sub>log(p<sub>i</sub><br>
  271.      * where p<sub>i</sub> = k[i] / (sum of elements in k)
  272.      *
  273.      * @param k Vector (for ex. Row Sums of a trials)
  274.      * @return Shannon Entropy of the given Vector
  275.      *
  276.      */
  277.     private double entropy(final long[] k) {
  278.         double h = 0d;
  279.         double sumK = 0d;
  280.         for (int i = 0; i < k.length; i++) {
  281.             sumK += (double) k[i];
  282.         }
  283.         for (int i = 0; i < k.length; i++) {
  284.             if (k[i] != 0) {
  285.                 final double pI = (double) k[i] / sumK;
  286.                 h += pI * JdkMath.log(pI);
  287.             }
  288.         }
  289.         return -h;
  290.     }

  291.     /**
  292.      * <p>Computes a G (Log-Likelihood Ratio) two sample test statistic for
  293.      * independence comparing frequency counts in
  294.      * {@code observed1} and {@code observed2}. The sums of frequency
  295.      * counts in the two samples are not required to be the same. The formula
  296.      * used to compute the test statistic is </p>
  297.      *
  298.      * <p>{@code 2 * totalSum * [H(rowSums) + H(colSums) - H(k)]}</p>
  299.      *
  300.      * <p> where {@code H} is the
  301.      * <a href="http://en.wikipedia.org/wiki/Entropy_%28information_theory%29">
  302.      * Shannon Entropy</a> of the random variable formed by viewing the elements
  303.      * of the argument array as incidence counts; <br>
  304.      * {@code k} is a matrix with rows {@code [observed1, observed2]}; <br>
  305.      * {@code rowSums, colSums} are the row/col sums of {@code k}; <br>
  306.      * and {@code totalSum} is the overall sum of all entries in {@code k}.</p>
  307.      *
  308.      * <p>This statistic can be used to perform a G test evaluating the null
  309.      * hypothesis that both observed counts are independent </p>
  310.      *
  311.      * <p> <strong>Preconditions</strong>: <ul>
  312.      * <li>Observed counts must be non-negative. </li>
  313.      * <li>Observed counts for a specific bin must not both be zero. </li>
  314.      * <li>Observed counts for a specific sample must not all be  0. </li>
  315.      * <li>The arrays {@code observed1} and {@code observed2} must have
  316.      * the same length and their common length must be at least 2. </li></ul>
  317.      *
  318.      * <p>If any of the preconditions are not met, a
  319.      * {@code MathIllegalArgumentException} is thrown.</p>
  320.      *
  321.      * @param observed1 array of observed frequency counts of the first data set
  322.      * @param observed2 array of observed frequency counts of the second data
  323.      * set
  324.      * @return G-Test statistic
  325.      * @throws DimensionMismatchException the lengths of the arrays do not
  326.      * match or their common length is less than 2
  327.      * @throws NotPositiveException if any entry in {@code observed1} or
  328.      * {@code observed2} is negative
  329.      * @throws ZeroException if either all counts of
  330.      * {@code observed1} or {@code observed2} are zero, or if the count
  331.      * at the same index is zero for both arrays.
  332.      */
  333.     public double gDataSetsComparison(final long[] observed1, final long[] observed2)
  334.             throws DimensionMismatchException, NotPositiveException, ZeroException {

  335.         // Make sure lengths are same
  336.         if (observed1.length < 2) {
  337.             throw new DimensionMismatchException(observed1.length, 2);
  338.         }
  339.         if (observed1.length != observed2.length) {
  340.             throw new DimensionMismatchException(observed1.length, observed2.length);
  341.         }

  342.         // Ensure non-negative counts
  343.         MathArrays.checkNonNegative(observed1);
  344.         MathArrays.checkNonNegative(observed2);

  345.         // Compute and compare count sums
  346.         long countSum1 = 0;
  347.         long countSum2 = 0;

  348.         // Compute and compare count sums
  349.         final long[] collSums = new long[observed1.length];
  350.         final long[][] k = new long[2][observed1.length];

  351.         for (int i = 0; i < observed1.length; i++) {
  352.             if (observed1[i] == 0 && observed2[i] == 0) {
  353.                 throw new ZeroException(LocalizedFormats.OBSERVED_COUNTS_BOTTH_ZERO_FOR_ENTRY, i);
  354.             } else {
  355.                 countSum1 += observed1[i];
  356.                 countSum2 += observed2[i];
  357.                 collSums[i] = observed1[i] + observed2[i];
  358.                 k[0][i] = observed1[i];
  359.                 k[1][i] = observed2[i];
  360.             }
  361.         }
  362.         // Ensure neither sample is uniformly 0
  363.         if (countSum1 == 0 || countSum2 == 0) {
  364.             throw new ZeroException();
  365.         }
  366.         final long[] rowSums = {countSum1, countSum2};
  367.         final double sum = (double) countSum1 + (double) countSum2;
  368.         return 2 * sum * (entropy(rowSums) + entropy(collSums) - entropy(k));
  369.     }

  370.     /**
  371.      * Calculates the root log-likelihood ratio for 2 state Datasets. See
  372.      * {@link #gDataSetsComparison(long[], long[] )}.
  373.      *
  374.      * <p>Given two events A and B, let k11 be the number of times both events
  375.      * occur, k12 the incidence of B without A, k21 the count of A without B,
  376.      * and k22 the number of times neither A nor B occurs.  What is returned
  377.      * by this method is </p>
  378.      *
  379.      * <p>{@code (sgn) sqrt(gValueDataSetsComparison({k11, k12}, {k21, k22})}</p>
  380.      *
  381.      * <p>where {@code sgn} is -1 if {@code k11 / (k11 + k12) < k21 / (k21 + k22))};<br>
  382.      * 1 otherwise.</p>
  383.      *
  384.      * <p>Signed root LLR has two advantages over the basic LLR: a) it is positive
  385.      * where k11 is bigger than expected, negative where it is lower b) if there is
  386.      * no difference it is asymptotically normally distributed. This allows one
  387.      * to talk about "number of standard deviations" which is a more common frame
  388.      * of reference than the chi^2 distribution.</p>
  389.      *
  390.      * @param k11 number of times the two events occurred together (AB)
  391.      * @param k12 number of times the second event occurred WITHOUT the
  392.      * first event (notA,B)
  393.      * @param k21 number of times the first event occurred WITHOUT the
  394.      * second event (A, notB)
  395.      * @param k22 number of times something else occurred (i.e. was neither
  396.      * of these events (notA, notB)
  397.      * @return root log-likelihood ratio
  398.      *
  399.      */
  400.     public double rootLogLikelihoodRatio(final long k11, long k12,
  401.             final long k21, final long k22) {
  402.         final double llr = gDataSetsComparison(
  403.                 new long[]{k11, k12}, new long[]{k21, k22});
  404.         double sqrt = JdkMath.sqrt(llr);
  405.         if ((double) k11 / (k11 + k12) < (double) k21 / (k21 + k22)) {
  406.             sqrt = -sqrt;
  407.         }
  408.         return sqrt;
  409.     }

  410.     /**
  411.      * <p>Returns the <i>observed significance level</i>, or <a href=
  412.      * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue">
  413.      * p-value</a>, associated with a G-Value (Log-Likelihood Ratio) for two
  414.      * sample test comparing bin frequency counts in {@code observed1} and
  415.      * {@code observed2}.</p>
  416.      *
  417.      * <p>The number returned is the smallest significance level at which one
  418.      * can reject the null hypothesis that the observed counts conform to the
  419.      * same distribution. </p>
  420.      *
  421.      * <p>See {@link #gTest(double[], long[])} for details
  422.      * on how the p-value is computed.  The degrees of of freedom used to
  423.      * perform the test is one less than the common length of the input observed
  424.      * count arrays.</p>
  425.      *
  426.      * <p><strong>Preconditions</strong>:
  427.      * <ul> <li>Observed counts must be non-negative. </li>
  428.      * <li>Observed counts for a specific bin must not both be zero. </li>
  429.      * <li>Observed counts for a specific sample must not all be 0. </li>
  430.      * <li>The arrays {@code observed1} and {@code observed2} must
  431.      * have the same length and their common length must be at least 2. </li>
  432.      * </ul>
  433.      * <p> If any of the preconditions are not met, a
  434.      * {@code MathIllegalArgumentException} is thrown.</p>
  435.      *
  436.      * @param observed1 array of observed frequency counts of the first data set
  437.      * @param observed2 array of observed frequency counts of the second data
  438.      * set
  439.      * @return p-value
  440.      * @throws DimensionMismatchException the length of the arrays does not
  441.      * match or their common length is less than 2
  442.      * @throws NotPositiveException if any of the entries in {@code observed1} or
  443.      * {@code observed2} are negative
  444.      * @throws ZeroException if either all counts of {@code observed1} or
  445.      * {@code observed2} are zero, or if the count at some index is
  446.      * zero for both arrays
  447.      * @throws MaxCountExceededException if an error occurs computing the
  448.      * p-value.
  449.      */
  450.     public double gTestDataSetsComparison(final long[] observed1,
  451.             final long[] observed2)
  452.             throws DimensionMismatchException, NotPositiveException, ZeroException,
  453.             MaxCountExceededException {

  454.         // pass a null rng to avoid unneeded overhead as we will not sample from this distribution
  455.         final ChiSquaredDistribution distribution =
  456.                 ChiSquaredDistribution.of((double) observed1.length - 1);
  457.         return distribution.survivalProbability(
  458.                 gDataSetsComparison(observed1, observed2));
  459.     }

  460.     /**
  461.      * <p>Performs a G-Test (Log-Likelihood Ratio Test) comparing two binned
  462.      * data sets. The test evaluates the null hypothesis that the two lists
  463.      * of observed counts conform to the same frequency distribution, with
  464.      * significance level {@code alpha}. Returns true iff the null
  465.      * hypothesis can be rejected  with 100 * (1 - alpha) percent confidence.
  466.      * </p>
  467.      * <p>See {@link #gDataSetsComparison(long[], long[])} for details
  468.      * on the formula used to compute the G (LLR) statistic used in the test and
  469.      * {@link #gTest(double[], long[])} for information on how
  470.      * the observed significance level is computed. The degrees of of freedom used
  471.      * to perform the test is one less than the common length of the input observed
  472.      * count arrays. </p>
  473.      *
  474.      * <strong>Preconditions</strong>: <ul>
  475.      * <li>Observed counts must be non-negative. </li>
  476.      * <li>Observed counts for a specific bin must not both be zero. </li>
  477.      * <li>Observed counts for a specific sample must not all be 0. </li>
  478.      * <li>The arrays {@code observed1} and {@code observed2} must
  479.      * have the same length and their common length must be at least 2. </li>
  480.      * <li>{@code 0 < alpha < 0.5} </li></ul>
  481.      *
  482.      * <p>If any of the preconditions are not met, a
  483.      * {@code MathIllegalArgumentException} is thrown.</p>
  484.      *
  485.      * @param observed1 array of observed frequency counts of the first data set
  486.      * @param observed2 array of observed frequency counts of the second data
  487.      * set
  488.      * @param alpha significance level of the test
  489.      * @return true iff null hypothesis can be rejected with confidence 1 -
  490.      * alpha
  491.      * @throws DimensionMismatchException the length of the arrays does not
  492.      * match
  493.      * @throws NotPositiveException if any of the entries in {@code observed1} or
  494.      * {@code observed2} are negative
  495.      * @throws ZeroException if either all counts of {@code observed1} or
  496.      * {@code observed2} are zero, or if the count at some index is
  497.      * zero for both arrays
  498.      * @throws OutOfRangeException if {@code alpha} is not in the range
  499.      * (0, 0.5]
  500.      * @throws MaxCountExceededException if an error occurs performing the test
  501.      */
  502.     public boolean gTestDataSetsComparison(
  503.             final long[] observed1,
  504.             final long[] observed2,
  505.             final double alpha)
  506.             throws DimensionMismatchException, NotPositiveException,
  507.             ZeroException, OutOfRangeException, MaxCountExceededException {

  508.         if (alpha <= 0 || alpha > 0.5) {
  509.             throw new OutOfRangeException(
  510.                     LocalizedFormats.OUT_OF_BOUND_SIGNIFICANCE_LEVEL, alpha, 0, 0.5);
  511.         }
  512.         return gTestDataSetsComparison(observed1, observed2) < alpha;
  513.     }
  514. }