BinomialDistribution (Apache Commons Statistics Distribution 1.0 API)

java.lang.Object
- org.apache.commons.statistics.distribution.BinomialDistribution

All Implemented Interfaces:

DiscreteDistribution
```
public final class BinomialDistribution
extends Object
```
Implementation of the binomial distribution.
The probability mass function of \( X \) is:
\[ f(k; n, p) = \binom{n}{k} p^k (1-p)^{n-k} \]
for \( n \in \{0, 1, 2, \dots\} \) the number of trials, \( p \in [0, 1] \) the probability of success, \( k \in \{0, 1, \dots, n\} \) the number of successes, and
\[ \binom{n}{k} = \frac{n!}{k! \, (n-k)!} \]
is the binomial coefficient.

See Also:

Binomial distribution (Wikipedia), Binomial distribution (MathWorld)

Nested Class Summary
- Nested classes/interfaces inherited from interface org.apache.commons.statistics.distribution.DiscreteDistribution
  DiscreteDistribution.Sampler

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`DiscreteDistribution.Sampler`	`createSampler(UniformRandomProvider rng)` Creates a sampler.
`double`	`cumulativeProbability(int x)` For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X <= x)`.
`double`	`getMean()` Gets the mean of this distribution.
`int`	`getNumberOfTrials()` Gets the number of trials parameter of this distribution.
`double`	`getProbabilityOfSuccess()` Gets the probability of success parameter of this distribution.
`int`	`getSupportLowerBound()` Gets the lower bound of the support.
`int`	`getSupportUpperBound()` Gets the upper bound of the support.
`double`	`getVariance()` Gets the variance of this distribution.
`int`	`inverseCumulativeProbability(double p)` Computes the quantile function of this distribution.
`int`	`inverseSurvivalProbability(double p)` Computes the inverse survival probability function of this distribution.
`double`	`logProbability(int x)` For a random variable `X` whose values are distributed according to this distribution, this method returns `log(P(X = x))`, where `log` is the natural logarithm.
`static BinomialDistribution`	`of(int trials, double p)` Creates a binomial distribution.
`double`	`probability(int x)` For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X = x)`.
`double`	`probability(int x0, int x1)` For a random variable `X` whose values are distributed according to this distribution, this method returns `P(x0 < X <= x1)`.
`double`	`survivalProbability(int x)` For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X > x)`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - of
```
public static BinomialDistribution of(int trials,
                                      double p)
```
    Creates a binomial distribution.
    
    Parameters:
    
    trials - Number of trials.
    
    p - Probability of success.
    
    Returns:
    
    the distribution
    
    Throws:
    
    IllegalArgumentException - if trials < 0, or if p < 0 or p > 1.
  - getNumberOfTrials
```
public int getNumberOfTrials()
```
    Gets the number of trials parameter of this distribution.
    
    Returns:
    
    the number of trials.
  - getProbabilityOfSuccess
```
public double getProbabilityOfSuccess()
```
    Gets the probability of success parameter of this distribution.
    
    Returns:
    
    the probability of success.
  - probability
```
public double probability(int x)
```
    For a random variable X whose values are distributed according to this distribution, this method returns P(X = x). In other words, this method represents the probability mass function (PMF) for the distribution.
    
    Parameters:
    
    x - Point at which the PMF is evaluated.
    
    Returns:
    
    the value of the probability mass function at x.
  - logProbability
```
public double logProbability(int x)
```
    For a random variable X whose values are distributed according to this distribution, this method returns log(P(X = x)), where log is the natural logarithm.
    
    Parameters:
    
    x - Point at which the PMF is evaluated.
    
    Returns:
    
    the logarithm of the value of the probability mass function at x.
  - cumulativeProbability
```
public double cumulativeProbability(int x)
```
    For a random variable X whose values are distributed according to this distribution, this method returns P(X <= x). In other, words, this method represents the (cumulative) distribution function (CDF) for this distribution.
    
    Parameters:
    
    x - Point at which the CDF is evaluated.
    
    Returns:
    
    the probability that a random variable with this distribution takes a value less than or equal to x.
  - survivalProbability
```
public double survivalProbability(int x)
```
    For a random variable X whose values are distributed according to this distribution, this method returns P(X > x). In other words, this method represents the complementary cumulative distribution function.
    By default, this is defined as 1 - cumulativeProbability(x), but the specific implementation may be more accurate.
    
    Parameters:
    
    x - Point at which the survival function is evaluated.
    
    Returns:
    
    the probability that a random variable with this distribution takes a value greater than x.
  - getMean
```
public double getMean()
```
    Gets the mean of this distribution.
    For number of trials \( n \) and probability of success \( p \), the mean is \( np \).
    
    Returns:
    
    the mean.
  - getVariance
```
public double getVariance()
```
    Gets the variance of this distribution.
    For number of trials \( n \) and probability of success \( p \), the variance is \( np (1 - p) \).
    
    Returns:
    
    the variance.
  - getSupportLowerBound
```
public int getSupportLowerBound()
```
    Gets the lower bound of the support. This method must return the same value as inverseCumulativeProbability(0), i.e. \( \inf \{ x \in \mathbb Z : P(X \le x) \gt 0 \} \). By convention, Integer.MIN_VALUE should be substituted for negative infinity.
    The lower bound of the support is always 0 except for the probability parameter p = 1.
    
    Returns:
    
    0 or the number of trials.
  - getSupportUpperBound
```
public int getSupportUpperBound()
```
    Gets the upper bound of the support. This method must return the same value as inverseCumulativeProbability(1), i.e. \( \inf \{ x \in \mathbb Z : P(X \le x) = 1 \} \). By convention, Integer.MAX_VALUE should be substituted for positive infinity.
    The upper bound of the support is the number of trials except for the probability parameter p = 0.
    
    Returns:
    
    number of trials or 0.
  - probability
```
public double probability(int x0,
                          int x1)
