rs_stats/prob/
std_err.rs

1//! # Standard Error Calculation
2//!
3//! This module implements the standard error calculation, which measures
4//! the precision of the sample mean as an estimate of the population mean.
5//!
6//! ## Mathematical Definition
7//! The standard error is defined as:
8//!
9//! SE = σ / √n
10//!
11//! where:
12//! - σ is the sample standard deviation
13//! - n is the sample size
14//!
15//! ## Key Properties
16//! - Decreases as sample size increases
17//! - Measures the variability of the sample mean
18//! - Used in confidence intervals and hypothesis testing
19
20use crate::prob::std_dev::std_dev;
21use num_traits::ToPrimitive;
22
23/// Calculate the standard error of a dataset
24///
25/// The standard error quantifies the uncertainty in the sample mean
26/// as an estimate of the population mean.
27///
28/// # Arguments
29/// * `data` - A slice of numeric values implementing `ToPrimitive`
30///
31/// # Returns
32/// * `Some(f64)` - The standard error if the input slice is non-empty
33/// * `None` - If the input slice is empty
34///
35/// # Examples
36/// ```
37/// use rs_stats::prob::std_err;
38///
39/// // Calculate standard error for a dataset
40/// let data = [1.0, 2.0, 3.0, 4.0, 5.0];
41/// let se = std_err(&data).unwrap();
42/// assert!((se - 0.632455532).abs() < 1e-9);
43///
44/// // Handle empty input
45/// let empty_data: &[f64] = &[];
46/// assert!(std_err(empty_data).is_none());
47/// ```
48#[inline]
49pub fn std_err<T>(data: &[T]) -> Option<f64>
50where
51    T: ToPrimitive + std::fmt::Debug,
52{
53    std_dev(data).map(|std| std / (data.len() as f64).sqrt())
54}
55
56#[cfg(test)]
57mod tests {
58    use super::*;
59
60    const EPSILON: f64 = 1e-9;
61
62    #[test]
63    fn test_std_err_integers() {
64        // Dataset: [1, 2, 3, 4, 5]
65        // Standard deviation of [1, 2, 3, 4, 5] is 1.414213562 (approx)
66        // Standard error should be std_dev / sqrt(n) = 1.414213562 / sqrt(5) = 0.632455532 (approx)
67        let data = vec![1, 2, 3, 4, 5];
68        let result = std_err(&data);
69        let expected = 0.632455532; // Calculated value of the standard error
70        assert!(
71            (result.unwrap() - expected).abs() < EPSILON,
72            "Standard error should be approximately 0.632455532"
73        );
74    }
75
76    #[test]
77    fn test_std_err_floats() {
78        // Dataset: [1.0, 2.0, 3.0, 4.0, 5.0]
79        // Standard deviation of [1.0, 2.0, 3.0, 4.0, 5.0] is the same as for integers
80        let data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
81        let result = std_err(&data);
82        let expected = 0.632455532;
83        assert!(
84            (result.unwrap() - expected).abs() < EPSILON,
85            "Standard error for floats should be approximately 0.632455532"
86        );
87    }
88
89    #[test]
90    fn test_std_err_single_element() {
91        // Dataset with only one element: [5]
92        // Standard deviation is 0, and thus standard error should also be 0
93        let data = vec![5];
94        let result = std_err(&data);
95        let expected = 0.0;
96        assert_eq!(
97            result,
98            Some(expected),
99            "Standard error for a single element should be 0.0"
100        );
101    }
102
103    #[test]
104    fn test_std_err_empty() {
105        // Empty dataset: []
106        // There should be no standard error, result should be None
107        let data: Vec<i32> = vec![];
108        let result = std_err(&data);
109        assert_eq!(
110            result, None,
111            "Standard error for an empty dataset should be None"
112        );
113    }
114}
rs_stats/prob/std_err.rs

rs_stats/prob/
std_err.rs
