IntervalUtils.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.interval;

  18. import org.apache.commons.math4.legacy.exception.NotPositiveException;
  19. import org.apache.commons.math4.legacy.exception.NotStrictlyPositiveException;
  20. import org.apache.commons.math4.legacy.exception.NumberIsTooLargeException;
  21. import org.apache.commons.math4.legacy.exception.OutOfRangeException;
  22. import org.apache.commons.math4.legacy.exception.util.LocalizedFormats;

  23. /**
  24.  * Factory methods to generate confidence intervals for a binomial proportion.
  25.  * The supported methods are:
  26.  * <ul>
  27.  * <li>Agresti-Coull interval</li>
  28.  * <li>Clopper-Pearson method (exact method)</li>
  29.  * <li>Normal approximation (based on central limit theorem)</li>
  30.  * <li>Wilson score interval</li>
  31.  * </ul>
  32.  *
  33.  * @since 3.3
  34.  */
  35. public final class IntervalUtils {

  36.     /** Singleton Agresti-Coull instance. */
  37.     private static final BinomialConfidenceInterval AGRESTI_COULL = new AgrestiCoullInterval();

  38.     /** Singleton Clopper-Pearson instance. */
  39.     private static final BinomialConfidenceInterval CLOPPER_PEARSON = new ClopperPearsonInterval();

  40.     /** Singleton NormalApproximation instance. */
  41.     private static final BinomialConfidenceInterval NORMAL_APPROXIMATION = new NormalApproximationInterval();

  42.     /** Singleton Wilson score instance. */
  43.     private static final BinomialConfidenceInterval WILSON_SCORE = new WilsonScoreInterval();

  44.     /**
  45.      * Prevent instantiation.
  46.      */
  47.     private IntervalUtils() {
  48.     }

  49.     /**
  50.      * Create an Agresti-Coull binomial confidence interval for the true
  51.      * probability of success of an unknown binomial distribution with the given
  52.      * observed number of trials, successes and confidence level.
  53.      *
  54.      * @param numberOfTrials number of trials
  55.      * @param numberOfSuccesses number of successes
  56.      * @param confidenceLevel desired probability that the true probability of
  57.      *        success falls within the returned interval
  58.      * @return Confidence interval containing the probability of success with
  59.      *         probability {@code confidenceLevel}
  60.      * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}.
  61.      * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
  62.      * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}.
  63.      * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}.
  64.      */
  65.     public static ConfidenceInterval getAgrestiCoullInterval(int numberOfTrials, int numberOfSuccesses,
  66.                                                              double confidenceLevel) {
  67.         return AGRESTI_COULL.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel);
  68.     }

  69.     /**
  70.      * Create a Clopper-Pearson binomial confidence interval for the true
  71.      * probability of success of an unknown binomial distribution with the given
  72.      * observed number of trials, successes and confidence level.
  73.      * <p>
  74.      * Preconditions:
  75.      * <ul>
  76.      * <li>{@code numberOfTrials} must be positive</li>
  77.      * <li>{@code numberOfSuccesses} may not exceed {@code numberOfTrials}</li>
  78.      * <li>{@code confidenceLevel} must be strictly between 0 and 1 (exclusive)</li>
  79.      * </ul>
  80.      *
  81.      * @param numberOfTrials number of trials
  82.      * @param numberOfSuccesses number of successes
  83.      * @param confidenceLevel desired probability that the true probability of
  84.      *        success falls within the returned interval
  85.      * @return Confidence interval containing the probability of success with
  86.      *         probability {@code confidenceLevel}
  87.      * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}.
  88.      * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
  89.      * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}.
  90.      * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}.
  91.      */
  92.     public static ConfidenceInterval getClopperPearsonInterval(int numberOfTrials, int numberOfSuccesses,
  93.                                                                double confidenceLevel) {
  94.         return CLOPPER_PEARSON.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel);
  95.     }

  96.     /**
  97.      * Create a binomial confidence interval for the true probability of success
  98.      * of an unknown binomial distribution with the given observed number of
  99.      * trials, successes and confidence level using the Normal approximation to
  100.      * the binomial distribution.
  101.      *
  102.      * @param numberOfTrials number of trials
  103.      * @param numberOfSuccesses number of successes
  104.      * @param confidenceLevel desired probability that the true probability of
  105.      *        success falls within the interval
  106.      * @return Confidence interval containing the probability of success with
  107.      *         probability {@code confidenceLevel}
  108.      */
  109.     public static ConfidenceInterval getNormalApproximationInterval(int numberOfTrials, int numberOfSuccesses,
  110.                                                                     double confidenceLevel) {
  111.         return NORMAL_APPROXIMATION.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel);
  112.     }

  113.     /**
  114.      * Create a Wilson score binomial confidence interval for the true
  115.      * probability of success of an unknown binomial distribution with the given
  116.      * observed number of trials, successes and confidence level.
  117.      *
  118.      * @param numberOfTrials number of trials
  119.      * @param numberOfSuccesses number of successes
  120.      * @param confidenceLevel desired probability that the true probability of
  121.      *        success falls within the returned interval
  122.      * @return Confidence interval containing the probability of success with
  123.      *         probability {@code confidenceLevel}
  124.      * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}.
  125.      * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
  126.      * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}.
  127.      * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}.
  128.      */
  129.     public static ConfidenceInterval getWilsonScoreInterval(int numberOfTrials, int numberOfSuccesses,
  130.                                                             double confidenceLevel) {
  131.         return WILSON_SCORE.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel);
  132.     }

  133.     /**
  134.      * Verifies that parameters satisfy preconditions.
  135.      *
  136.      * @param numberOfTrials number of trials (must be positive)
  137.      * @param numberOfSuccesses number of successes (must not exceed numberOfTrials)
  138.      * @param confidenceLevel confidence level (must be strictly between 0 and 1)
  139.      * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}.
  140.      * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
  141.      * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}.
  142.      * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}.
  143.      */
  144.     static void checkParameters(int numberOfTrials, int numberOfSuccesses, double confidenceLevel) {
  145.         if (numberOfTrials <= 0) {
  146.             throw new NotStrictlyPositiveException(LocalizedFormats.NUMBER_OF_TRIALS, numberOfTrials);
  147.         }
  148.         if (numberOfSuccesses < 0) {
  149.             throw new NotPositiveException(LocalizedFormats.NEGATIVE_NUMBER_OF_SUCCESSES, numberOfSuccesses);
  150.         }
  151.         if (numberOfSuccesses > numberOfTrials) {
  152.             throw new NumberIsTooLargeException(LocalizedFormats.NUMBER_OF_SUCCESS_LARGER_THAN_POPULATION_SIZE,
  153.                                                 numberOfSuccesses, numberOfTrials, true);
  154.         }
  155.         if (confidenceLevel <= 0 || confidenceLevel >= 1) {
  156.             throw new OutOfRangeException(LocalizedFormats.OUT_OF_BOUNDS_CONFIDENCE_LEVEL,
  157.                                           confidenceLevel, 0, 1);
  158.         }
  159.     }
  160. }