Improved javadoc; changed confidence level to significance level. JIRA: MATH-1034.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1532638 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math3/stat/inference/BinomialTest.java

@@ -51,8 +51,8 @@ public class BinomialTest {
      * @param numberOfSuccesses number of successes observed
      * @param probability assumed probability of a single trial under the null hypothesis
      * @param alternativeHypothesis type of hypothesis being evaluated (one- or two-sided)
-     * @param confidenceLevel confidence level of the test
+     * @param alpha significance level of the test
-     * @return true if the null hypothesis can be rejected with confidence {@code confidenceLevel}
+     * @return true if the null hypothesis can be rejected with confidence {@code 1 - alpha}
      * @throws NotPositiveException if {@code numberOfTrials} or {@code numberOfSuccesses} is negative
      * @throws OutOfRangeException if {@code probability} is not between 0 and 1
      * @throws MathIllegalArgumentException if {@code numberOfTrials} < {@code numberOfSuccesses} or
@@ -60,9 +60,9 @@ public class BinomialTest {
      * @see AlternativeHypothesis
      */
     public boolean binomialTest(int numberOfTrials, int numberOfSuccesses, double probability,
-                                AlternativeHypothesis alternativeHypothesis, double confidenceLevel) {
+                                AlternativeHypothesis alternativeHypothesis, double alpha) {
         double pValue = binomialTest(numberOfTrials, numberOfSuccesses, probability, alternativeHypothesis);
-        return pValue < 1 - confidenceLevel;
+        return pValue < alpha;
     }
 
     /**
@@ -71,7 +71,15 @@ public class BinomialTest {
      * associated with a <a href="http://en.wikipedia.org/wiki/Binomial_test"> Binomial test</a>.
      * <p>
      * The number returned is the smallest significance level at which one can reject the null hypothesis.
-     * The form of the hypothesis depends on {@code alternativeHypothesis}.
+     * The form of the hypothesis depends on {@code alternativeHypothesis}.</p>
+     * <p>
+     * The p-Value represents the likelihood of getting a result at least as extreme as the sample,
+     * given the provided {@code probability} of success on a single trial. For single-sided tests,
+     * this value can be directly derived from the Binomial distribution. For the two-sided test,
+     * the implementation works as follows: we start by looking at the most extreme cases
+     * (0 success and n success where n is the number of trials from the sample) and determine their likelihood.
+     * The lower value is added to the p-Value (if both values are equal, both are added). Then we continue with
+     * the next extreme value, until we added the value for the actual observed sample.</p>
      * <p>
      * <strong>Preconditions</strong>:
      * <ul>
@@ -79,7 +87,7 @@ public class BinomialTest {
      * <li>Number of successes must be &ge; 0.</li>
      * <li>Number of successes must be &le; number of trials.</li>
      * <li>Probability must be &ge; 0 and &le; 1.</li>
-     * </ul>
+     * </ul></p>
      *
      * @param numberOfTrials number of trials performed
      * @param numberOfSuccesses number of successes observed

src/test/java/org/apache/commons/math3/stat/inference/BinomialTestTest.java

@@ -67,15 +67,15 @@ public class BinomialTestTest {
 
     @Test
     public void testBinomialTestAcceptReject() {
-        double confidenceLevel95 = 0.95;
+        double alpha05 = 0.05;
-        double confidenceLevel99 = 0.99;
+        double alpha01 = 0.01;
 
-        Assert.assertTrue(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.TWO_SIDED, confidenceLevel95));
+        Assert.assertTrue(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.TWO_SIDED, alpha05));
-        Assert.assertTrue(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.GREATER_THAN, confidenceLevel95));
+        Assert.assertTrue(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.GREATER_THAN, alpha05));
-        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.LESS_THAN, confidenceLevel95));
+        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.LESS_THAN, alpha05));
 
-        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.TWO_SIDED, confidenceLevel99));
+        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.TWO_SIDED, alpha01));
-        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.GREATER_THAN, confidenceLevel99));
+        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.GREATER_THAN, alpha01));
-        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.LESS_THAN, confidenceLevel95));
+        Assert.assertFalse(testStatistic.binomialTest(trials, successes, probability, AlternativeHypothesis.LESS_THAN, alpha05));
     }
 }