Module peroxide::statistics::dist

Probabilistic distributions

Probability Distribution

• There are some famous pdf in Peroxide (not checked pdfs will be implemented soon)
  • Bernoulli
  • Binomial
  • Beta
  • Dirichlet
  • Gamma
  • Normal
  • Student’s t
  • Uniform
  • Weighted Uniform
• There are two enums to represent probability distribution
  • OPDist<T> : One parameter distribution (Bernoulli)
  • TPDist<T> : Two parameter distribution (Uniform, Normal, Beta, Gamma)
    • T: PartialOrd + SampleUniform + Copy + Into<f64>
• There are some traits for pdf
  • RNG trait - extract sample & calculate pdf
  • Statistics trait - already shown above

RNG trait

• RNG trait is composed of two fields
  • sample: Extract samples
  • sample_with_rng: Extract samples with specific rng
  • pdf : Calculate pdf value at specific point

  use rand::{Rng, distributions::uniform::SampleUniform};
  pub trait RNG {
      /// Extract samples of distributions
      fn sample(&self, n: usize) -> Vec<f64>;
  
      /// Extract samples of distributions with rng
      fn sample_with_rng<R: Rng>(&self, rng: &mut R, n: usize) -> Vec<f64>;
  
      /// Probability Distribution Function
      ///
      /// # Type
      /// `f64 -> f64`
      fn pdf<S: PartialOrd + SampleUniform + Copy + Into<f64>>(&self, x: S) -> f64;
  }

Bernoulli Distribution

• Definition $$ \text{Bern}(x | \mu) = \mu^x (1-\mu)^{1-x} $$

• Representative value

  • Mean: $\mu$
  • Var : $\mu(1 - \mu)$

• In peroxide, to generate $\text{Bern}(x | \mu)$, use simple traits

  1. Generate $U \sim \text{Unif}(0, 1)$
  2. If $U \leq \mu$, then $X = 1$ else $X = 0$

• Usage is very simple

  use peroxide::fuga::*;
  
  fn main() {
      let mut rng = smallrng_from_seed(42);
      let b = Bernoulli(0.1);                   // Bern(x | 0.1)
      b.sample(100).print();                    // Generate 100 samples
      b.sample_with_rng(&mut rng, 100).print(); // Generate 100 samples with specific rng
      b.pdf(0).print();                         // 0.9
      b.mean().print();                         // 0.1
      b.var().print();                          // 0.09 (approximately)
      b.sd().print();                           // 0.3  (approximately)
  }

Uniform Distribution

• Definition $$\text{Unif}(x | a, b) = \begin{cases} \frac{1}{b - a} & x \in [a,b]\\ 0 & \text{otherwise} \end{cases}$$

• Representative value

  • Mean: $\frac{a + b}{2}$
  • Var : $\frac{1}{12}(b-a)^2$

• To generate uniform random number, Peroxide uses rand crate

• Caution: Uniform(T, T) generates T type samples (only for Uniform)

  use peroxide::fuga::*;
  
  fn main() {
      // Uniform(start, end)
      let a = Uniform(0f64, 1f64); // It will generate `f64` samples.
      a.sample(100).print();
      a.pdf(0.2).print();
      a.mean().print();
      a.var().print();
      a.sd().print();
  }

Normal Distribution

• Definition $$\mathcal{N}(x | \mu, \sigma^2) = \frac{1}{\sqrt{2\pi \sigma^2}} \exp{\left( - \frac{(x - \mu)^2}{2\sigma^2}\right)}$$
• Representative value
  • Mean: $\mu$
  • Var: $\sigma^2$
• To generate normal random number, there are two famous algorithms
  • Marsaglia-Polar method
  • Ziggurat traits
• In peroxide (after ver 0.19.1), use rand_distr to generate random normal samples.
• In peroxide, main traits is Ziggurat - most efficient traits to generate random normal samples.
  • Code is based on a C implementation by Jochen Voss.

  use peroxide::fuga::*;
  
  fn main() {
      // Normal(mean, std)
      let a = Normal(0, 1); // Standard normal
      a.sample(100).print();
      a.pdf(0).print(); // Maximum probability
      a.mean().print();
      a.var().print();
      a.sd().print();
  }

Beta Distribution

