org.apache.commons.math3.stat.interval.IntervalUtils Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-math3 Show documentation
Show all versions of commons-math3 Show documentation
The Apache Commons Math project is a library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems not immediately available in the Java programming language or commons-lang.
/*
* 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.math3.stat.interval;
import org.apache.commons.math3.exception.NotPositiveException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NumberIsTooLargeException;
import org.apache.commons.math3.exception.OutOfRangeException;
import org.apache.commons.math3.exception.util.LocalizedFormats;
/**
* Factory methods to generate confidence intervals for a binomial proportion.
* The supported methods are:
*
* - Agresti-Coull interval
* - Clopper-Pearson method (exact method)
* - Normal approximation (based on central limit theorem)
* - Wilson score interval
*
*
* @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.
*
* Preconditions:
*
* - {@code numberOfTrials} must be positive
* - {@code numberOfSuccesses} may not exceed {@code numberOfTrials}
* - {@code confidenceLevel} must be strictly between 0 and 1 (exclusive)
*
*
*
* @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);
}
}
}