Struct HyperGeometric 

pub struct HyperGeometric { /* private fields */ }

The Hypergeometric Distribution

Description

Density, distribution function, quantile function and random generation for the hypergeometric distribution.

Arguments

• Quantiles representing the number of white balls drawn without replacement from an urn which contains both black and white balls.
• m: the number of white balls in the urn.
• n: the number of black balls in the urn.
• k: the number of balls drawn from the urn.
• p: probability, it must be between 0 and 1.

Details

The hypergeometric distribution is used for sampling without replacement. The density of this distribution with parameters m, n and k (named Np, N-Np, and n, respectively in the reference below) is given by

$ p(x) = {m \choose x} {n \choose k-x} / {m+n \choose k} $

for x = 0, …, k.

Note that p(x) is non-zero only for max(0, k-n) <= x <= min(k, m).

With $p := \frac{m}{m+n}$ (hence $Np = N \times p$ in the reference’s notation), the first two moments are mean

$ E[X] = μ = k p $

and variance

$ Var(X) = k p (1 - p) * \frac{m+n-k}{m+n-1} $,

which shows the closeness to the Binomial(k,p) (where the hypergeometric has smaller variance unless k = 1).

The quantile is defined as the smallest value x such that F(x) ≥ p, where F is the distribution function.

If one of m, n, k, exceeds .Machine$integer.max, currently the equivalent of qhyper(runif(nn), m,n,k) is used, when a binomial approximation may be considerably more efficient.

Density Plot

let hyper_geom = HyperGeometricBuilder::new().build().unwrap();
let x = <[f64]>::sequence_by(-0.5, 1.5, 0.001);
let y = x
    .iter()
    .map(|x| hyper_geom.density(x).unwrap())
    .collect::<Vec<_>>();

let root = SVGBackend::new("density.svg", (1024, 768)).into_drawing_area();
Plot::new()
    .with_options(PlotOptions {
        x_axis_label: "x".to_string(),
        y_axis_label: "density".to_string(),
        ..Default::default()
    })
    .with_plottable(Line {
        x,
        y,
        color: BLACK,
        ..Default::default()
    })
    .plot(&root)
    .unwrap();

Source

dhyper computes via binomial probabilities, using code contributed by Catherine Loader (see dbinom).

phyper is based on calculating dhyper and phyper(…)/dhyper(…) (as a summation), based on ideas of Ian Smith and Morten Welinder.

qhyper is based on inversion.

rhyper is based on a corrected version of

Kachitvichyanukul, V. and Schmeiser, B. (1985). Computer generation of hypergeometric random variates. Journal of Statistical Computation and Simulation, 22, 127–145.

References

Johnson, N. L., Kotz, S., and Kemp, A. W. (1992) Univariate Discrete Distributions, Second Edition. New York: Wiley.

See Also

Distributions for other standard distributions.

Examples

These are not equal, but the error is very small

let m = 10;
let n = 7;
let k = 8;

let x = (0..=k + 1).collect::<Vec<_>>();

let hyper = HyperGeometricBuilder::new()
    .with_group_1(m)
    .with_group_2(n)
    .with_number_drawn(k)
    .build()
    .unwrap();
let p = x
    .iter()
    .map(|x| hyper.probability(x, true).unwrap())
    .collect::<Vec<_>>();
let d = x
    .iter()
    .map(|x| hyper.density(x).unwrap())
    .collect::<Vec<_>>()
    .cumsum();
let diff = p
    .iter()
    .zip(d.iter())
    .map(|(p, d)| p - d)
    .collect::<Vec<_>>();

println!("{p:?}");
println!("{d:?}");
println!("{diff:?}");

Trait Implementations

impl Distribution for HyperGeometric

fn density<R>(&self, x: R) -> NonNan<f64>

where R: Into<NonNan<f64>>,

The density of the values at a given point

fn log_density<R>(&self, x: R) -> NonNan<f64>

where R: Into<NonNan<f64>>,

The logarithmic density of the values at a given point

fn probability<R>( &self, q: R, lower_tail: bool, ) -> GreaterThanEqualZero<LessThanEqualOne<NonNan<f64>>>

where R: Into<NonNan<f64>>,

PDF; The probability that a value is found in a distribution (inverse of quantile)

fn log_probability<R>( &self, q: R, lower_tail: bool, ) -> LessThanEqualZero<NonNan<f64>>

where R: Into<NonNan<f64>>,

log(PDF); The logarithmic probability that a value is found in a distribution (inverse of quantile)

fn quantile<P>(&self, p: P, lower_tail: bool) -> NonNan<f64>

where P: Into<GreaterThanEqualZero<LessThanEqualOne<NonNan<f64>>>>,

The value in the distribution that is associated with a probability (inverse of probability)

fn log_quantile<LP>(&self, p: LP, lower_tail: bool) -> NonNan<f64>

where LP: Into<LessThanEqualZero<NonNan<f64>>>,

The logarithmic value in the distribution that is associated with a probability (inverse of probability)

fn random_sample<R>(&self, rng: &mut R) -> NonNan<f64>

where R: RNG,

Generates a random sample from the distribution