Documentation binomial to hypergeometric

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`.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/binomial.svg"/>
+///
 /// # 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 {

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`.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/cauchy.svg"/>
+///
 /// # 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<F>

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.
+/// 
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/dirichlet.svg"/>
 ///
 /// # Example
 ///

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`.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential_exp1.svg"/>
+///
 /// 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<f64> 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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential.svg"/>
+///
 /// # Example
 ///
 /// ```
@@ -91,12 +105,6 @@ impl Distribution<f64> 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<F>

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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/frechet.svg"/>
 ///
 /// # Example
 /// ```

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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/gamma.svg"/>
+///
 /// 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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/chi_squared.svg"/>
+///
 /// # 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`.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/fisher_f.svg"/>
+///
 /// # 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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/student_t.svg"/>
 ///
 /// # Example
 ///
@@ -560,7 +589,21 @@ struct BC<N> {
     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 `β`.
+/// 
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/beta.svg"/>
 ///
 /// # Example
 ///

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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/geometric.svg"/>
+///
 /// # Example
 ///
 /// ```
@@ -145,6 +152,12 @@ impl Distribution<u64> for Geometric
 /// 
 /// Implemented via iterated
 /// [`Rng::gen::<u64>().leading_zeros()`](Rng::gen::<u64>().leading_zeros()).
+///
+/// # Plot
+///
+/// The following plot illustrates the standard geometric distribution.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/standard_geometric.svg"/>
 /// 
 /// # Example
 /// ```

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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/gumbel.svg"/>
 ///
 /// # Example
 /// ```

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.
+///
+/// <img src="https://raw.githubusercontent.com/rust-random/charts/main/charts/hypergeometric.svg"/>
 /// 
 /// # Example
 ///