Rename Average to AverageWithError

This anticipates an implementation that does not calculate the error.

src/average.rs

@@ -15,13 +15,13 @@ use conv::ApproxFrom;
 /// ## Example
 ///
 /// ```
-/// use average::Average;
+/// use average::AverageWithError;
 ///
-/// let a: Average = (1..6).map(Into::into).collect();
+/// let a: AverageWithError = (1..6).map(Into::into).collect();
 /// println!("The average is {} ± {}.", a.mean(), a.error());
 /// ```
 #[derive(Debug, Clone)]
-pub struct Average {
+pub struct AverageWithError {
     /// Average value.
     avg: f64,
     /// Number of samples.
@@ -30,10 +30,10 @@ pub struct Average {
     v: f64,
 }
 
-impl Average {
+impl AverageWithError {
     /// Create a new average estimator.
-    pub fn new() -> Average {
+    pub fn new() -> AverageWithError {
-        Average { avg: 0., n: 0, v: 0. }
+        AverageWithError { avg: 0., n: 0, v: 0. }
     }
 
     /// Add an element sampled from the population.
@@ -98,18 +98,18 @@ impl Average {
     /// ## Example
     ///
     /// ```
-    /// use average::Average;
+    /// use average::AverageWithError;
     ///
     /// let sequence: &[f64] = &[1., 2., 3., 4., 5., 6., 7., 8., 9.];
     /// let (left, right) = sequence.split_at(3);
-    /// let avg_total: Average = sequence.iter().map(|x| *x).collect();
+    /// let avg_total: AverageWithError = sequence.iter().map(|x| *x).collect();
-    /// let mut avg_left: Average = left.iter().map(|x| *x).collect();
+    /// let mut avg_left: AverageWithError = left.iter().map(|x| *x).collect();
-    /// let avg_right: Average = right.iter().map(|x| *x).collect();
+    /// let avg_right: AverageWithError = right.iter().map(|x| *x).collect();
     /// avg_left.merge(&avg_right);
     /// assert_eq!(avg_total.mean(), avg_left.mean());
     /// assert_eq!(avg_total.sample_variance(), avg_left.sample_variance());
     /// ```
-    pub fn merge(&mut self, other: &Average) {
+    pub fn merge(&mut self, other: &AverageWithError) {
         // This algorithm was proposed by Chan et al. in 1979.
         //
         // See https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance.
@@ -128,17 +128,17 @@ impl Average {
     }
 }
 
-impl core::default::Default for Average {
+impl core::default::Default for AverageWithError {
-    fn default() -> Average {
+    fn default() -> AverageWithError {
-        Average::new()
+        AverageWithError::new()
     }
 }
 
-impl core::iter::FromIterator<f64> for Average {
+impl core::iter::FromIterator<f64> for AverageWithError {
-    fn from_iter<T>(iter: T) -> Average
+    fn from_iter<T>(iter: T) -> AverageWithError
         where T: IntoIterator<Item=f64>
     {
-        let mut a = Average::new();
+        let mut a = AverageWithError::new();
         for i in iter {
             a.add(i);
         }
@@ -155,9 +155,9 @@ mod tests {
         let sequence: &[f64] = &[1., 2., 3., 4., 5., 6., 7., 8., 9.];
         for mid in 0..sequence.len() {
             let (left, right) = sequence.split_at(mid);
-            let avg_total: Average = sequence.iter().map(|x| *x).collect();
+            let avg_total: AverageWithError = sequence.iter().map(|x| *x).collect();
-            let mut avg_left: Average = left.iter().map(|x| *x).collect();
+            let mut avg_left: AverageWithError = left.iter().map(|x| *x).collect();
-            let avg_right: Average = right.iter().map(|x| *x).collect();
+            let avg_right: AverageWithError = right.iter().map(|x| *x).collect();
             avg_left.merge(&avg_right);
             assert_eq!(avg_total.n, avg_left.n);
             assert_eq!(avg_total.avg, avg_left.avg);

src/lib.rs

@@ -2,8 +2,8 @@
 //! sequence of numbers, and for their standard errors. The typical workflow
 //! looks like this:
 //!
-//! 1. Initialize your estimator of choice ([`Average`] or [`WeightedAverage`])
+//! 1. Initialize your estimator of choice ([`AverageWithError`] or
-//!    with `new()`.
+//!    [`WeightedAverageWithError`]) with `new()`.
 //! 2. Add some subset (called "samples") of the sequence of numbers (called
 //!    "population") for which you want to estimate the average, using `add()`
 //!    or `collect()`.
@@ -13,15 +13,15 @@
 //! You can run several estimators in parallel and merge them into one with
 //! `merge()`.
 //!
-//! [`Average`]: ./average/struct.Average.html
+//! [`AverageWithError`]: ./average/struct.Average.html
-//! [`WeightedAverage`]: ./weighted_average/struct.WeightedAverage.html
+//! [`WeightedAverageWithError`]: ./weighted_average/struct.WeightedAverage.html
 //!
 //! ## Example
 //!
 //! ```
-//! use average::Average;
+//! use average::AverageWithError;
 //!
-//! let mut a: Average = (1..6).map(Into::into).collect();
+//! let mut a: AverageWithError = (1..6).map(Into::into).collect();
 //! a.add(42.);
 //! println!("The average is {} ± {}.", a.mean(), a.error());
 //! ```
@@ -36,5 +36,5 @@ extern crate conv;
 mod average;
 mod weighted_average;
 
-pub use average::Average;
+pub use average::AverageWithError;
-pub use weighted_average::WeightedAverage;
+pub use weighted_average::WeightedAverageWithError;

src/weighted_average.rs

@@ -1,6 +1,6 @@
 use core;
 
-use super::Average;
+use super::AverageWithError;
 
 /// Estimate the weighted and unweighted arithmetic mean and the unweighted
 /// variance of a sequence of numbers ("population").
@@ -11,14 +11,14 @@ use super::Average;
 /// ## Example
 ///
 /// ```
-/// use average::WeightedAverage;
+/// use average::WeightedAverageWithError;
 ///
-/// let a: WeightedAverage = (1..6).zip(1..6)
+/// let a: WeightedAverageWithError = (1..6).zip(1..6)
 ///     .map(|(x, w)| (f64::from(x), f64::from(w))).collect();
 /// println!("The weighted average is {} ± {}.", a.weighted_mean(), a.error());
 /// ```
 #[derive(Debug, Clone)]
-pub struct WeightedAverage {
+pub struct WeightedAverageWithError {
     /// Sum of the weights.
     weight_sum: f64,
     /// Sum of the squares of the weights.
@@ -27,15 +27,15 @@ pub struct WeightedAverage {
     weighted_avg: f64,
 
     /// Estimator of unweighted average and its variance.
-    unweighted_avg: Average,
+    unweighted_avg: AverageWithError,
 }
 
-impl WeightedAverage {
+impl WeightedAverageWithError {
     /// Create a new weighted and unweighted average estimator.
-    pub fn new() -> WeightedAverage {
+    pub fn new() -> WeightedAverageWithError {
-        WeightedAverage {
+        WeightedAverageWithError {
             weight_sum: 0., weight_sum_sq: 0., weighted_avg: 0.,
-            unweighted_avg: Average::new(),
+            unweighted_avg: AverageWithError::new(),
         }
     }
 
@@ -134,20 +134,20 @@ impl WeightedAverage {
     /// ## Example
     ///
     /// ```
-    /// use average::WeightedAverage;
+    /// use average::WeightedAverageWithError;
     ///
     /// let weighted_sequence: &[(f64, f64)] = &[
     ///     (1., 0.1), (2., 0.2), (3., 0.3), (4., 0.4), (5., 0.5),
     ///     (6., 0.6), (7., 0.7), (8., 0.8), (9., 0.9)];
     /// let (left, right) = weighted_sequence.split_at(3);
-    /// let avg_total: WeightedAverage = weighted_sequence.iter().map(|&x| x).collect();
+    /// let avg_total: WeightedAverageWithError = weighted_sequence.iter().map(|&x| x).collect();
-    /// let mut avg_left: WeightedAverage = left.iter().map(|&x| x).collect();
+    /// let mut avg_left: WeightedAverageWithError = left.iter().map(|&x| x).collect();
-    /// let avg_right: WeightedAverage = right.iter().map(|&x| x).collect();
+    /// let avg_right: WeightedAverageWithError = right.iter().map(|&x| x).collect();
     /// avg_left.merge(&avg_right);
     /// assert!((avg_total.weighted_mean() - avg_left.weighted_mean()).abs() < 1e-15);
     /// assert!((avg_total.error() - avg_left.error()).abs() < 1e-15);
     /// ```
-    pub fn merge(&mut self, other: &WeightedAverage) {
+    pub fn merge(&mut self, other: &WeightedAverageWithError) {
         let total_weight_sum = self.weight_sum + other.weight_sum;
         self.weighted_avg = (self.weight_sum * self.weighted_avg
                              + other.weight_sum * other.weighted_avg)
@@ -159,17 +159,17 @@ impl WeightedAverage {
     }
 }
 
-impl core::default::Default for WeightedAverage {
+impl core::default::Default for WeightedAverageWithError {
-    fn default() -> WeightedAverage {
+    fn default() -> WeightedAverageWithError {
-        WeightedAverage::new()
+        WeightedAverageWithError::new()
     }
 }
 
-impl core::iter::FromIterator<(f64, f64)> for WeightedAverage {
+impl core::iter::FromIterator<(f64, f64)> for WeightedAverageWithError {
-    fn from_iter<T>(iter: T) -> WeightedAverage
+    fn from_iter<T>(iter: T) -> WeightedAverageWithError
         where T: IntoIterator<Item=(f64, f64)>
     {
-        let mut a = WeightedAverage::new();
+        let mut a = WeightedAverageWithError::new();
         for (i, w) in iter {
             a.add(i, w);
         }
@@ -186,9 +186,9 @@ mod tests {
         let sequence: &[f64] = &[1., 2., 3., 4., 5., 6., 7., 8., 9.];
         for mid in 0..sequence.len() {
             let (left, right) = sequence.split_at(mid);
-            let avg_total: WeightedAverage = sequence.iter().map(|x| (*x, 1.)).collect();
+            let avg_total: WeightedAverageWithError = sequence.iter().map(|x| (*x, 1.)).collect();
-            let mut avg_left: WeightedAverage = left.iter().map(|x| (*x, 1.)).collect();
+            let mut avg_left: WeightedAverageWithError = left.iter().map(|x| (*x, 1.)).collect();
-            let avg_right: WeightedAverage = right.iter().map(|x| (*x, 1.)).collect();
+            let avg_right: WeightedAverageWithError = right.iter().map(|x| (*x, 1.)).collect();
             avg_left.merge(&avg_right);
 
             assert_eq!(avg_total.weight_sum, avg_left.weight_sum);
@@ -209,9 +209,9 @@ mod tests {
             (6., 0.6), (7., 0.7), (8., 0.8), (9., 0.)];
         for mid in 0..sequence.len() {
             let (left, right) = sequence.split_at(mid);
-            let avg_total: WeightedAverage = sequence.iter().map(|&(x, w)| (x, w)).collect();
+            let avg_total: WeightedAverageWithError = sequence.iter().map(|&(x, w)| (x, w)).collect();
-            let mut avg_left: WeightedAverage = left.iter().map(|&(x, w)| (x, w)).collect();
+            let mut avg_left: WeightedAverageWithError = left.iter().map(|&(x, w)| (x, w)).collect();
-            let avg_right: WeightedAverage = right.iter().map(|&(x, w)| (x, w)).collect();
+            let avg_right: WeightedAverageWithError = right.iter().map(|&(x, w)| (x, w)).collect();
             avg_left.merge(&avg_right);
             assert_eq!(avg_total.unweighted_avg.len(), avg_left.unweighted_avg.len());
             assert_almost_eq!(avg_total.weight_sum, avg_left.weight_sum, 1e-15);

tests/average.rs

@@ -6,11 +6,11 @@ extern crate rand;
 
 use core::iter::Iterator;
 
-use average::Average;
+use average::AverageWithError;
 
 #[test]
 fn trivial() {
-    let mut a = Average::new();
+    let mut a = AverageWithError::new();
     assert_eq!(a.len(), 0);
     a.add(1.0);
     assert_eq!(a.mean(), 1.0);
@@ -28,7 +28,7 @@ fn trivial() {
 
 #[test]
 fn simple() {
-    let a: Average = (1..6).map(f64::from).collect();
+    let a: AverageWithError = (1..6).map(f64::from).collect();
     assert_eq!(a.mean(), 3.0);
     assert_eq!(a.len(), 5);
     assert_eq!(a.sample_variance(), 2.5);
@@ -40,7 +40,7 @@ fn numerically_unstable() {
     // The naive algorithm fails for this example due to cancelation.
     let big = 1e9;
     let sample = &[big + 4., big + 7., big + 13., big + 16.];
-    let a: Average = sample.iter().map(|x| *x).collect();
+    let a: AverageWithError = sample.iter().map(|x| *x).collect();
     assert_eq!(a.sample_variance(), 30.);
 }
 
@@ -48,7 +48,7 @@ fn numerically_unstable() {
 fn normal_distribution() {
     use rand::distributions::{Normal, IndependentSample};
     let normal = Normal::new(2.0, 3.0);
-    let mut a = Average::new();
+    let mut a = AverageWithError::new();
     for _ in 0..1_000_000 {
         a.add(normal.ind_sample(&mut ::rand::thread_rng()));
     }

tests/streaming_stats.rs

@@ -19,7 +19,7 @@ fn initialize_vec(size: usize) -> Vec<f64> {
 #[test]
 fn average_vs_streaming_stats_small() {
     let values = initialize_vec(100);
-    let a: average::Average = values.iter().map(|x| *x).collect();
+    let a: average::AverageWithError = values.iter().map(|x| *x).collect();
     let b: stats::OnlineStats = values.iter().map(|x| *x).collect();
     assert_almost_eq!(a.mean(), b.mean(), 1e-16);
     assert_almost_eq!(a.population_variance(), b.variance(), 1e-16);
@@ -28,7 +28,7 @@ fn average_vs_streaming_stats_small() {
 #[test]
 fn average_vs_streaming_stats_large() {
     let values = initialize_vec(1_000_000);
-    let a: average::Average = values.iter().map(|x| *x).collect();
+    let a: average::AverageWithError = values.iter().map(|x| *x).collect();
     let b: stats::OnlineStats = values.iter().map(|x| *x).collect();
     assert_almost_eq!(a.mean(), b.mean(), 1e-16);
     assert_almost_eq!(a.population_variance(), b.variance(), 1e-13);

tests/weighted_average.rs

@@ -4,11 +4,11 @@ extern crate core;
 
 use core::iter::Iterator;
 
-use average::WeightedAverage;
+use average::WeightedAverageWithError;
 
 #[test]
 fn trivial() {
-    let mut a = WeightedAverage::new();
+    let mut a = WeightedAverageWithError::new();
     assert_eq!(a.len(), 0);
     assert_eq!(a.sum_weights(), 0.);
     assert_eq!(a.sum_weights_sq(), 0.);
@@ -32,7 +32,7 @@ fn trivial() {
 
 #[test]
 fn simple() {
-    let a: WeightedAverage = (1..6).map(|x| (f64::from(x), 1.0)).collect();
+    let a: WeightedAverageWithError = (1..6).map(|x| (f64::from(x), 1.0)).collect();
     assert_eq!(a.len(), 5);
     assert_eq!(a.weighted_mean(), 3.0);
     assert_eq!(a.unweighted_mean(), 3.0);
@@ -46,7 +46,7 @@ fn reference() {
     // Example from http://www.analyticalgroup.com/download/WEIGHTED_MEAN.pdf.
     let values = &[5., 5., 4., 4., 3., 4., 3., 2., 2., 1.];
     let weights = &[1.23, 2.12, 1.23, 0.32, 1.53, 0.59, 0.94, 0.94, 0.84, 0.73];
-    let a: WeightedAverage = values.iter().zip(weights.iter())
+    let a: WeightedAverageWithError = values.iter().zip(weights.iter())
         .map(|(x, w)| (*x, *w)).collect();
     assert_almost_eq!(a.weighted_mean(), 3.53486, 1e-5);
     assert_almost_eq!(a.sample_variance(), 1.7889, 1e-4);
@@ -60,7 +60,7 @@ fn reference() {
 fn error_corner_case() {
     let values = &[1., 2.];
     let weights = &[0.5, 0.5];
-    let a: WeightedAverage = values.iter().zip(weights.iter())
+    let a: WeightedAverageWithError = values.iter().zip(weights.iter())
         .map(|(x, w)| (*x, *w)).collect();
     assert_eq!(a.error(), 0.5);
 }