stats-ci 0.1.1

A pure Rust library for computing and working with confidence intervals on sample data.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use crate::*;

use lazy_static::lazy_static;
use statrs::distribution::ContinuousCDF;
use statrs::distribution::{Normal, StudentsT};

///
/// return the z-value of the normal distribution for a given confidence level.
///
/// # Arguments
///
/// * `confidence` - the confidence level, e.g. 0.95 for 95% confidence
///
pub fn z_value(confidence: Confidence) -> f64 {
    lazy_static! {
        static ref NORMAL: Normal = Normal::new(0., 1.).unwrap();
    }
    NORMAL.inverse_cdf(confidence.quantile())
}

///
/// return the t-value of the t-distribution for a given confidence level and degree of freedom.
///
/// # Arguments
///
/// * `confidence` - the confidence level, e.g. 0.95 for 95% confidence
/// * `degrees_of_freedom` - the degrees of freedom of the t-distribution
///
/// # Panics
///
/// * if `degrees_of_freedom` is negative or zero
///
pub fn t_value(confidence: Confidence, degrees_of_freedom: f64) -> f64 {
    let student_t = StudentsT::new(0., 1., degrees_of_freedom).unwrap();
    student_t.inverse_cdf(confidence.quantile())
}

const POPULATION_LIMIT: f64 = 100_000.;

pub(crate) fn interval_bounds(
    confidence: Confidence,
    mean: f64,
    std_err_mean: f64,
    degrees_of_freedom: f64,
) -> (f64, f64) {
    let span = if degrees_of_freedom < POPULATION_LIMIT {
        let t = t_value(confidence, degrees_of_freedom);
        t * std_err_mean
    } else {
        let z = z_value(confidence);
        z * std_err_mean
    };
    (mean - span, mean + span)
}

#[cfg(test)]
mod tests {
    use super::*;
    use approx::*;

    #[test]
    fn test_t_and_z_value() {
        for confidence_level in [0.5, 0.8, 0.9, 0.95, 0.99, 0.999] {
            for new_confidence in [
                Confidence::new_two_sided,
                Confidence::new_upper,
                Confidence::new_lower,
            ] {
                let confidence = new_confidence(confidence_level);
                let t_value = t_value(confidence, 1000.);
                let z_value = z_value(confidence);
                assert_abs_diff_eq!(t_value, z_value, epsilon = 1e-2);
            }
        }
    }

    #[test]
    fn test_interval_bounds() {
        let confidence = Confidence::new_two_sided(0.95);
        let mean = 0.;
        let std_err_mean = 1.;

        for n in [
            POPULATION_LIMIT - 1.,
            POPULATION_LIMIT,
            POPULATION_LIMIT + 1.,
            POPULATION_LIMIT + 2.,
        ] {
            let degrees_of_freedom = n - 1.;
            let actual = interval_bounds(confidence, mean, std_err_mean, degrees_of_freedom);
            let bounds_t = only_t(confidence, mean, std_err_mean, degrees_of_freedom);
            let bounds_z = only_z(confidence, mean, std_err_mean);

            println!("n = {} (dof: {})", n, degrees_of_freedom);
            println!("actual: ({}, {})", actual.0, actual.1);
            println!("bounds_t: ({}, {})", bounds_t.0, bounds_t.1);
            println!("bounds_z: ({}, {})", bounds_z.0, bounds_z.1);
            println!();

            assert_abs_diff_eq!(actual.0, bounds_t.0, epsilon = 1e-4);
            assert_abs_diff_eq!(actual.1, bounds_t.1, epsilon = 1e-4);
            assert_abs_diff_eq!(actual.0, bounds_z.0, epsilon = 1e-4);
            assert_abs_diff_eq!(actual.1, bounds_z.1, epsilon = 1e-4);
        }
    }

    fn only_t(
        confidence: Confidence,
        mean: f64,
        std_err_mean: f64,
        degrees_of_freedom: f64,
    ) -> (f64, f64) {
        let t = t_value(confidence, degrees_of_freedom);
        let span = t * std_err_mean;
        (mean - span, mean + span)
    }
    fn only_z(confidence: Confidence, mean: f64, std_err_mean: f64) -> (f64, f64) {
        let z = z_value(confidence);
        let span = z * std_err_mean;
        (mean - span, mean + span)
    }
}