kstats-distributions/org.oremif.kstats.distributions/BetaBinomialDistribution

BetaBinomialDistribution

class BetaBinomialDistribution(val trials: Int, val alpha: Double, val beta: Double) : DiscreteDistribution(source)

Represents the beta-binomial distribution, a compound distribution arising when the success probability of a binomial distribution is itself random and follows a beta distribution.

The beta-binomial distribution models overdispersed count data where the assumption of a fixed success probability is too restrictive. Instead of a single probability, each observation draws its own success probability from a Beta(alpha, beta) distribution, and the count of successes in trials independent trials then follows a binomial. This two-stage model captures extra variability beyond what a simple binomial allows, making it suitable for scenarios such as the number of defective items in batches with varying quality, or the number of positive responses in surveys where response rates vary across groups.

The support is {0, 1, ..., trials}. Sampling works by first drawing a random probability from Beta(alpha, beta), then drawing from Binomial(trials, p). The PMF, CDF, and survival function are computed in log-space using the log-beta function and the log-sum-exp technique for numerical stability.

Example:

val dist = BetaBinomialDistribution(trials = 10, alpha = 2.0, beta = 5.0)
dist.pmf(3)               // probability of exactly 3 successes
dist.cdf(3)               // probability of 3 or fewer successes
dist.quantileInt(0.5)     // median number of successes
dist.mean                 // 2.857... (10 * 2 / (2 + 5))
dist.variance             // 3.316... (overdispersed relative to binomial)
dist.sample(Random(42))   // a single random draw

Constructors

BetaBinomialDistribution

constructor(trials: Int, alpha: Double, beta: Double)

Properties

alpha

val alpha: Double

the first shape parameter of the underlying Beta distribution. Must be positive.

beta

val beta: Double

the second shape parameter of the underlying Beta distribution. Must be positive.

entropy

open override val entropy: Double

Returns the Shannon entropy of this beta-binomial distribution in nats.

kurtosis

open override val kurtosis: Double

Returns the excess kurtosis (Fisher definition) of this beta-binomial distribution.

mean

open override val mean: Double

The mean of this distribution, equal to n * alpha / (alpha + beta).

skewness

open override val skewness: Double

The skewness of this distribution, computed from the shape parameters and trial count. Returns Double.NaN when trials is zero.

trials

val trials: Int

the number of independent trials. Must be non-negative.

variance

open override val variance: Double

The variance of this distribution, overdispersed relative to the binomial by a factor of (alpha + beta + n) / (alpha + beta + 1).

Functions

cdf

open override fun cdf(k: Int): Double

Returns the cumulative distribution function value at k for this beta-binomial distribution.

logPmf

open override fun logPmf(k: Int): Double

Returns the natural logarithm of the probability mass at k for this beta-binomial distribution.

pmf

open override fun pmf(k: Int): Double

Returns the probability of exactly k successes in this beta-binomial distribution.

quantileInt

open override fun quantileInt(p: Double): Int

Returns the quantile (inverse CDF) for the given probability p as an integer.

sample

open override fun sample(random: Random): Int

Draws a single random integer from this beta-binomial distribution using compound sampling.

open override fun sf(k: Int): Double

Returns the survival function value at k for this beta-binomial distribution.