basic_stochastics 0.1.3

A small collection of utilities to make performing basic stochastic calculations more convenient
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

//! # Basic Stochastics
//!
//! `basic_stochastics` is a small collection of utilities to make performing basic stochastic
//! calculations more convenient.

// sigma to percent
pub const ONE_SIGMA: f64 = 1.0; // ~68,27%
pub const TWO_SIGMA: f64 = 2.0; // ~95.45%
pub const THREE_SIGMA: f64 = 3.0; // ~99.73%

// percent to sigma
pub const FIFTY_TO_SIGMA: f64 = 0.675;
pub const SIXTY_TO_SIGMA: f64 = 0.842;
pub const SEVENTY_TO_SIGMA: f64 = 1.036;
pub const EIGHTY_TO_SIGMA: f64 = 1.282;
pub const NINETY_TO_SIGMA: f64 = 1.645;
pub const NINETY_FIVE_TO_SIGMA: f64 = 1.960;
pub const NINETY_NINE_TO_SIGMA: f64 = 2.576;


/// Determines, whether the given value matches the given sigma environment of the given data's normal distribution.
/// You can either provide a specific sigma environment or use one from the given constants.
/// Please see https://en.wikipedia.org/wiki/Normal_distribution and sigma rooms for further information.
///
/// # Examples
///
/// ```
/// let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
///
/// assert_eq!(basic_stochastics::matches_sigma_environment(&data, basic_stochastics::ONE_SIGMA, 3.4), true);
/// assert_eq!(basic_stochastics::matches_sigma_environment(&data, basic_stochastics::ONE_SIGMA, 1.4), true);
/// assert_eq!(basic_stochastics::matches_sigma_environment(&data, basic_stochastics::ONE_SIGMA, 5.0), false);
///
/// assert_eq!(basic_stochastics::matches_sigma_environment(&data, basic_stochastics::TWO_SIGMA, 3.4), true);
/// assert_eq!(basic_stochastics::matches_sigma_environment(&data, basic_stochastics::TWO_SIGMA, 5.0), false);
///
/// assert_eq!(basic_stochastics::matches_sigma_environment(&data, 2.576, 3.4), true);
/// ```
pub fn matches_sigma_environment(data: &Vec<f64>, sigma_room: f64, to_check: f64) -> bool {
    let average = average(data);
    let sigma = empiric_deviation(data);

    matches_custom_sigma_environment(average, sigma, sigma_room, to_check)
}

/// Determines, whether the given value matches the given sigma environment using the given µ and σ values.
/// You can either provide a specific sigma environment or use one from the given constants.
/// Please see https://en.wikipedia.org/wiki/Normal_distribution and sigma rooms for further information.
///
/// # Examples
///
/// ```
/// let sigma = 15.0;
/// let average = 100.0;
///
/// assert_eq!(basic_stochastics::matches_custom_sigma_environment(average, sigma, basic_stochastics::ONE_SIGMA, 110.0), true);
/// assert_eq!(basic_stochastics::matches_custom_sigma_environment(average, sigma, basic_stochastics::ONE_SIGMA, 120.0), false);
/// ```
pub fn matches_custom_sigma_environment(average: f64, sigma: f64, sigma_room: f64, to_check: f64) -> bool {
    ((average - (sigma_room * sigma)) < to_check) && (to_check < (average + (sigma_room * sigma)))
}

/// Calculates the average of the given vector.
///
/// # Examples
///
/// ```
/// let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
///
/// assert_eq!(basic_stochastics::average(&data), 2.4);
/// ```
pub fn average(data: &Vec<f64>) -> f64 {
    let mut sum: f64 = 0.0;
    for i in data {
        sum += *i;
    }

    return sum / data.len() as f64;
}


/// Calculates the variance of the given vector.
/// Please see https://en.wikipedia.org/wiki/Variance for further explanation.
///
/// # Examples
///
/// ```
/// let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
///
/// assert_eq!(basic_stochastics::variance(&data), 1.04);
/// ```
pub fn variance(data: &Vec<f64>) -> f64 {
    let average = average(data);

    let mut variance = 0.0;
    for i in data {
        let difference: f64 = *i - average;
        variance += difference * difference;
    }

    return variance / data.len() as f64;
}

/// Calculates the square root of the variance, representing the scattering of the given data
///
/// # Examples
///
/// ```
///  let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
///
///  assert_eq!(basic_stochastics::empiric_deviation(&data), 1.019803902718557)
/// ```
pub fn empiric_deviation(data: &Vec<f64>) -> f64 {
    return variance(data).sqrt();
}

#[cfg(test)]
mod tests {

    #[test]
    fn test_average() {
        let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
        assert_eq!(::average(&data), 2.4);
    }

    #[test]
    fn test_variance() {
        let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
        assert_eq!(::variance(&data), 1.04);
    }

    #[test]
    fn test_empiric_deviation() {
        let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];
        assert_eq!(::empiric_deviation(&data), 1.019803902718557);
    }

    #[test]
    fn test_sigma_environment() {
        let data = vec![1.0, 2.0, 3.0, 4.0, 2.0];

        assert_eq!(::matches_sigma_environment(&data, ::ONE_SIGMA, 3.4), true);
        assert_eq!(::matches_sigma_environment(&data, ::ONE_SIGMA, 1.4), true);
        assert_eq!(::matches_sigma_environment(&data, ::ONE_SIGMA, 5.0), false);

        assert_eq!(::matches_sigma_environment(&data, ::TWO_SIGMA, 3.4), true);
        assert_eq!(::matches_sigma_environment(&data, ::TWO_SIGMA, 5.0), false);
    }

    #[test]
    fn test_custom_sigma_environment() {
        let sigma = 15.0;
        let average = 100.0;

        assert_eq!(::matches_custom_sigma_environment(average, sigma, ::ONE_SIGMA, 110.0), true);
        assert_eq!(::matches_custom_sigma_environment(average, sigma, ::ONE_SIGMA, 120.0), false);
    }
}