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}