obitools4/autodoc/docmd/pkg/obistats/betabinom.md

Beta-Binomial Distribution Implementation in obistats

This Go package provides a complete statistical implementation of the Beta-Binomial distribution, a compound discrete probability distribution where the success probability of a Binomial distribution follows a Beta distribution.

Core Features

• Struct Definition:
  BetaBinomial encapsulates the distribution parameters: number of trials (N > 0) and Beta shape parameters Alpha and Beta, both strictly positive. Optional random source (Src) supports reproducible sampling.

• Probability Mass Function (PMF):

  • LogProb(x) computes the natural logarithm of the PMF at integer x ∈ [0, N].
  • Prob(x) returns the PMF value via exponentiation.

• Cumulative Distribution Function (CDF):

  • LogCDF(x) evaluates the log-CDF using an analytical expression involving:
    • Log-binomial coefficient (Lchoose)
    • Log-beta function (mathext.Lbeta)
    • Generalized hypergeometric function HypPFQ (via scientificgo.org/special).
  • CDF(x) returns the standard CDF as exp(LogCDF(x)).

• Statistical Moments:

  • Mean: N \cdot \frac{\alpha}{\alpha + \beta}
  • Variance: N \cdot \frac{\alpha \beta (\!N + \alpha + \beta\!)}{(\alpha+\beta)^2 (\alpha+\beta+1)}
  • Standard deviation: square root of variance.

• Mode:
  Returns the most probable count. Special cases handled:

  • NaN if both \alpha, \beta \leq 1
  • 0 if only \alpha \leq 1
  • N if only \beta \leq 1

• Utility Methods:

  • LogCDFTable(x) builds a cumulative log-probability table up to x, useful for fast lookup or numerical stability.
  • NumParameters() returns the number of distribution parameters (3: N, \alpha, \beta).

• Input Validation:
  Panics on invalid parameters (non-positive N, \alpha, or \beta), ensuring correctness.

This module supports high-precision statistical computations using specialized mathematical libraries (gonum.org/v1/gonum/mathext, scientificgo.org/special).