andreacavalli
/
rust-average
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Rename `Average` to `AverageWithError` 

This anticipates an implementation that does not calculate the error.
This commit is contained in:
Vinzent Steinberg 2017-05-24 10:24:57 +02:00
parent ee6c5f861c
commit 962adb91d7
6 changed files with 66 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
src/average.rs
View File

@ -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 {
Average { avg: 0., n: 0, v: 0. }
pub fn new() -> AverageWithError {
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 mut avg_left: Average = left.iter().map(|x| *x).collect();
/// let avg_right: Average = right.iter().map(|x| *x).collect();
/// let avg_total: AverageWithError = sequence.iter().map(|x| *x).collect();
/// let mut avg_left: AverageWithError = left.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 {
fn default() -> Average {
Average::new()
impl core::default::Default for AverageWithError {
fn default() -> AverageWithError {
AverageWithError::new()
}
}
impl core::iter::FromIterator<f64> for Average {
fn from_iter<T>(iter: T) -> Average
impl core::iter::FromIterator<f64> for AverageWithError {
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 mut avg_left: Average = left.iter().map(|x| *x).collect();
let avg_right: Average = right.iter().map(|x| *x).collect();
let avg_total: AverageWithError = sequence.iter().map(|x| *x).collect();
let mut avg_left: AverageWithError = left.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);

16
src/lib.rs
View File

@ -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`])
//! with `new()`.
//! 1. Initialize your estimator of choice ([`AverageWithError`] or
//! [`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
//! [`WeightedAverage`]: ./weighted_average/struct.WeightedAverage.html
//! [`AverageWithError`]: ./average/struct.Average.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 weighted_average::WeightedAverage;
pub use average::AverageWithError;
pub use weighted_average::WeightedAverageWithError;

52
src/weighted_average.rs
View File

@ -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 {
WeightedAverage {
pub fn new() -> WeightedAverageWithError {
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 mut avg_left: WeightedAverage = left.iter().map(|&x| x).collect();
/// let avg_right: WeightedAverage = right.iter().map(|&x| x).collect();
/// let avg_total: WeightedAverageWithError = weighted_sequence.iter().map(|&x| x).collect();
/// let mut avg_left: WeightedAverageWithError = left.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 {
fn default() -> WeightedAverage {
WeightedAverage::new()
impl core::default::Default for WeightedAverageWithError {
fn default() -> WeightedAverageWithError {
WeightedAverageWithError::new()
}
}
impl core::iter::FromIterator<(f64, f64)> for WeightedAverage {
fn from_iter<T>(iter: T) -> WeightedAverage
impl core::iter::FromIterator<(f64, f64)> for WeightedAverageWithError {
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 mut avg_left: WeightedAverage = left.iter().map(|x| (*x, 1.)).collect();
let avg_right: WeightedAverage = right.iter().map(|x| (*x, 1.)).collect();
let avg_total: WeightedAverageWithError = sequence.iter().map(|x| (*x, 1.)).collect();
let mut avg_left: WeightedAverageWithError = left.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 mut avg_left: WeightedAverage = left.iter().map(|&(x, w)| (x, w)).collect();
let avg_right: WeightedAverage = right.iter().map(|&(x, w)| (x, w)).collect();
let avg_total: WeightedAverageWithError = sequence.iter().map(|&(x, w)| (x, w)).collect();
let mut avg_left: WeightedAverageWithError = left.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);

10
tests/average.rs
View File

@ -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()));
}

4
tests/streaming_stats.rs
View File

@ -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);

10
tests/weighted_average.rs
View File

@ -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);
}