Package org.apache.commons.math3.stat.interval

Class IntervalUtils

java.lang.Object

org.apache.commons.math3.stat.interval.IntervalUtils

public final class IntervalUtils
extends java.lang.Object

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

Field Summary

Fields

Modifier and Type	Field	Description
private static BinomialConfidenceInterval	AGRESTI_COULL	Singleton Agresti-Coull instance.
private static BinomialConfidenceInterval	CLOPPER_PEARSON	Singleton Clopper-Pearson instance.
private static BinomialConfidenceInterval	NORMAL_APPROXIMATION	Singleton NormalApproximation instance.
private static BinomialConfidenceInterval	WILSON_SCORE	Singleton Wilson score instance.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	IntervalUtils()	Prevent instantiation.

Method Summary

Modifier and Type	Method	Description
(package private) static void	checkParameters(int numberOfTrials, int numberOfSuccesses, double confidenceLevel)	Verifies that parameters satisfy preconditions.
static ConfidenceInterval	getAgrestiCoullInterval(int numberOfTrials, int numberOfSuccesses, double confidenceLevel)	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.
static ConfidenceInterval	getClopperPearsonInterval(int numberOfTrials, int numberOfSuccesses, double 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.
static ConfidenceInterval	getNormalApproximationInterval(int numberOfTrials, int numberOfSuccesses, double 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.
static ConfidenceInterval	getWilsonScoreInterval(int numberOfTrials, int numberOfSuccesses, double 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AGRESTI_COULL

private static final BinomialConfidenceInterval AGRESTI_COULL

Singleton Agresti-Coull instance.

CLOPPER_PEARSON

private static final BinomialConfidenceInterval CLOPPER_PEARSON

Singleton Clopper-Pearson instance.

NORMAL_APPROXIMATION

private static final BinomialConfidenceInterval NORMAL_APPROXIMATION

Singleton NormalApproximation instance.

WILSON_SCORE

private static final BinomialConfidenceInterval WILSON_SCORE

Singleton Wilson score instance.

Constructor Detail

IntervalUtils

private IntervalUtils()

Prevent instantiation.

Method Detail

getAgrestiCoullInterval

public static ConfidenceInterval getAgrestiCoullInterval(int numberOfTrials,
                                                         int numberOfSuccesses,
                                                         double confidenceLevel)

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.

Parameters:

numberOfTrials - number of trials

numberOfSuccesses - number of successes

confidenceLevel - desired probability that the true probability of success falls within the returned interval

Returns:

Confidence interval containing the probability of success with probability confidenceLevel

Throws:

NotStrictlyPositiveException - if numberOfTrials <= 0.

NotPositiveException - if numberOfSuccesses < 0.

NumberIsTooLargeException - if numberOfSuccesses > numberOfTrials.

OutOfRangeException - if confidenceLevel is not in the interval (0, 1).

getClopperPearsonInterval

public static ConfidenceInterval getClopperPearsonInterval(int numberOfTrials,
                                                           int numberOfSuccesses,
                                                           double 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:

• numberOfTrials must be positive
• numberOfSuccesses may not exceed numberOfTrials
• confidenceLevel must be strictly between 0 and 1 (exclusive)

Parameters:

numberOfTrials - number of trials

numberOfSuccesses - number of successes

confidenceLevel - desired probability that the true probability of success falls within the returned interval

Returns:

Confidence interval containing the probability of success with probability confidenceLevel

Throws:

NotStrictlyPositiveException - if numberOfTrials <= 0.

NotPositiveException - if numberOfSuccesses < 0.

NumberIsTooLargeException - if numberOfSuccesses > numberOfTrials.

OutOfRangeException - if confidenceLevel is not in the interval (0, 1).

getNormalApproximationInterval

public static ConfidenceInterval getNormalApproximationInterval(int numberOfTrials,
                                                                int numberOfSuccesses,
                                                                double 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.

Parameters:

numberOfTrials - number of trials

numberOfSuccesses - number of successes

confidenceLevel - desired probability that the true probability of success falls within the interval

Returns:

Confidence interval containing the probability of success with probability confidenceLevel

getWilsonScoreInterval

public static ConfidenceInterval getWilsonScoreInterval(int numberOfTrials,
                                                        int numberOfSuccesses,
                                                        double 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.

Parameters:

numberOfTrials - number of trials

numberOfSuccesses - number of successes

confidenceLevel - desired probability that the true probability of success falls within the returned interval

Returns:

Confidence interval containing the probability of success with probability confidenceLevel

Throws:

NotStrictlyPositiveException - if numberOfTrials <= 0.

NotPositiveException - if numberOfSuccesses < 0.

NumberIsTooLargeException - if numberOfSuccesses > numberOfTrials.

OutOfRangeException - if confidenceLevel is not in the interval (0, 1).

checkParameters

static void checkParameters(int numberOfTrials,
                            int numberOfSuccesses,
                            double confidenceLevel)

Verifies that parameters satisfy preconditions.

Parameters:

numberOfTrials - number of trials (must be positive)

numberOfSuccesses - number of successes (must not exceed numberOfTrials)

confidenceLevel - confidence level (must be strictly between 0 and 1)

Throws:

NotStrictlyPositiveException - if numberOfTrials <= 0.

NotPositiveException - if numberOfSuccesses < 0.

NumberIsTooLargeException - if numberOfSuccesses > numberOfTrials.

OutOfRangeException - if confidenceLevel is not in the interval (0, 1).