Add distribution plots to rand_distr documentation (rust-random#1434)

Author: MichaelOwenDyer

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+- Add plots for `rand_distr` distributions to documentation (#1434)
+
 ## [0.5.0-alpha.1] - 2024-03-18
 - Target `rand` version `0.9.0-alpha.1`
 

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"]

src/binomial.rs

@@ -7,7 +7,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The binomial distribution.
+//! The binomial distribution `Binomial(n, p)`.
 
 use crate::{Distribution, Uniform};
 use core::cmp::Ordering;
@@ -16,11 +16,24 @@ use core::fmt;
 use num_traits::Float;
 use rand::Rng;
 
-/// The binomial distribution `Binomial(n, p)`.
+/// The [binomial distribution](https://en.wikipedia.org/wiki/Binomial_distribution) `Binomial(n, p)`.
+///
+/// The binomial distribution is a discrete probability distribution
+/// which describes the probability of seeing `k` successes in `n`
+/// independent trials, each of which has success probability `p`.
+///
+/// # Density function
 ///
-/// This distribution has 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
 ///
 /// ```

src/cauchy.rs

@@ -7,20 +7,37 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The Cauchy distribution.
+//! The Cauchy distribution `Cauchy(x₀, γ)`.
 
 use crate::{Distribution, Standard};
 use core::fmt;
 use num_traits::{Float, FloatConst};
 use rand::Rng;
 
-/// The Cauchy distribution `Cauchy(median, scale)`.
+/// The [Cauchy distribution](https://en.wikipedia.org/wiki/Cauchy_distribution) `Cauchy(x₀, γ)`.
 ///
-/// This distribution has a density function:
-/// `f(x) = 1 / (pi * scale * (1 + ((x - median) / scale)^2))`
+/// The Cauchy distribution is a continuous probability distribution with
+/// parameters `x₀` (median) and `γ` (scale).
+/// It describes the distribution of the ratio of two independent
+/// normally distributed random variables with means `x₀` and scales `γ`.
+/// In other words, if `X` and `Y` are independent normally distributed
+/// random variables with means `x₀` and scales `γ`, respectively, then
+/// `X / Y` is `Cauchy(x₀, γ)` distributed.
 ///
-/// Note that at least for `f32`, results are not fully portable due to minor
-/// differences in the target system's *tan* implementation, `tanf`.
+/// # Density function
+///
+/// `f(x) = 1 / (π * γ * (1 + ((x - x₀) / γ)²))`
+///
+/// # Plot
+///
+/// The plot illustrates the Cauchy distribution with various values of `x₀` and `γ`.
+/// Note how the median parameter `x₀` shifts the distribution along the x-axis,
+/// and how the scale `γ` changes the density around the median.
+///
+/// The standard Cauchy distribution is the special case with `x₀ = 0` and `γ = 1`,
+/// which corresponds to the ratio of two [`StandardNormal`](crate::StandardNormal) distributions.
+///
+/// ![Cauchy distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/cauchy.svg)
 ///
 /// # Example
 ///
@@ -31,6 +48,11 @@ use rand::Rng;
 /// let v = cau.sample(&mut rand::thread_rng());
 /// println!("{} is from a Cauchy(2, 5) distribution", v);
 /// ```
+///
+/// # Notes
+///
+/// Note that at least for `f32`, results are not fully portable due to minor
+/// differences in the target system's *tan* implementation, `tanf`.
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Cauchy<F>

src/dirichlet.rs

@@ -7,7 +7,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The dirichlet distribution.
+//! The dirichlet distribution `Dirichlet(α₁, α₂, ..., αₙ)`.
+
 #![cfg(feature = "alloc")]
 use crate::{Beta, Distribution, Exp1, Gamma, Open01, StandardNormal};
 use core::fmt;
@@ -185,11 +186,23 @@ where
     FromBeta(DirichletFromBeta<F, N>),
 }
 
-/// The Dirichlet distribution `Dirichlet(alpha)`.
+/// The [Dirichlet distribution](https://en.wikipedia.org/wiki/Dirichlet_distribution) `Dirichlet(α₁, α₂, ..., αₖ)`.
 ///
 /// 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.
+/// probability distributions parameterized by a vector of positive
+/// real numbers `α₁, α₂, ..., αₖ`, where `k` is the number of dimensions
+/// of the distribution. The distribution is supported on the `k-1`-dimensional
+/// simplex, which is the set of points `x = [x₁, x₂, ..., xₖ]` such that
+/// `0 ≤ xᵢ ≤ 1` and `∑ xᵢ = 1`.
+/// It is a multivariate generalization of the [`Beta`](crate::Beta) distribution.
+/// The distribution is symmetric when all `αᵢ` are equal.
+///
+/// # Plot
+///
+/// The following plot illustrates the 2-dimensional simplices for various
+/// 3-dimensional Dirichlet distributions.
+///
+/// ![Dirichlet distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/dirichlet.png)
 ///
 /// # Example
 ///

src/exponential.rs

@@ -7,37 +7,47 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The exponential distribution.
+//! The exponential distribution `Exp(λ)`.
 
 use crate::utils::ziggurat;
 use crate::{ziggurat_tables, Distribution};
 use core::fmt;
 use num_traits::Float;
 use rand::Rng;
 
-/// Samples floating-point numbers according to the exponential distribution,
-/// with rate parameter `λ = 1`. This is equivalent to `Exp::new(1.0)` or
-/// sampling with `-rng.gen::<f64>().ln()`, but faster.
+/// The standard exponential distribution `Exp(1)`.
 ///
-/// See `Exp` for the general exponential distribution.
+/// This is equivalent to `Exp::new(1.0)` or sampling with
+/// `-rng.gen::<f64>().ln()`, but faster.
 ///
-/// 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.
+/// See [`Exp`](crate::Exp) for the general exponential distribution.
 ///
-/// [^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 plot illustrates the exponential distribution with `λ = 1`.
+///
+/// ![Exponential distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential_exp1.svg)
 ///
 /// # Example
+///
 /// ```
 /// use rand::prelude::*;
 /// use rand_distr::Exp1;
 ///
 /// let val: f64 = thread_rng().sample(Exp1);
 /// println!("{}", val);
 /// ```
+///
+/// # Notes
+///
+/// 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.
+///
+/// [^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 Exp1;
@@ -75,12 +85,30 @@ impl Distribution<f64> for Exp1 {
     }
 }
 
