Skip to main content

tpt_math_prob_bayes/
lib.rs

1//! Bayesian inference primitives.
2//!
3//! Small, dependency-free building blocks for exact conjugate updates and for
4//! approximate inference when conjugacy runs out:
5//!
6//! * [`Beta`] — conjugate prior for a Bernoulli/Binomial success rate.
7//! * [`Gaussian`] (aliased [`Normal`]) — density, sampling, and the
8//!   Normal–Normal conjugate update for an unknown mean with known variance.
9//! * [`Gamma`] — conjugate prior for a Poisson rate, and the engine behind
10//!   Beta sampling.
11//! * [`Metropolis`] — a random-walk Metropolis(–Hastings) sampler for any
12//!   unnormalised scalar log-target.
13//! * [`special`] — the log-gamma/log-beta/normal-CDF machinery underneath.
14//! * Free log-likelihood helpers such as [`bernoulli_log_likelihood`],
15//!   [`normal_log_likelihood`], and [`log_sum_exp`].
16//!
17//! Every distribution samples through the [`Rng`] and [`Distribution`] traits
18//! from `tpt-math-prob-core`, so a deterministic generator such as
19//! `SplitMix64` makes any inference run exactly reproducible.
20//!
21//! # Conjugate updates
22//!
23//! ```
24//! use tpt_math_prob_bayes::Beta;
25//!
26//! // Uniform prior over a coin's bias, then 7 heads and 3 tails.
27//! let posterior = Beta::uniform().update(7, 3);
28//! assert_eq!((posterior.alpha(), posterior.beta()), (8.0, 4.0));
29//! assert!((posterior.mean() - 2.0 / 3.0).abs() < 1e-12);
30//!
31//! // Posterior belief with 95% probability mass.
32//! let (lo, hi) = posterior.credible_interval(0.95);
33//! assert!(lo < posterior.mean() && posterior.mean() < hi);
34//! ```
35//!
36//! # Approximate inference
37//!
38//! ```
39//! use tpt_math_prob_bayes::{Beta, Metropolis};
40//! use tpt_math_prob_core::SplitMix64;
41//!
42//! let prior = Beta::new(2.0, 2.0);
43//! let (successes, failures) = (30, 70);
44//!
45//! // Sample the same posterior with MCMC instead of the conjugate formula.
46//! let target = move |p: f64| prior.log_unnormalized_posterior(p, successes, failures);
47//! let mut sampler = Metropolis::with_gaussian_proposal(target, 0.1);
48//! let mut rng = SplitMix64::seed_from_u64(2024);
49//! let trace = sampler.run_with_burn_in(&mut rng, 0.5, 2_000, 40_000);
50//!
51//! let mcmc_mean = trace.iter().sum::<f64>() / trace.len() as f64;
52//! let exact_mean = prior.update(successes, failures).mean();
53//! assert!((mcmc_mean - exact_mean).abs() < 0.01);
54//! ```
55
56use core::fmt;
57
58pub mod adaptive;
59mod beta;
60pub mod diagnostics;
61mod gamma;
62pub mod hmc;
63mod likelihood;
64mod mcmc;
65mod normal;
66pub mod special;
67
68pub use beta::Beta;
69pub use gamma::Gamma;
70pub use likelihood::{
71    bernoulli_log_likelihood, binomial_log_likelihood, exponential_log_likelihood, log_sum_exp,
72    normal_log_likelihood, poisson_log_likelihood,
73};
74pub use mcmc::Metropolis;
75pub use normal::{Gaussian, Normal};
76
77/// The randomness traits this crate is built on, re-exported for convenience.
78pub use tpt_math_prob_core::{Distribution, Rng, Sampler};
79
80/// An invalid distribution parameter.
81///
82/// Returned by the `try_new` constructors; the panicking `new` constructors
83/// report the same condition in their panic message.
84#[derive(Clone, Copy, Debug, PartialEq, Eq)]
85#[non_exhaustive]
86pub enum ParameterError {
87    /// The parameter was `NaN` or infinite.
88    NotFinite {
89        /// Name of the offending parameter.
90        parameter: &'static str,
91    },
92    /// The parameter must be strictly positive but was zero or negative.
93    NotPositive {
94        /// Name of the offending parameter.
95        parameter: &'static str,
96    },
97}
98
99impl fmt::Display for ParameterError {
100    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
101        match self {
102            ParameterError::NotFinite { parameter } => {
103                write!(f, "`{parameter}` must be finite")
104            }
105            ParameterError::NotPositive { parameter } => {
106                write!(f, "`{parameter}` must be strictly positive")
107            }
108        }
109    }
110}
111
112impl std::error::Error for ParameterError {}
113
114/// Validate that `value` is finite.
115pub(crate) fn check_finite(parameter: &'static str, value: f64) -> Result<(), ParameterError> {
116    if value.is_finite() {
117        Ok(())
118    } else {
119        Err(ParameterError::NotFinite { parameter })
120    }
121}
122
123/// Validate that `value` is finite and strictly positive.
124pub(crate) fn check_positive(parameter: &'static str, value: f64) -> Result<(), ParameterError> {
125    check_finite(parameter, value)?;
126    if value > 0.0 {
127        Ok(())
128    } else {
129        Err(ParameterError::NotPositive { parameter })
130    }
131}
132
133#[cfg(test)]
134mod tests {
135    use super::*;
136
137    #[test]
138    fn parameter_error_displays_the_parameter_name() {
139        let err = check_positive("alpha", -1.0).unwrap_err();
140        assert_eq!(err, ParameterError::NotPositive { parameter: "alpha" });
141        assert_eq!(err.to_string(), "`alpha` must be strictly positive");
142
143        let err = check_finite("mean", f64::NAN).unwrap_err();
144        assert_eq!(err, ParameterError::NotFinite { parameter: "mean" });
145        assert_eq!(err.to_string(), "`mean` must be finite");
146
147        assert!(check_positive("rate", 1.0).is_ok());
148        assert!(check_finite("mean", -3.0).is_ok());
149        assert!(check_positive("rate", f64::INFINITY).is_err());
150    }
151
152    #[test]
153    fn parameter_error_is_a_std_error() {
154        fn as_error(e: impl std::error::Error) -> String {
155            e.to_string()
156        }
157        assert!(as_error(ParameterError::NotFinite { parameter: "std" }).contains("std"));
158    }
159}