Add distribution graphs to documentation

rand_distr/Cargo.toml

@@ -14,7 +14,7 @@ keywords = ["random", "rng", "distribution", "probability"]
 categories = ["algorithms", "no-std"]
 edition = "2021"
 rust-version = "1.61"
-include = ["src/", "LICENSE-*", "README.md", "CHANGELOG.md", "COPYRIGHT"]
+include = ["/src", "LICENSE-*", "README.md", "CHANGELOG.md", "COPYRIGHT"]
 
 [package.metadata.docs.rs]
 rustdoc-args = ["--cfg docsrs", "--generate-link-to-definition"]

rand_distr/src/binomial.rs

@@ -17,10 +17,24 @@ use num_traits::Float;
 use rand::Rng;
 
 /// 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`.
+///
+/// ![Binomial distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/binomial.svg)
+///
 /// # Example
 ///
 /// ```

rand_distr/src/cauchy.rs

@@ -16,12 +16,25 @@ use rand::Rng;
 
 /// 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`.
+///
+/// ![Cauchy distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/cauchy.svg)
+///
 /// # Example
 ///
 /// ```

rand_distr/src/dirichlet.rs

@@ -190,6 +190,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.
+/// 
+/// ![Dirichlet distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/dirichlet.png)
 ///
 /// # Example
 ///

rand_distr/src/exponential.rs

@@ -21,6 +21,12 @@ use rand::Rng;
 ///
 /// See `Exp` for the general exponential distribution.
 ///
+/// # Plot
+///
+/// The following plot illustrates the exponential distribution with `λ = 1`.
+///
+/// ![Exponential distribution](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.
+///
+/// ![Exponential distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential.svg)
+///
 /// # Example
 ///
 /// ```

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.
+///
+/// ![Fréchet distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/frechet.svg)
 ///
 /// # Example
 /// ```

rand_distr/src/gamma.rs

@@ -24,7 +24,7 @@ use rand::Rng;
 #[cfg(feature = "serde1")]
 use serde::{Deserialize, Serialize};
 
-/// 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::{Deserialize, Serialize};
 /// 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.
+///
+/// ![Gamma distribution](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
@@ -270,6 +277,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.
+///
+/// ![Chi-squared distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/chi_squared.svg)
+///
 /// # Example
 ///
 /// ```
@@ -279,6 +293,12 @@ where
 /// let v = chi.sample(&mut rand::thread_rng());
 /// println!("{} is from a χ²(11) distribution", v)
 /// ```
+///
+/// # Diagram
+///
+/// The diagram shows the chi-squared distribution with varying degrees of freedom.
+///
+/// ![Chi-squared distribution]()
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))]
 pub struct ChiSquared<F>
@@ -368,12 +388,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`.
+///
+/// ![F-distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/fisher_f.svg)
+///
 /// # Example
 ///
 /// ```
@@ -457,8 +483,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.
+///
+/// ![T-distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/student_t.svg)
 ///
 /// # Example
 ///
@@ -545,7 +586,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 `β`.
+/// 
+/// ![Beta distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/beta.svg)
 ///
 /// # Example
 ///

rand_distr/src/geometric.rs

@@ -18,6 +18,13 @@ use rand::Rng;
 /// 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.
+///
+/// ![Geometric distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/geometric.svg)
+///
 /// # Example
 ///
 /// ```
@@ -149,6 +156,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.
+///
+/// ![Standard Geometric distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/standard_geometric.svg)
+///
 /// # Example
 /// ```
 /// use rand::prelude::*;

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.
+///
+/// ![Gumbel distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/gumbel.svg)
 ///
 /// # Example
 /// ```

rand_distr/src/hypergeometric.rs

@@ -39,6 +39,14 @@ enum SamplingMethod {
 /// 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.
+///
+/// ![Hypergeometric distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/hypergeometric.svg)
+///
 /// # Example
 ///
 /// ```

rand_distr/src/inverse_gaussian.rs

@@ -25,6 +25,25 @@ impl fmt::Display for Error {
 impl std::error::Error for Error {}
 
 /// The [inverse Gaussian distribution](https://en.wikipedia.org/wiki/Inverse_Gaussian_distribution)
+/// 
+/// This is a continuous probability distribution with two parameters, `mean` and `shape`,
+/// defined for `x > 0`.
+/// It is also known as the Wald distribution.
+/// 
+/// # Plot
+/// 
+/// The following plot shows the inverse Gaussian distribution with various parameters.
+/// 
+/// ![Inverse Gaussian distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/inverse_gaussian.svg)
+/// 
+/// # Example
+/// ```
+/// use rand_distr::{InverseGaussian, Distribution};
+///
+/// let inv_gauss = InverseGaussian::new(1.0, 2.0).unwrap();
+/// let v = inv_gauss.sample(&mut rand::thread_rng());
+/// println!("{} is from a inverse Gaussian(1, 2) distribution", v);
+/// ```
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct InverseGaussian<F>

rand_distr/src/normal.rs

@@ -19,14 +19,15 @@ use rand::Rng;
 /// `N(0, 1)` (a.k.a. a standard normal, or Gaussian). This is equivalent to
 /// `Normal::new(0.0, 1.0)` but faster.
 ///
-/// See `Normal` for the general normal distribution.
+/// See [`Normal`] for the general normal distribution.
 ///
 /// Implemented via the ZIGNOR variant[^1] of the Ziggurat method.
 ///
-/// [^1]: Jurgen A. Doornik (2005). [*An Improved Ziggurat Method to
-///       Generate Normal Random Samples*](
-///       https://www.doornik.com/research/ziggurat.pdf).
-///       Nuffield College, Oxford
+/// # Plot
+///
+/// The following diagram shows the standard normal distribution.
+///
+/// ![Standard normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/normal.svg)
 ///
 /// # Example
 /// ```
@@ -36,6 +37,11 @@ use rand::Rng;
 /// let val: f64 = thread_rng().sample(StandardNormal);
 /// println!("{}", val);
 /// ```
+///
+/// [^1]: Jurgen A. Doornik (2005). [*An Improved Ziggurat Method to
+///       Generate Normal Random Samples*](
+///       https://www.doornik.com/research/ziggurat.pdf).
+///       Nuffield College, Oxford
 #[derive(Clone, Copy, Debug)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct StandardNormal;
@@ -100,6 +106,13 @@ impl Distribution<f64> for StandardNormal {
 /// Note that [`StandardNormal`] is an optimised implementation for mean 0, and
 /// standard deviation 1.
 ///
+/// # Plot
+///
+/// The following diagram shows the normal distribution with various parameters.
+/// [`StandardNormal`] is illustrated with `μ = 0` and `σ = 1`.
+///
+/// ![Normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/normal.svg)
+///
 /// # Example
 ///
 /// ```
@@ -110,8 +123,6 @@ impl Distribution<f64> for StandardNormal {
 /// let v = normal.sample(&mut rand::thread_rng());
 /// println!("{} is from a N(2, 9) distribution", v)
 /// ```
-///
-/// [`StandardNormal`]: crate::StandardNormal
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Normal<F>