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

Rename average to mean for consistency

Browse Source
This commit is contained in:
Vinzent Steinberg 2017-05-28 21:13:47 +02:00
parent 712303b58a
commit 30622be775
8 changed files with 121 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
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`], [`AverageWithError`],
//! [`WeightedAverage`] or [`WeightedAverageWithError`]) with `new()`.
//! 1. Initialize your estimator of choice ([`Mean`], [`MeanWithError`],
//! [`WeightedMean`] or [`WeightedMeanWithError`]) 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()`.
@ -17,18 +17,18 @@
//! so the sequence of numbers can be an iterator. The used algorithms try to
//! avoid numerical instabilities.
//!
//! [`Average`]: ./average/struct.Average.html
//! [`AverageWithError`]: ./average/struct.AverageWithError.html
//! [`WeightedAverage`]: ./weighted_average/struct.WeightedAverage.html
//! [`WeightedAverageWithError`]: ./weighted_average/struct.WeightedAverageWithError.html
//! [`Mean`]: ./average/struct.Mean.html
//! [`MeanWithError`]: ./average/struct.MeanWithError.html
//! [`WeightedMean`]: ./weighted_average/struct.WeightedMean.html
//! [`WeightedMeanWithError`]: ./weighted_average/struct.WeightedMeanWithError.html
//!
//!
//! ## Example
//!
//! ```
//! use average::AverageWithError;
//! use average::MeanWithError;
//!
//! let mut a: AverageWithError = (1..6).map(Into::into).collect();
//! let mut a: MeanWithError = (1..6).map(Into::into).collect();
//! a.add(42.);
//! println!("The average is {} ± {}.", a.mean(), a.error());
//! ```
@ -40,12 +40,12 @@ extern crate quickersort;
#[macro_use] mod macros;
mod moments;
mod weighted_average;
mod weighted_mean;
mod minmax;
mod reduce;
mod quantile;
pub use moments::{Average, AverageWithError};
pub use weighted_average::{WeightedAverage, WeightedAverageWithError};
pub use moments::{Mean, Variance, MeanWithError};
pub use weighted_mean::{WeightedMean, WeightedMeanWithError};
pub use minmax::{Min, Max};
pub use quantile::Quantile;

40
src/moments/mean.rs
View File