• Definition $$\text{Beta}(x | \alpha, \beta) = \frac{1}{\text{B}(\alpha, \beta)} x^{\alpha-1} (1-x)^{\beta-1}$$ where $\text{B}(\alpha, \beta) = \frac{\Gamma(\alpha)\Gamma(\beta)}{\Gamma(\alpha+\beta)}$ is the Beta function.

• Representative value

  • Mean: $\frac{\alpha}{\alpha+\beta}$
  • Var: $\frac{\alpha\beta}{(\alpha+\beta)^2(\alpha+\beta+1)}$

• To generate beta random samples, Peroxide uses the rand_distr::Beta distribution from the rand_distr crate.

  use peroxide::fuga::*;
  
  fn main() {
      // Beta(alpha, beta)
      let a = Beta(2.0, 5.0);
      a.sample(100).print();
      a.pdf(0.3).print();
      a.mean().print();
      a.var().print();
  }

Gamma Distribution

• Definition $$\text{Gamma}(x | \alpha, \beta) = \frac{\beta^\alpha}{\Gamma(\alpha)} x^{\alpha-1} e^{-\beta x}$$ where $\Gamma(\alpha) = \int_0^\infty x^{\alpha-1} e^{-x} dx$ is the Gamma function.

• Representative value

  • Mean: $\frac{\alpha}{\beta}$
  • Var: $\frac{\alpha}{\beta^2}$

• To generate gamma random samples, Peroxide uses the rand_distr::Gamma distribution from the rand_distr crate.

  use peroxide::fuga::*;
  
  fn main() {
      // Gamma(shape, scale)
      let a = Gamma(2.0, 1.0);
      a.sample(100).print();
      a.pdf(1.5).print();
      a.mean().print();
      a.var().print();
  }

Binomial Distribution

• Definition $$\text{Binom}(k | n, p) = \binom{n}{k} p^k (1-p)^{n-k}$$ where $\binom{n}{k} = \frac{n!}{k!(n-k)!}$ is the binomial coefficient.

• Representative value

  • Mean: $np$
  • Var: $np(1-p)$

• To generate binomial random samples, Peroxide uses the rand_distr::Binomial distribution from the rand_distr crate.

  use peroxide::fuga::*;
  
  fn main() {
      // Binomial(n, p)
      let a = Binomial(10, 0.3);
      a.sample(100).print();
      a.pdf(3).print();
      a.mean().print();
      a.var().print();
  }

Student’s t Distribution

• Definition $$\text{StudentT}(x | \nu) = \frac{\Gamma(\frac{\nu+1}{2})}{\sqrt{\nu\pi},\Gamma(\frac{\nu}{2})} \left(1+\frac{x^2}{\nu} \right)^{-\frac{\nu+1}{2}}$$ where $\nu$ is the degrees of freedom and $\Gamma$ is the Gamma function.

• Representative value

  • Mean: 0 (for $\nu > 1$)
  • Var: $\frac{\nu}{\nu-2}$ (for $\nu > 2$)

• To generate Student’s t random samples, Peroxide uses the rand_distr::StudentT distribution from the rand_distr crate.

  use peroxide::fuga::*;
  
  fn main() {
      // StudentT(nu)
      let a = StudentT(5.0);
      a.sample(100).print();
      a.pdf(1.0).print();
      a.mean().print(); // Undefined for nu <= 1
      a.var().print();  // Undefined for nu <= 2
  }

Weighted Uniform Distribution

• Definition $$\text{WUnif}(x | \mathbf{W}, \mathcal{I}) = \frac{1}{\sum_{j=1}^n w_j \mu(I_j)} \sum_{i=1}^n w_i \mathbb{1}_{I_i}(x)$$

  • $\mathbf{W} = (w_i)$: Weights
  • $\mathcal{I} = \{I_i\}$: Intervals
  • $\mu(I_i)$: Measure of $I_i$
  • $\mathbb{1}_{I_i}(x)$: Indicator function

• Reference

  • Piecewise Rejection Sampling

Re-exports

• pub use self::OPDist::*;
• pub use self::TPDist::*;

Structs

• WeightedUniform

Enums

• OPDist
  One parameter distribution
• TPDist
  Two parameter distribution
• WeightedUniformError

Traits

• ParametricDist
  Extract parameter
• RNG
  Random Number Generator trait