| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.math4.legacy.stat.interval; |
| |
| import org.apache.commons.math4.legacy.exception.NotPositiveException; |
| import org.apache.commons.math4.legacy.exception.NotStrictlyPositiveException; |
| import org.apache.commons.math4.legacy.exception.NumberIsTooLargeException; |
| import org.apache.commons.math4.legacy.exception.OutOfRangeException; |
| import org.apache.commons.math4.legacy.exception.util.LocalizedFormats; |
| |
| /** |
| * Factory methods to generate confidence intervals for a binomial proportion. |
| * The supported methods are: |
| * <ul> |
| * <li>Agresti-Coull interval</li> |
| * <li>Clopper-Pearson method (exact method)</li> |
| * <li>Normal approximation (based on central limit theorem)</li> |
| * <li>Wilson score interval</li> |
| * </ul> |
| * |
| * @since 3.3 |
| */ |
| public final class IntervalUtils { |
| |
| /** Singleton Agresti-Coull instance. */ |
| private static final BinomialConfidenceInterval AGRESTI_COULL = new AgrestiCoullInterval(); |
| |
| /** Singleton Clopper-Pearson instance. */ |
| private static final BinomialConfidenceInterval CLOPPER_PEARSON = new ClopperPearsonInterval(); |
| |
| /** Singleton NormalApproximation instance. */ |
| private static final BinomialConfidenceInterval NORMAL_APPROXIMATION = new NormalApproximationInterval(); |
| |
| /** Singleton Wilson score instance. */ |
| private static final BinomialConfidenceInterval WILSON_SCORE = new WilsonScoreInterval(); |
| |
| /** |
| * Prevent instantiation. |
| */ |
| private IntervalUtils() { |
| } |
| |
| /** |
| * Create an Agresti-Coull binomial confidence interval for the true |
| * probability of success of an unknown binomial distribution with the given |
| * observed number of trials, successes and confidence level. |
| * |
| * @param numberOfTrials number of trials |
| * @param numberOfSuccesses number of successes |
| * @param confidenceLevel desired probability that the true probability of |
| * success falls within the returned interval |
| * @return Confidence interval containing the probability of success with |
| * probability {@code confidenceLevel} |
| * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}. |
| * @throws NotPositiveException if {@code numberOfSuccesses < 0}. |
| * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}. |
| * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}. |
| */ |
| public static ConfidenceInterval getAgrestiCoullInterval(int numberOfTrials, int numberOfSuccesses, |
| double confidenceLevel) { |
| return AGRESTI_COULL.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel); |
| } |
| |
| /** |
| * Create a Clopper-Pearson binomial confidence interval for the true |
| * probability of success of an unknown binomial distribution with the given |
| * observed number of trials, successes and confidence level. |
| * <p> |
| * Preconditions: |
| * <ul> |
| * <li>{@code numberOfTrials} must be positive</li> |
| * <li>{@code numberOfSuccesses} may not exceed {@code numberOfTrials}</li> |
| * <li>{@code confidenceLevel} must be strictly between 0 and 1 (exclusive)</li> |
| * </ul> |
| * |
| * @param numberOfTrials number of trials |
| * @param numberOfSuccesses number of successes |
| * @param confidenceLevel desired probability that the true probability of |
| * success falls within the returned interval |
| * @return Confidence interval containing the probability of success with |
| * probability {@code confidenceLevel} |
| * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}. |
| * @throws NotPositiveException if {@code numberOfSuccesses < 0}. |
| * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}. |
| * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}. |
| */ |
| public static ConfidenceInterval getClopperPearsonInterval(int numberOfTrials, int numberOfSuccesses, |
| double confidenceLevel) { |
| return CLOPPER_PEARSON.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel); |
| } |
| |
| /** |
| * Create a binomial confidence interval for the true probability of success |
| * of an unknown binomial distribution with the given observed number of |
| * trials, successes and confidence level using the Normal approximation to |
| * the binomial distribution. |
| * |
| * @param numberOfTrials number of trials |
| * @param numberOfSuccesses number of successes |
| * @param confidenceLevel desired probability that the true probability of |
| * success falls within the interval |
| * @return Confidence interval containing the probability of success with |
| * probability {@code confidenceLevel} |
| */ |
| public static ConfidenceInterval getNormalApproximationInterval(int numberOfTrials, int numberOfSuccesses, |
| double confidenceLevel) { |
| return NORMAL_APPROXIMATION.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel); |
| } |
| |
| /** |
| * Create a Wilson score binomial confidence interval for the true |
| * probability of success of an unknown binomial distribution with the given |
| * observed number of trials, successes and confidence level. |
| * |
| * @param numberOfTrials number of trials |
| * @param numberOfSuccesses number of successes |
| * @param confidenceLevel desired probability that the true probability of |
| * success falls within the returned interval |
| * @return Confidence interval containing the probability of success with |
| * probability {@code confidenceLevel} |
| * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}. |
| * @throws NotPositiveException if {@code numberOfSuccesses < 0}. |
| * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}. |
| * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}. |
| */ |
| public static ConfidenceInterval getWilsonScoreInterval(int numberOfTrials, int numberOfSuccesses, |
| double confidenceLevel) { |
| return WILSON_SCORE.createInterval(numberOfTrials, numberOfSuccesses, confidenceLevel); |
| } |
| |
| /** |
| * Verifies that parameters satisfy preconditions. |
| * |
| * @param numberOfTrials number of trials (must be positive) |
| * @param numberOfSuccesses number of successes (must not exceed numberOfTrials) |
| * @param confidenceLevel confidence level (must be strictly between 0 and 1) |
| * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}. |
| * @throws NotPositiveException if {@code numberOfSuccesses < 0}. |
| * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}. |
| * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}. |
| */ |
| static void checkParameters(int numberOfTrials, int numberOfSuccesses, double confidenceLevel) { |
| if (numberOfTrials <= 0) { |
| throw new NotStrictlyPositiveException(LocalizedFormats.NUMBER_OF_TRIALS, numberOfTrials); |
| } |
| if (numberOfSuccesses < 0) { |
| throw new NotPositiveException(LocalizedFormats.NEGATIVE_NUMBER_OF_SUCCESSES, numberOfSuccesses); |
| } |
| if (numberOfSuccesses > numberOfTrials) { |
| throw new NumberIsTooLargeException(LocalizedFormats.NUMBER_OF_SUCCESS_LARGER_THAN_POPULATION_SIZE, |
| numberOfSuccesses, numberOfTrials, true); |
| } |
| if (confidenceLevel <= 0 || confidenceLevel >= 1) { |
| throw new OutOfRangeException(LocalizedFormats.OUT_OF_BOUNDS_CONFIDENCE_LEVEL, |
| confidenceLevel, 0, 1); |
| } |
| } |
| |
| } |