```
    For a random variable X whose values are distributed according to this distribution, this method returns P(x0 < X <= x1). The default implementation uses the identity P(x0 < X <= x1) = P(X <= x1) - P(X <= x0)
    Special cases:
    - returns 0.0 if x0 == x1;
    - returns probability(x1) if x0 + 1 == x1;
    Specified by:
    
    probability in interface DiscreteDistribution
    
    Parameters:
    
    x0 - Lower bound (exclusive).
    
    x1 - Upper bound (inclusive).
    
    Returns:
    
    the probability that a random variable with this distribution takes a value between x0 and x1, excluding the lower and including the upper endpoint.
  - inverseCumulativeProbability
```
public int inverseCumulativeProbability(double p)
```
    Computes the quantile function of this distribution. For a random variable X distributed according to this distribution, the returned value is:
    \[ x = \begin{cases} \inf \{ x \in \mathbb Z : P(X \le x) \ge p\} & \text{for } 0 \lt p \le 1 \\ \inf \{ x \in \mathbb Z : P(X \le x) \gt 0 \} & \text{for } p = 0 \end{cases} \]
    If the result exceeds the range of the data type int, then Integer.MIN_VALUE or Integer.MAX_VALUE is returned. In this case the result of cumulativeProbability(x) called using the returned p-quantile may not compute the original p.
    The default implementation returns:
    - DiscreteDistribution.getSupportLowerBound() for p = 0,
    - DiscreteDistribution.getSupportUpperBound() for p = 1, or
    - the result of a binary search between the lower and upper bound using cumulativeProbability(x). The bounds may be bracketed for efficiency.
    Specified by:
    
    inverseCumulativeProbability in interface DiscreteDistribution
    
    Parameters:
    
    p - Cumulative probability.
    
    Returns:
    
    the smallest p-quantile of this distribution (largest 0-quantile for p = 0).
    
    Throws:
    
    IllegalArgumentException - if p < 0 or p > 1
  - inverseSurvivalProbability
```
public int inverseSurvivalProbability(double p)
```
    Computes the inverse survival probability function of this distribution. For a random variable X distributed according to this distribution, the returned value is:
    \[ x = \begin{cases} \inf \{ x \in \mathbb Z : P(X \ge x) \le p\} & \text{for } 0 \le p \lt 1 \\ \inf \{ x \in \mathbb Z : P(X \ge x) \lt 1 \} & \text{for } p = 1 \end{cases} \]
    If the result exceeds the range of the data type int, then Integer.MIN_VALUE or Integer.MAX_VALUE is returned. In this case the result of survivalProbability(x) called using the returned (1-p)-quantile may not compute the original p.
    By default, this is defined as inverseCumulativeProbability(1 - p), but the specific implementation may be more accurate.
    The default implementation returns:
    - DiscreteDistribution.getSupportLowerBound() for p = 1,
    - DiscreteDistribution.getSupportUpperBound() for p = 0, or
    - the result of a binary search between the lower and upper bound using survivalProbability(x). The bounds may be bracketed for efficiency.
    Specified by:
    
    inverseSurvivalProbability in interface DiscreteDistribution
    
    Parameters:
    
    p - Cumulative probability.
    
    Returns:
    
    the smallest (1-p)-quantile of this distribution (largest 0-quantile for p = 1).
    
    Throws:
    
    IllegalArgumentException - if p < 0 or p > 1
  - createSampler
```
public DiscreteDistribution.Sampler createSampler(UniformRandomProvider rng)
```
    Creates a sampler.
    
    Specified by:
    
    createSampler in interface DiscreteDistribution
    
    Parameters:
    
    rng - Generator of uniformly distributed numbers.
    
    Returns:
    
    a sampler that produces random numbers according this distribution.

Class BinomialDistribution

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.commons.statistics.distribution.DiscreteDistribution

Method Summary

Methods inherited from class java.lang.Object

Method Detail

of

getNumberOfTrials

getProbabilityOfSuccess

probability

logProbability

cumulativeProbability

survivalProbability

getMean

getVariance

getSupportLowerBound

getSupportUpperBound

probability

inverseCumulativeProbability

inverseSurvivalProbability

createSampler