-/// The exponential distribution `Exp(lambda)`.
+/// The [exponential distribution](https://en.wikipedia.org/wiki/Exponential_distribution) `Exp(λ)`.
+///
+/// The exponential distribution is a continuous probability distribution
+/// with rate parameter `λ` (`lambda`). It describes the time between events
+/// in a [`Poisson`](crate::Poisson) process, i.e. a process in which
+/// events occur continuously and independently at a constant average rate.
+///
+/// See [`Exp1`](crate::Exp1) for an optimised implementation for `λ = 1`.
+///
+/// # Density function
+///
+/// `f(x) = λ * exp(-λ * x)` for `x > 0`, when `λ > 0`.
+///
+/// For `λ = 0`, all samples yield infinity (because a Poisson process
+/// with rate 0 has no events).
+///
+/// # Plot
 ///
-/// This distribution has density function: `f(x) = lambda * exp(-lambda * x)`
-/// for `x > 0`, when `lambda > 0`. For `lambda = 0`, all samples yield infinity.
+/// The following plot illustrates the exponential distribution with
+/// various values of `λ`.
+/// The `λ` parameter controls the rate of decay as `x` approaches infinity,
+/// and the mean of the distribution is `1/λ`.
 ///
-/// Note that [`Exp1`](crate::Exp1) is an optimised implementation for `lambda = 1`.
+/// ![Exponential distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential.svg)
 ///
 /// # Example
 ///

src/frechet.rs

@@ -6,20 +6,36 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The Fréchet distribution.
+//! The Fréchet distribution `Fréchet(μ, σ, α)`.
 
 use crate::{Distribution, OpenClosed01};
 use core::fmt;
 use num_traits::Float;
 use rand::Rng;
 
-/// Samples floating-point numbers according to the Fréchet distribution
+/// The [Fréchet distribution](https://en.wikipedia.org/wiki/Fr%C3%A9chet_distribution) `Fréchet(α, μ, σ)`.
 ///
-/// This distribution has density function:
-/// `f(x) = [(x - μ) / σ]^(-1 - α) exp[-(x - μ) / σ]^(-α) α / σ`,
-/// where `μ` is the location parameter, `σ` the scale parameter, and `α` the shape parameter.
+/// The Fréchet distribution is a continuous probability distribution
+/// with location parameter `μ` (`mu`), scale parameter `σ` (`sigma`),
+/// and shape parameter `α` (`alpha`). It describes the distribution
+/// of the maximum (or minimum) of a number of random variables.
+/// It is also known as the Type II extreme value distribution.
+///
+/// # Density function
+///
+/// `f(x) = [(x - μ) / σ]^(-1 - α) exp[-(x - μ) / σ]^(-α) α / σ`
+///
+/// # Plot
+///
+/// The plot shows the Fréchet distribution with various values of `μ`, `σ`, and `α`.
+/// 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 tail behavior.
+///
+/// ![Fréchet distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/frechet.svg)
 ///
 /// # Example
+///
 /// ```
 /// use rand::prelude::*;
 /// use rand_distr::Frechet;