@ -9,24 +9,24 @@ use conv::ApproxFrom;
/// ## Example
///
/// ```
/// use average::Average;
/// use average::Mean;
///
/// let a: Average = (1..6).map(Into::into).collect();
/// println!("The average is {}.", a.mean());
/// let a: Mean = (1..6).map(Into::into).collect();
/// println!("The mean is {}.", a.mean());
/// ```
#[derive(Debug, Clone)]
pub struct Average {
/// Average value.
pub struct Mean {
/// Mean value.
avg: f64,
/// Sample size.
n: u64,
}
impl Average {
/// Create a new average estimator.
impl Mean {
/// Create a new mean estimator.
#[inline]
pub fn new() -> Average {
Average { avg: 0., n: 0 }
pub fn new() -> Mean {
Mean { avg: 0., n: 0 }
}
/// Add an observation sampled from the population.
@ -85,18 +85,18 @@ impl Average {
/// ## Example
///
/// ```
/// use average::Average;
/// use average::Mean;
///
/// 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: Mean = sequence.iter().map(|x| *x).collect();
/// let mut avg_left: Mean = left.iter().map(|x| *x).collect();
/// let avg_right: Mean = right.iter().map(|x| *x).collect();
/// avg_left.merge(&avg_right);
/// assert_eq!(avg_total.mean(), avg_left.mean());
/// ```
#[inline]
pub fn merge(&mut self, other: &Average) {
pub fn merge(&mut self, other: &Mean) {
// This algorithm was proposed by Chan et al. in 1979.
//
// See https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance.
@ -113,17 +113,17 @@ impl Average {
}
}
impl core::default::Default for Average {
fn default() -> Average {
Average::new()
impl core::default::Default for Mean {
fn default() -> Mean {
Mean::new()
}
}
impl core::iter::FromIterator<f64> for Average {
fn from_iter<T>(iter: T) -> Average
impl core::iter::FromIterator<f64> for Mean {
fn from_iter<T>(iter: T) -> Mean
where T: IntoIterator<Item=f64>
{
let mut a = Average::new();
let mut a = Mean::new();
for i in iter {
a.add(i);
}

2
src/moments/mod.rs
View File

@ -1,2 +1,4 @@
include!("mean.rs");
include!("variance.rs");
pub type MeanWithError = Variance;

36
src/moments/variance.rs
View File

@ -7,23 +7,23 @@
/// ## Example
///
/// ```
/// use average::AverageWithError;
/// use average::Variance;
///
/// let a: AverageWithError = (1..6).map(Into::into).collect();
/// let a: Variance = (1..6).map(Into::into).collect();
/// println!("The average is {} ± {}.", a.mean(), a.error());
/// ```
#[derive(Debug, Clone)]
pub struct AverageWithError {
pub struct Variance {
/// Estimator of average.
avg: Average,
avg: Mean,
/// Intermediate sum of squares for calculating the variance.
sum_2: f64,
}
impl AverageWithError {
impl Variance {
/// Create a new average estimator.
pub fn new() -> AverageWithError {
AverageWithError { avg: Average::new(), sum_2: 0. }
pub fn new() -> Variance {
Variance { avg: Mean::new(), sum_2: 0. }
}
/// Add an observation sampled from the population.
@ -117,19 +117,19 @@ impl AverageWithError {
/// ## Example
///
/// ```
/// use average::AverageWithError;
/// use average::Variance;
///
/// let sequence: &[f64] = &[1., 2., 3., 4., 5., 6., 7., 8., 9.];
/// let (left, right) = sequence.split_at(3);
/// 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();
/// let avg_total: Variance = sequence.iter().map(|x| *x).collect();
/// let mut avg_left: Variance = left.iter().map(|x| *x).collect();
/// let avg_right: Variance = 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());
/// ```
#[inline]
pub fn merge(&mut self, other: &AverageWithError) {
pub fn merge(&mut self, other: &Variance) {
// This algorithm was proposed by Chan et al. in 1979.
//
// See https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance.
@ -142,17 +142,17 @@ impl AverageWithError {
}
}
impl core::default::Default for AverageWithError {
fn default() -> AverageWithError {
AverageWithError::new()
impl core::default::Default for Variance {
fn default() -> Variance {
Variance::new()
}
}
impl core::iter::FromIterator<f64> for AverageWithError {
fn from_iter<T>(iter: T) -> AverageWithError
impl core::iter::FromIterator<f64> for Variance {
fn from_iter<T>(iter: T) -> Variance
where T: IntoIterator<Item=f64>
{
let mut a = AverageWithError::new();
let mut a = Variance::new();
for i in iter {
a.add(i);
}

98
src/weighted_average.rs → src/weighted_mean.rs
View File

@ -1,6 +1,6 @@
use core;
use super::AverageWithError;
use super::MeanWithError;
/// Estimate the weighted and unweighted arithmetic mean of a sequence of
@ -10,24 +10,24 @@ use super::AverageWithError;
/// ## Example
///
/// ```
/// use average::WeightedAverage;
/// use average::WeightedMean;
///
/// let a: WeightedAverage = (1..6).zip(1..6)
/// let a: WeightedMean = (1..6).zip(1..6)
/// .map(|(x, w)| (f64::from(x), f64::from(w))).collect();
/// println!("The weighted average is {}.", a.mean());
/// println!("The weighted mean is {}.", a.mean());
/// ```
#[derive(Debug, Clone)]
pub struct WeightedAverage {
pub struct WeightedMean {
/// Sum of the weights.
weight_sum: f64,
/// Weighted average value.
/// Weighted mean value.
weighted_avg: f64,
}
impl WeightedAverage {
/// Create a new weighted and unweighted average estimator.
pub fn new() -> WeightedAverage {
WeightedAverage {
impl WeightedMean {
/// Create a new weighted and unweighted mean estimator.
pub fn new() -> WeightedMean {
WeightedMean {
weight_sum: 0., weighted_avg: 0.,
}
}
@ -35,7 +35,7 @@ impl WeightedAverage {
/// Add a weighted observation sampled from the population.
#[inline]
pub fn add(&mut self, sample: f64, weight: f64) {
// The algorithm for the unweighted average was suggested by Welford in 1962.
// The algorithm for the unweighted mean was suggested by Welford in 1962.
//
// See
// https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
@ -77,20 +77,20 @@ impl WeightedAverage {
/// ## Example
///
/// ```
/// use average::WeightedAverage;
/// use average::WeightedMean;
///
/// 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: WeightedMean = weighted_sequence.iter().map(|&x| x).collect();
/// let mut avg_left: WeightedMean = left.iter().map(|&x| x).collect();
/// let avg_right: WeightedMean = right.iter().map(|&x| x).collect();
/// avg_left.merge(&avg_right);
/// assert!((avg_total.mean() - avg_left.mean()).abs() < 1e-15);
/// ```
#[inline]
pub fn merge(&mut self, other: &WeightedAverage) {
pub fn merge(&mut self, other: &WeightedMean) {
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)
@ -99,17 +99,17 @@ impl WeightedAverage {
}
}
impl core::default::Default for WeightedAverage {
fn default() -> WeightedAverage {
WeightedAverage::new()
impl core::default::Default for WeightedMean {
fn default() -> WeightedMean {
WeightedMean::new()
}
}
impl core::iter::FromIterator<(f64, f64)> for WeightedAverage {
fn from_iter<T>(iter: T) -> WeightedAverage
impl core::iter::FromIterator<(f64, f64)> for WeightedMean {
fn from_iter<T>(iter: T) -> WeightedMean
where T: IntoIterator<Item=(f64, f64)>
{
let mut a = WeightedAverage::new();
let mut a = WeightedMean::new();
for (i, w) in iter {
a.add(i, w);
}
@ -126,38 +126,38 @@ impl core::iter::FromIterator<(f64, f64)> for WeightedAverage {
/// ## Example
///
/// ```
/// use average::WeightedAverageWithError;
/// use average::WeightedMeanWithError;
///
/// let a: WeightedAverageWithError = (1..6).zip(1..6)
/// let a: WeightedMeanWithError = (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());
/// println!("The weighted mean is {} ± {}.", a.weighted_mean(), a.error());
/// ```
#[derive(Debug, Clone)]
pub struct WeightedAverageWithError {
pub struct WeightedMeanWithError {
/// Sum of the squares of the weights.
weight_sum_sq: f64,
/// Estimator of the weighted average.
weighted_avg: WeightedAverage,
/// Estimator of unweighted average and its variance.
unweighted_avg: AverageWithError,
/// Estimator of the weighted mean.
weighted_avg: WeightedMean,
/// Estimator of unweighted mean and its variance.
unweighted_avg: MeanWithError,
}
impl WeightedAverageWithError {
/// Create a new weighted and unweighted average estimator.
impl WeightedMeanWithError {
/// Create a new weighted and unweighted mean estimator.
#[inline]
pub fn new() -> WeightedAverageWithError {
WeightedAverageWithError {
pub fn new() -> WeightedMeanWithError {
WeightedMeanWithError {
weight_sum_sq: 0.,
weighted_avg: WeightedAverage::new(),
unweighted_avg: AverageWithError::new(),
weighted_avg: WeightedMean::new(),
unweighted_avg: MeanWithError::new(),
}
}
/// Add a weighted observation sampled from the population.
#[inline]
pub fn add(&mut self, sample: f64, weight: f64) {
// The algorithm for the unweighted average was suggested by Welford in 1962.
// The algorithm for the weighted average was suggested by West in 1979.
// The algorithm for the unweighted mean was suggested by Welford in 1962.
// The algorithm for the weighted mean was suggested by West in 1979.
//
// See
// https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
@ -261,37 +261,37 @@ impl WeightedAverageWithError {
/// ## Example
///
/// ```
/// use average::WeightedAverageWithError;
/// use average::WeightedMeanWithError;
///
/// 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: 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();
/// let avg_total: WeightedMeanWithError = weighted_sequence.iter().map(|&x| x).collect();
/// let mut avg_left: WeightedMeanWithError = left.iter().map(|&x| x).collect();
/// let avg_right: WeightedMeanWithError = 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: &WeightedAverageWithError) {
pub fn merge(&mut self, other: &WeightedMeanWithError) {
self.weight_sum_sq += other.weight_sum_sq;
self.weighted_avg.merge(&other.weighted_avg);
self.unweighted_avg.merge(&other.unweighted_avg);
}
}
impl core::default::Default for WeightedAverageWithError {
fn default() -> WeightedAverageWithError {
WeightedAverageWithError::new()
impl core::default::Default for WeightedMeanWithError {
fn default() -> WeightedMeanWithError {
WeightedMeanWithError::new()
}
}
impl core::iter::FromIterator<(f64, f64)> for WeightedAverageWithError {
fn from_iter<T>(iter: T) -> WeightedAverageWithError
impl core::iter::FromIterator<(f64, f64)> for WeightedMeanWithError {
fn from_iter<T>(iter: T) -> WeightedMeanWithError
where T: IntoIterator<Item=(f64, f64)>
{
let mut a = WeightedAverageWithError::new();
let mut a = WeightedMeanWithError::new();
for (i, w) in iter {
a.add(i, w);
}

16
tests/average.rs → tests/mean.rs
View File

@ -6,11 +6,11 @@ extern crate rand;
use core::iter::Iterator;
use average::AverageWithError;
use average::MeanWithError;
#[test]
fn trivial() {
let mut a = AverageWithError::new();
let mut a = MeanWithError::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: AverageWithError = (1..6).map(f64::from).collect();
let a: MeanWithError = (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: AverageWithError = sample.iter().map(|x| *x).collect();
let a: MeanWithError = sample.iter().map(|x| *x).collect();
assert_eq!(a.sample_variance(), 30.);
}
@ -49,9 +49,9 @@ fn merge() {
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: 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();
let avg_total: MeanWithError = sequence.iter().map(|x| *x).collect();
let mut avg_left: MeanWithError = left.iter().map(|x| *x).collect();
let avg_right: MeanWithError = right.iter().map(|x| *x).collect();
avg_left.merge(&avg_right);
assert_eq!(avg_total.len(), avg_left.len());
assert_eq!(avg_total.mean(), avg_left.mean());
@ -63,7 +63,7 @@ fn merge() {
fn normal_distribution() {
use rand::distributions::{Normal, IndependentSample};
let normal = Normal::new(2.0, 3.0);
let mut a = AverageWithError::new();
let mut a = MeanWithError::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::AverageWithError = values.iter().map(|x| *x).collect();
let a: average::MeanWithError = 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-14);
@ -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::AverageWithError = values.iter().map(|x| *x).collect();
let a: average::MeanWithError = 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);

22
tests/weighted_average.rs → tests/weighted_mean.rs
View File

@ -4,11 +4,11 @@ extern crate core;
use core::iter::Iterator;
use average::WeightedAverageWithError;
use average::WeightedMeanWithError;
#[test]
fn trivial() {
let mut a = WeightedAverageWithError::new();
let mut a = WeightedMeanWithError::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: WeightedAverageWithError = (1..6).map(|x| (f64::from(x), 1.0)).collect();
let a: WeightedMeanWithError = (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: WeightedAverageWithError = values.iter().zip(weights.iter())
let a: WeightedMeanWithError = 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: WeightedAverageWithError = values.iter().zip(weights.iter())
let a: WeightedMeanWithError = values.iter().zip(weights.iter())
.map(|(x, w)| (*x, *w)).collect();
assert_eq!(a.error(), 0.5);
}
@ -70,9 +70,9 @@ fn merge_unweighted() {
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: 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();
let avg_total: WeightedMeanWithError = sequence.iter().map(|x| (*x, 1.)).collect();
let mut avg_left: WeightedMeanWithError = left.iter().map(|x| (*x, 1.)).collect();
let avg_right: WeightedMeanWithError = right.iter().map(|x| (*x, 1.)).collect();
avg_left.merge(&avg_right);
assert_eq!(avg_total.sum_weights(), avg_left.sum_weights());
@ -92,9 +92,9 @@ fn merge_weighted() {
(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: 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();
let avg_total: WeightedMeanWithError = sequence.iter().map(|&(x, w)| (x, w)).collect();
let mut avg_left: WeightedMeanWithError = left.iter().map(|&(x, w)| (x, w)).collect();
let avg_right: WeightedMeanWithError = right.iter().map(|&(x, w)| (x, w)).collect();
avg_left.merge(&avg_right);
assert_eq!(avg_total.len(), avg_left.len());
assert_almost_eq!(avg_total.sum_weights(), avg_left.sum_weights(), 1e-15);