From 741d82e7fe57e838f4d6a2436ea03986d520900f Mon Sep 17 00:00:00 2001 From: Michael Dyer Date: Thu, 11 Apr 2024 18:39:40 +0200 Subject: [PATCH] Documentation binomial to hypergeometric --- rand_distr/src/binomial.rs | 23 ++++++++---- rand_distr/src/cauchy.rs | 19 +++++++--- rand_distr/src/dirichlet.rs | 6 +++ rand_distr/src/exponential.rs | 20 +++++++--- rand_distr/src/frechet.rs | 13 ++++++- rand_distr/src/gamma.rs | 63 +++++++++++++++++++++++++++----- rand_distr/src/geometric.rs | 13 +++++++ rand_distr/src/gumbel.rs | 17 +++++++-- rand_distr/src/hypergeometric.rs | 8 ++++ 9 files changed, 148 insertions(+), 34 deletions(-) diff --git a/rand_distr/src/binomial.rs b/rand_distr/src/binomial.rs index c92b9c2395..edb85b152c 100644 --- a/rand_distr/src/binomial.rs +++ b/rand_distr/src/binomial.rs @@ -17,10 +17,24 @@ use core::cmp::Ordering; use num_traits::Float; /// The binomial distribution `Binomial(n, p)`. +/// +/// The binomial distribution is a discrete probability distribution with +/// parameters `n` (number of trials) and `p` (probability of success). +/// Given some number of successes `k`, `Binomial(n, p)` describes the +/// probability of having `k` successes in `n` independent trials, +/// each of which has probability `p` to succeed. /// -/// This distribution has density function: +/// This distribution follows the density function: /// `f(k) = n!/(k! (n-k)!) p^k (1-p)^(n-k)` for `k >= 0`. /// +/// # Plot +/// +/// The following plot of the binomial distribution illustrates the +/// probability of `k` successes out of `n = 10` trials with `p = 0.2` +/// and `p = 0.6` for `0 <= k <= n`. +/// +/// +/// /// # Example /// /// ``` @@ -30,13 +44,6 @@ use num_traits::Float; /// let v = bin.sample(&mut rand::thread_rng()); /// println!("{} is from a binomial distribution", v); /// ``` -/// -/// # Diagram -/// -/// The following diagram of the binomial distribution illustrates the probability of -/// `k` successes out of `n = 10` trials with `p = 0.2` and `p = 0.6` for each `k` from 0 to `n`. -/// -/// ![Binomial distribution]() #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))] pub struct Binomial { diff --git a/rand_distr/src/cauchy.rs b/rand_distr/src/cauchy.rs index 496de47b09..89ad1fd5df 100644 --- a/rand_distr/src/cauchy.rs +++ b/rand_distr/src/cauchy.rs @@ -16,12 +16,25 @@ use core::fmt; /// The Cauchy distribution `Cauchy(median, scale)`. /// +/// The Cauchy distribution is a continuous probability distribution with +/// parameters `median` and `scale`. +/// /// This distribution has a density function: /// `f(x) = 1 / (pi * scale * (1 + ((x - median) / scale)^2))` /// /// Note that at least for `f32`, results are not fully portable due to minor /// differences in the target system's *tan* implementation, `tanf`. /// +/// # Plot +/// +/// The plot illustrates the Cauchy distribution with various parameters. +/// Note how the `median` parameter `x₀` shifts the distribution along the x-axis, +/// and the `scale` parameter `γ` changes the density around the median. +/// +/// The standard Cauchy distribution is the special case with `median = 0` and `scale = 1`. +/// +/// +/// /// # Example /// /// ``` @@ -31,12 +44,6 @@ use core::fmt; /// let v = cau.sample(&mut rand::thread_rng()); /// println!("{} is from a Cauchy(2, 5) distribution", v); /// ``` -/// -/// # Diagram -/// -/// The diagram shows the Cauchy distribution with various parameters. -/// -/// ![Cauchy distribution]() #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))] pub struct Cauchy diff --git a/rand_distr/src/dirichlet.rs b/rand_distr/src/dirichlet.rs index 413c00476a..ee425c24cf 100644 --- a/rand_distr/src/dirichlet.rs +++ b/rand_distr/src/dirichlet.rs @@ -191,6 +191,12 @@ where /// The Dirichlet distribution is a family of continuous multivariate /// probability distributions parameterized by a vector alpha of positive reals. /// It is a multivariate generalization of the beta distribution. +/// +/// # Plot +/// +/// The following plot illustrates the Dirichlet distribution with various parameters. +/// +/// /// /// # Example /// diff --git a/rand_distr/src/exponential.rs b/rand_distr/src/exponential.rs index 71fd9a07ad..701efa7bfb 100644 --- a/rand_distr/src/exponential.rs +++ b/rand_distr/src/exponential.rs @@ -21,6 +21,12 @@ use core::fmt; /// /// See `Exp` for the general exponential distribution. /// +/// # Plot +/// +/// The following plot illustrates the exponential distribution with `λ = 1`. +/// +/// +/// /// Implemented via the ZIGNOR variant[^1] of the Ziggurat method. The exact /// description in the paper was adjusted to use tables for the exponential /// distribution rather than normal. @@ -82,6 +88,14 @@ impl Distribution for Exp1 { /// /// Note that [`Exp1`](crate::Exp1) is an optimised implementation for `lambda = 1`. /// +/// # Plot +/// +/// The following plot illustrates the exponential distribution with +/// various values of `lambda`. +/// The `lambda` parameter controls the rate of decay as `x` approaches infinity. +/// +/// +/// /// # Example /// /// ``` @@ -91,12 +105,6 @@ impl Distribution for Exp1 { /// let v = exp.sample(&mut rand::thread_rng()); /// println!("{} is from a Exp(2) distribution", v); /// ``` -/// -/// # Diagram -/// -/// The diagram shows the exponential distribution with `λ = 0.5`, `λ = 1` and `λ = 2`. -/// -/// ![Exponential distribution]() #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))] pub struct Exp diff --git a/rand_distr/src/frechet.rs b/rand_distr/src/frechet.rs index 781b7af164..bf114d3838 100644 --- a/rand_distr/src/frechet.rs +++ b/rand_distr/src/frechet.rs @@ -17,7 +17,18 @@ use rand::Rng; /// /// This distribution has density function: /// `f(x) = [(x - μ) / σ]^(-1 - α) exp[-(x - μ) / σ]^(-α) α / σ`, -/// where `μ` is the location parameter, `σ` the scale parameter, and `α` the shape parameter. +/// where `μ` is the location parameter, `σ` the scale parameter, +/// and `α` the shape parameter. +/// +/// # Plot +/// +/// The plot shows the Fréchet distribution with various parameters. +/// Note how the location parameter `μ` shifts the distribution along the x-axis, +/// the scale parameter `σ` stretches or compresses the distribution along the x-axis, +/// and the shape parameter `α` changes the severity of the increase in density +/// towards the lower bound. +/// +/// /// /// # Example /// ``` diff --git a/rand_distr/src/gamma.rs b/rand_distr/src/gamma.rs index 59bdeaceee..7188d51e73 100644 --- a/rand_distr/src/gamma.rs +++ b/rand_distr/src/gamma.rs @@ -24,7 +24,7 @@ use core::fmt; #[cfg(feature = "serde1")] use serde::{Serialize, Deserialize}; -/// The Gamma distribution `Gamma(shape, scale)` distribution. +/// The Gamma distribution `Gamma(shape, scale)`. /// /// The density function of this distribution is /// @@ -35,6 +35,13 @@ use serde::{Serialize, Deserialize}; /// where `Γ` is the Gamma function, `k` is the shape and `θ` is the /// scale and both `k` and `θ` are strictly positive. /// +/// # Plot +/// +/// The following plot illustrates the Gamma distribution with +/// various parameters. +/// +/// +/// /// The algorithm used is that described by Marsaglia & Tsang 2000[^1], /// falling back to directly sampling from an Exponential for `shape /// == 1`, and using the boosting technique described in that paper for @@ -50,12 +57,6 @@ use serde::{Serialize, Deserialize}; /// println!("{} is from a Gamma(2, 5) distribution", v); /// ``` /// -/// # Diagram -/// -/// The diagram shows the Gamma distribution with varying shape and scale. -/// -/// ![Gamma distribution]() -/// /// [^1]: George Marsaglia and Wai Wan Tsang. 2000. "A Simple Method for /// Generating Gamma Variables" *ACM Trans. Math. Softw.* 26, 3 /// (September 2000), 363-372. @@ -277,6 +278,13 @@ where /// `k`, this uses the equivalent characterisation /// `χ²(k) = Gamma(k/2, 2)`. /// +/// # Plot +/// +/// The plot shows the chi-squared distribution with varying degrees +/// of freedom. +/// +/// +/// /// # Example /// /// ``` @@ -382,12 +390,18 @@ where } } -/// The Fisher F distribution `F(m, n)`. +/// The Fisher F-distribution `F(m, n)`. /// /// This distribution is equivalent to the ratio of two normalised /// chi-squared distributions, that is, `F(m,n) = (χ²(m)/m) / /// (χ²(n)/n)`. /// +/// # Plot +/// +/// The plot shows the F-distribution with various values of `m` and `n`. +/// +/// +/// /// # Example /// /// ``` @@ -472,8 +486,23 @@ where } } -/// The Student t distribution, `t(nu)`, where `nu` is the degrees of +/// The Student t-distribution, `t(nu)`, where `nu` is the degrees of /// freedom. +/// +/// This is a continuous probability distribution that arises when +/// estimating the mean of a normally-distributed population in +/// situations where the sample size is small and the population's +/// standard deviation is unknown. +/// +/// For `nu = 1`, this is equivalent to the standard [`Cauchy`](crate::Cauchy) distribution, +/// and as `nu` diverges to infinity, `t(nu)` converges to +/// [`StandardNormal`](crate::StandardNormal). +/// +/// # Plot +/// +/// The plot shows the t-distribution with various degrees of freedom. +/// +/// /// /// # Example /// @@ -560,7 +589,21 @@ struct BC { kappa2: N, } -/// The Beta distribution with shape parameters `alpha` and `beta`. +/// The Beta distribution `Beta(alpha, beta)`. +/// +/// The Beta distribution is a continuous probability distribution +/// defined on the interval `[0, 1]`. It is the conjugate prior for the +/// parameter `p` of the [`Binomial`][crate::Binomial] distribution. +/// +/// It has two shape parameters `α` and `β` which control the shape of +/// the distribution. The distribution is symmetric when `α = β`. +/// +/// # Plot +/// +/// The plot shows the Beta distribution with various combinations +/// of `α` and `β`. +/// +/// /// /// # Example /// diff --git a/rand_distr/src/geometric.rs b/rand_distr/src/geometric.rs index 5204013a5b..9c3ce09a21 100644 --- a/rand_distr/src/geometric.rs +++ b/rand_distr/src/geometric.rs @@ -18,6 +18,13 @@ use num_traits::Float; /// Note that [`StandardGeometric`](crate::StandardGeometric) is an optimised /// implementation for `p = 0.5`. /// +/// # Plot +/// +/// The following plot illustrates the geometric distribution for various values of `p`. +/// Note how the higher `p` is, the more likely it is to have a success early on. +/// +/// +/// /// # Example /// /// ``` @@ -145,6 +152,12 @@ impl Distribution for Geometric /// /// Implemented via iterated /// [`Rng::gen::().leading_zeros()`](Rng::gen::().leading_zeros()). +/// +/// # Plot +/// +/// The following plot illustrates the standard geometric distribution. +/// +/// /// /// # Example /// ``` diff --git a/rand_distr/src/gumbel.rs b/rand_distr/src/gumbel.rs index 4a83658692..8001b0b8e8 100644 --- a/rand_distr/src/gumbel.rs +++ b/rand_distr/src/gumbel.rs @@ -13,11 +13,22 @@ use core::fmt; use num_traits::Float; use rand::Rng; -/// Samples floating-point numbers according to the Gumbel distribution +/// The Gumbel distribution `Gumbel(location, scale)`. +/// +/// The Gumbel distribution is a continuous probability distribution with +/// location parameter `μ` and scale parameter `σ`. /// /// This distribution has density function: -/// `f(x) = exp(-(z + exp(-z))) / σ`, where `z = (x - μ) / σ`, -/// `μ` is the location parameter, and `σ` the scale parameter. +/// `f(x) = exp(-(z + exp(-z))) / σ`, where `z = (x - μ) / σ`. +/// +/// # Plot +/// +/// The following plot illustrates the Gumbel distribution with various parameters. +/// Note how the location parameter `μ` shifts the distribution along the x-axis, +/// and the scale parameter `σ` changes the density around `μ`. +/// Note also the asymptotic behavior of the distribution towards the right. +/// +/// /// /// # Example /// ``` diff --git a/rand_distr/src/hypergeometric.rs b/rand_distr/src/hypergeometric.rs index 73a8e91c75..9f5e664514 100644 --- a/rand_distr/src/hypergeometric.rs +++ b/rand_distr/src/hypergeometric.rs @@ -35,6 +35,14 @@ enum SamplingMethod { /// The [binomial distribution](crate::Binomial) is the analogous distribution /// for sampling with replacement. It is a good approximation when the population /// size is much larger than the sample size. +/// +/// # Plot +/// +/// The following plot of the hypergeometric distribution illustrates the probability of drawing +/// `k` successes in `n = 10` draws from a population of `N = 50` items, of which either `K = 12` +/// or `K = 25` are successes. +/// +/// /// /// # Example ///