rand_distr/
fisher_f.rs

1// Copyright 2018 Developers of the Rand project.
2// Copyright 2013 The Rust Project Developers.
3//
4// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
7// option. This file may not be copied, modified, or distributed
8// except according to those terms.
9
10//! The Fisher F-distribution.
11
12use crate::{ChiSquared, Distribution, Exp1, Open01, StandardNormal, chi_squared};
13use core::fmt;
14use num_traits::Float;
15use rand::Rng;
16#[cfg(feature = "serde")]
17use serde::{Deserialize, Serialize};
18
19/// The [Fisher F-distribution](https://en.wikipedia.org/wiki/F-distribution) `F(m, n)`.
20///
21/// This distribution is equivalent to the ratio of two normalised
22/// chi-squared distributions, that is, `F(m,n) = (χ²(m)/m) /
23/// (χ²(n)/n)`.
24///
25/// # Plot
26///
27/// The plot shows the F-distribution with various values of `m` and `n`.
28///
29/// ![F-distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/fisher_f.svg)
30///
31/// # Example
32///
33/// ```
34/// use rand_distr::{FisherF, Distribution};
35///
36/// let f = FisherF::new(2.0, 32.0).unwrap();
37/// let v = f.sample(&mut rand::rng());
38/// println!("{} is from an F(2, 32) distribution", v)
39/// ```
40#[derive(Clone, Copy, Debug, PartialEq)]
41#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
42pub struct FisherF<F>
43where
44    F: Float,
45    StandardNormal: Distribution<F>,
46    Exp1: Distribution<F>,
47    Open01: Distribution<F>,
48{
49    numer: ChiSquared<F>,
50    denom: ChiSquared<F>,
51    // denom_dof / numer_dof so that this can just be a straight
52    // multiplication, rather than a division.
53    dof_ratio: F,
54}
55
56/// Error type returned from [`FisherF::new`].
57#[derive(Clone, Copy, Debug, PartialEq, Eq)]
58#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
59pub enum Error {
60    /// `0.5 * m <= 0.0` or `nan`.
61    MTooSmall,
62    /// `0.5 * n <= 0.0` or `nan`.
63    NTooSmall,
64}
65
66impl fmt::Display for Error {
67    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
68        f.write_str(match self {
69            Error::MTooSmall => "m is not positive in Fisher F distribution",
70            Error::NTooSmall => "n is not positive in Fisher F distribution",
71        })
72    }
73}
74
75#[cfg(feature = "std")]
76impl std::error::Error for Error {}
77
78impl<F> FisherF<F>
79where
80    F: Float,
81    StandardNormal: Distribution<F>,
82    Exp1: Distribution<F>,
83    Open01: Distribution<F>,
84{
85    /// Create a new `FisherF` distribution, with the given parameter.
86    pub fn new(m: F, n: F) -> Result<FisherF<F>, Error> {
87        Ok(FisherF {
88            numer: ChiSquared::new(m).map_err(|x| match x {
89                chi_squared::Error::DoFTooSmall => Error::MTooSmall,
90            })?,
91            denom: ChiSquared::new(n).map_err(|x| match x {
92                chi_squared::Error::DoFTooSmall => Error::NTooSmall,
93            })?,
94            dof_ratio: n / m,
95        })
96    }
97}
98impl<F> Distribution<F> for FisherF<F>
99where
100    F: Float,
101    StandardNormal: Distribution<F>,
102    Exp1: Distribution<F>,
103    Open01: Distribution<F>,
104{
105    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> F {
106        self.numer.sample(rng) / self.denom.sample(rng) * self.dof_ratio
107    }
108}
109
110#[cfg(test)]
111mod test {
112    use super::*;
113
114    #[test]
115    fn test_f() {
116        let f = FisherF::new(2.0, 32.0).unwrap();
117        let mut rng = crate::test::rng(204);
118        for _ in 0..1000 {
119            f.sample(&mut rng);
120        }
121    }
122
123    #[test]
124    fn fisher_f_distributions_can_be_compared() {
125        assert_eq!(FisherF::new(1.0, 2.0), FisherF::new(1.0, 2.0));
126    }
127}
rand_distr/fisher_f.rs

rand_distr/
fisher_f.rs
