doc: updates doc tests to use new traits

statrs-dev · Nov 5, 2024 · 3844e92 · 3844e92
1 parent 01bb6d5
commit 3844e92
Show file tree

Hide file tree

Showing 32 changed files with 209 additions and 163 deletions.
diff --git a/src/distribution/bernoulli.rs b/src/distribution/bernoulli.rs
@@ -10,13 +10,14 @@ use crate::statistics::*;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Bernoulli, Discrete};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{Bernoulli, BinomialError, Discrete};
+/// use statrs::statistics::*;
 ///
-/// let n = Bernoulli::new(0.5).unwrap();
-/// assert_eq!(n.mean().unwrap(), 0.5);
+/// let n = Bernoulli::new(0.5)?;
+/// assert_eq!(n.mean(), 0.5);
 /// assert_eq!(n.pmf(0), 0.5);
 /// assert_eq!(n.pmf(1), 0.5);
+/// # Ok::<(), BinomialError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct Bernoulli {
@@ -53,10 +54,11 @@ impl Bernoulli {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Bernoulli;
+    /// use statrs::distribution::{Bernoulli, BinomialError};
     ///
-    /// let n = Bernoulli::new(0.5).unwrap();
+    /// let n = Bernoulli::new(0.5)?;
     /// assert_eq!(n.p(), 0.5);
+    /// # Ok::<(), BinomialError>(())
     /// ```
     pub fn p(&self) -> f64 {
         self.b.p()
@@ -68,10 +70,11 @@ impl Bernoulli {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Bernoulli;
+    /// use statrs::distribution::{Bernoulli, BinomialError};
     ///
-    /// let n = Bernoulli::new(0.5).unwrap();
+    /// let n = Bernoulli::new(0.5)?;
     /// assert_eq!(n.n(), 1);
+    /// # Ok::<(), BinomialError>(())
     /// ```
     pub fn n(&self) -> u64 {
         1

diff --git a/src/distribution/beta.rs b/src/distribution/beta.rs
@@ -8,13 +8,14 @@ use crate::statistics::*;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Beta, Continuous};
+/// use statrs::distribution::{Beta, Continuous, BetaError};
 /// use statrs::statistics::*;
 /// use statrs::prec;
 ///
-/// let n = Beta::new(2.0, 2.0).unwrap();
-/// assert_eq!(n.mean().unwrap(), 0.5);
+/// let n = Beta::new(2.0, 2.0)?;
+/// assert_eq!(n.mean(), 0.5);
 /// assert!(prec::almost_eq(n.pdf(0.5), 1.5, 1e-14));
+/// # Ok::<(), BetaError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct Beta {
@@ -82,10 +83,11 @@ impl Beta {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Beta;
+    /// use statrs::distribution::{Beta, BetaError};
     ///
-    /// let n = Beta::new(1.0, 2.0).unwrap();
+    /// let n = Beta::new(1.0, 2.0)?;
     /// assert_eq!(n.shape_a(), 1.0);
+    /// # Ok::<(), BetaError>(())
     /// ```
     pub fn shape_a(&self) -> f64 {
         self.shape_a
@@ -96,10 +98,11 @@ impl Beta {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Beta;
+    /// use statrs::distribution::{Beta, BetaError};
     ///
-    /// let n = Beta::new(1.0, 2.0).unwrap();
+    /// let n = Beta::new(1.0, 2.0)?;
     /// assert_eq!(n.shape_b(), 2.0);
+    /// # Ok::<(), BetaError>(())
     /// ```
     pub fn shape_b(&self) -> f64 {
         self.shape_b

diff --git a/src/distribution/binomial.rs b/src/distribution/binomial.rs
@@ -10,13 +10,14 @@ use std::f64;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Binomial, Discrete};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{Binomial, BinomialError, Discrete};
+/// use statrs::statistics::*;
 ///
-/// let n = Binomial::new(0.5, 5).unwrap();
-/// assert_eq!(n.mean().unwrap(), 2.5);
+/// let n = Binomial::new(0.5, 5)?;
+/// assert_eq!(n.mean(), 2.5);
 /// assert_eq!(n.pmf(0), 0.03125);
 /// assert_eq!(n.pmf(3), 0.3125);
+/// # Ok::<(), BinomialError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct Binomial {
@@ -78,10 +79,11 @@ impl Binomial {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Binomial;
+    /// use statrs::distribution::{Binomial, BinomialError};
     ///
-    /// let n = Binomial::new(0.5, 5).unwrap();
+    /// let n = Binomial::new(0.5, 5)?;
     /// assert_eq!(n.p(), 0.5);
+    /// # Ok::<(), BinomialError>(())
     /// ```
     pub fn p(&self) -> f64 {
         self.p
@@ -93,10 +95,11 @@ impl Binomial {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Binomial;
+    /// use statrs::distribution::{Binomial, BinomialError};
     ///
-    /// let n = Binomial::new(0.5, 5).unwrap();
+    /// let n = Binomial::new(0.5, 5)?;
     /// assert_eq!(n.n(), 5);
+    /// # Ok::<(), BinomialError>(())
     /// ```
     pub fn n(&self) -> u64 {
         self.n

diff --git a/src/distribution/categorical.rs b/src/distribution/categorical.rs
@@ -10,13 +10,14 @@ use std::f64;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Categorical, Discrete};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{Categorical, CategoricalError, Discrete};
+/// use statrs::statistics::*;
 /// use statrs::prec;
 ///
-/// let n = Categorical::new(&[0.0, 1.0, 2.0]).unwrap();
-/// assert!(prec::almost_eq(n.mean().unwrap(), 5.0 / 3.0, 1e-15));
+/// let n = Categorical::new(&[0.0, 1.0, 2.0])?;
+/// assert!(prec::almost_eq(n.mean(), 5.0 / 3.0, 1e-15));
 /// assert_eq!(n.pmf(1), 1.0 / 3.0);
+/// # Ok::<(), CategoricalError>(())
 /// ```
 #[derive(Clone, PartialEq, Debug)]
 pub struct Categorical {

diff --git a/src/distribution/cauchy.rs b/src/distribution/cauchy.rs
@@ -8,12 +8,13 @@ use std::f64;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Cauchy, Continuous};
-/// use statrs::statistics::Mode;
+/// use statrs::distribution::{Cauchy, Continuous, CauchyError};
+/// use statrs::statistics::*;
 ///
-/// let n = Cauchy::new(0.0, 1.0).unwrap();
+/// let n = Cauchy::new(0.0, 1.0)?;
 /// assert_eq!(n.mode().unwrap(), 0.0);
 /// assert_eq!(n.pdf(1.0), 0.1591549430918953357689);
+/// # Ok::<(), CauchyError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct Cauchy {
@@ -80,10 +81,11 @@ impl Cauchy {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Cauchy;
+    /// use statrs::distribution::{Cauchy, CauchyError};
     ///
-    /// let n = Cauchy::new(0.0, 1.0).unwrap();
+    /// let n = Cauchy::new(0.0, 1.0)?;
     /// assert_eq!(n.location(), 0.0);
+    /// # Ok::<(), CauchyError>(())
     /// ```
     pub fn location(&self) -> f64 {
         self.location
@@ -94,10 +96,11 @@ impl Cauchy {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Cauchy;
+    /// use statrs::distribution::{Cauchy, CauchyError};
     ///
-    /// let n = Cauchy::new(0.0, 1.0).unwrap();
+    /// let n = Cauchy::new(0.0, 1.0)?;
     /// assert_eq!(n.scale(), 1.0);
+    /// # Ok::<(), CauchyError>(())
     /// ```
     pub fn scale(&self) -> f64 {
         self.scale

diff --git a/src/distribution/chi.rs b/src/distribution/chi.rs
@@ -9,13 +9,14 @@ use std::f64;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Chi, Continuous};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{Chi, Continuous, ChiError};
+/// use statrs::statistics::*;
 /// use statrs::prec;
 ///
-/// let n = Chi::new(2.0).unwrap();
+/// let n = Chi::new(2.0)?;
 /// assert!(prec::almost_eq(n.mean().unwrap(), 1.25331413731550025121, 1e-14));
 /// assert!(prec::almost_eq(n.pdf(1.0), 0.60653065971263342360, 1e-15));
+/// # Ok::<(), ChiError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct Chi {
@@ -77,10 +78,12 @@ impl Chi {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Chi;
+    /// use statrs::distribution::{Chi, ChiError};
+    ///
     ///
-    /// let n = Chi::new(2.0).unwrap();
+    /// let n = Chi::new(2.0)?;
     /// assert_eq!(n.freedom(), 2.0);
+    /// # Ok::<(), ChiError>(())
     /// ```
     pub fn freedom(&self) -> f64 {
         self.freedom

diff --git a/src/distribution/chi_squared.rs b/src/distribution/chi_squared.rs
@@ -11,13 +11,14 @@ use std::f64;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{ChiSquared, Continuous};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{ChiSquared, Continuous, GammaError};
+/// use statrs::statistics::*;
 /// use statrs::prec;
 ///
-/// let n = ChiSquared::new(3.0).unwrap();
-/// assert_eq!(n.mean().unwrap(), 3.0);
+/// let n = ChiSquared::new(3.0)?;
+/// assert_eq!(n.mean(), 3.0);
 /// assert!(prec::almost_eq(n.pdf(4.0), 0.107981933026376103901, 1e-15));
+/// # Ok::<(), GammaError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct ChiSquared {
@@ -56,10 +57,11 @@ impl ChiSquared {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::ChiSquared;
+    /// use statrs::distribution::{ChiSquared, GammaError};
     ///
-    /// let n = ChiSquared::new(3.0).unwrap();
+    /// let n = ChiSquared::new(3.0)?;
     /// assert_eq!(n.freedom(), 3.0);
+    /// # Ok::<(), GammaError>(())
     /// ```
     pub fn freedom(&self) -> f64 {
         self.freedom
@@ -70,10 +72,11 @@ impl ChiSquared {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::ChiSquared;
+    /// use statrs::distribution::{ChiSquared, GammaError};
     ///
-    /// let n = ChiSquared::new(3.0).unwrap();
+    /// let n = ChiSquared::new(3.0)?;
     /// assert_eq!(n.shape(), 3.0 / 2.0);
+    /// # Ok::<(), GammaError>(())
     /// ```
     pub fn shape(&self) -> f64 {
         self.g.shape()
@@ -84,10 +87,11 @@ impl ChiSquared {
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::ChiSquared;
+    /// use statrs::distribution::{ChiSquared, GammaError};
     ///
-    /// let n = ChiSquared::new(3.0).unwrap();
+    /// let n = ChiSquared::new(3.0)?;
     /// assert_eq!(n.rate(), 0.5);
+    /// # Ok::<(), GammaError>(())
     /// ```
     pub fn rate(&self) -> f64 {
         self.g.rate()

diff --git a/src/distribution/dirac.rs b/src/distribution/dirac.rs
@@ -7,11 +7,12 @@ use crate::statistics::*;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Dirac, Continuous};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{Dirac, Continuous, DiracError};
+/// use statrs::statistics::*;
 ///
-/// let n = Dirac::new(3.0).unwrap();
-/// assert_eq!(n.mean().unwrap(), 3.0);
+/// let n = Dirac::new(3.0)?;
+/// assert_eq!(n.mean(), 3.0);
+/// # Ok::<(), DiracError>(())
 /// ```
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub struct Dirac(f64);

diff --git a/src/distribution/dirichlet.rs b/src/distribution/dirichlet.rs
@@ -12,14 +12,14 @@ use std::f64;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{Dirichlet, Continuous};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{Dirichlet, Continuous, DirichletError};
+/// use statrs::statistics::*;
 /// use nalgebra::DVector;
-/// use statrs::statistics::MeanN;
 ///
-/// let n = Dirichlet::new(vec![1.0, 2.0, 3.0]).unwrap();
-/// assert_eq!(n.mean().unwrap(), DVector::from_vec(vec![1.0 / 6.0, 1.0 / 3.0, 0.5]));
+/// let n = Dirichlet::new(vec![1.0, 2.0, 3.0])?;
+/// assert_eq!(n.mean(), DVector::from_vec(vec![1.0 / 6.0, 1.0 / 3.0, 0.5]));
 /// assert_eq!(n.pdf(&DVector::from_vec(vec![0.33333, 0.33333, 0.33333])), 2.222155556222205);
+/// # Ok::<(), DirichletError>(())
 /// ```
 #[derive(Clone, PartialEq, Debug)]
 pub struct Dirichlet<D>
@@ -138,11 +138,12 @@ where
     /// # Examples
     ///
     /// ```
-    /// use statrs::distribution::Dirichlet;
+    /// use statrs::distribution::{Dirichlet, DirichletError};
     /// use nalgebra::DVector;
     ///
-    /// let n = Dirichlet::new(vec![1.0, 2.0, 3.0]).unwrap();
+    /// let n = Dirichlet::new(vec![1.0, 2.0, 3.0])?;
     /// assert_eq!(n.alpha(), &DVector::from_vec(vec![1.0, 2.0, 3.0]));
+    /// # Ok::<(), DirichletError>(())
     /// ```
     pub fn alpha(&self) -> &nalgebra::OVector<f64, D> {
         &self.alpha

diff --git a/src/distribution/discrete_uniform.rs b/src/distribution/discrete_uniform.rs
@@ -8,12 +8,13 @@ use crate::statistics::*;
 /// # Examples
 ///
 /// ```
-/// use statrs::distribution::{DiscreteUniform, Discrete};
-/// use statrs::statistics::Distribution;
+/// use statrs::distribution::{DiscreteUniform, Discrete, DiscreteUniformError};
+/// use statrs::statistics::*;
 ///
-/// let n = DiscreteUniform::new(0, 5).unwrap();
-/// assert_eq!(n.mean().unwrap(), 2.5);
+/// let n = DiscreteUniform::new(0, 5)?;
+/// assert_eq!(n.mean(), 2.5);
 /// assert_eq!(n.pmf(3), 1.0 / 6.0);
+/// # Ok::<(), DiscreteUniformError>(())
 /// ```
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct DiscreteUniform {
@@ -66,6 +67,11 @@ impl DiscreteUniform {
             Ok(DiscreteUniform { min, max })
         }
     }
+
+    pub fn std_dev(&self) -> f64 {
+        let dist = self.max - self.min + 1;
+        (dist * dist) as f64 / 12.
+    }
 }
 
 impl std::fmt::Display for DiscreteUniform {

diff --git a/src/distribution/empirical.rs b/src/distribution/empirical.rs
@@ -27,7 +27,7 @@ impl<T: PartialOrd> Ord for NonNan<T> {
 ///
 /// ```
 /// use statrs::distribution::{Continuous, Empirical};
-/// use statrs::statistics::Distribution;
+/// use statrs::statistics::*;
 ///
 /// let samples = vec![0.0, 5.0, 10.0];
 ///