From cfab296f585746ebbe62931ce70a8549feecadba Mon Sep 17 00:00:00 2001 From: Vinzent Steinberg Date: Wed, 24 May 2017 19:45:58 +0200 Subject: [PATCH] Improve documentation --- README.md | 6 +++--- src/average.rs | 20 ++++++-------------- src/lib.rs | 4 ++++ src/minmax.rs | 10 ++-------- src/weighted_average.rs | 14 +++++++------- 5 files changed, 22 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 5033651..7cdb6fe 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # average -Calculate the average of a sequence and its error iteratively, using constant -memory and avoiding numerical problems. The calculation can be easily parallelized -by using `Average::merge`. +Calculate the average of a sequence and its error iteratively in a single pass, +using constant memory and avoiding numerical problems. The calculation can be +easily parallelized by using `merge`. [Documentation](https://docs.rs/average) | [crates.io](https://crates.io/crates/average) diff --git a/src/average.rs b/src/average.rs index 324e7ea..63f918a 100644 --- a/src/average.rs +++ b/src/average.rs @@ -5,10 +5,6 @@ use conv::ApproxFrom; /// Estimate the arithmetic mean of a sequence of numbers ("population"). /// -/// Everything is calculated iteratively using constant memory, so the sequence -/// of numbers can be an iterator. The used algorithms try to avoid numerical -/// instabilities. -/// /// /// ## Example /// @@ -33,7 +29,7 @@ impl Average { Average { avg: 0., n: 0 } } - /// Add an element sampled from the population. + /// Add an observation sampled from the population. #[inline] pub fn add(&mut self, sample: f64) { // This algorithm introduced by Welford in 1962 trades numerical @@ -45,7 +41,7 @@ impl Average { self.avg += delta / f64::approx_from(self.n).unwrap(); } - /// Determine whether the samples are empty. + /// Determine whether the sample is empty. #[inline] pub fn is_empty(&self) -> bool { self.n == 0 @@ -57,7 +53,7 @@ impl Average { self.avg } - /// Return the number of samples. + /// Return the sample size. #[inline] pub fn len(&self) -> u64 { self.n @@ -120,10 +116,6 @@ impl core::iter::FromIterator for Average { /// /// This can be used to estimate the standard error of the mean. /// -/// Everything is calculated iteratively using constant memory, so the sequence -/// of numbers can be an iterator. The used algorithms try to avoid numerical -/// instabilities. -/// /// /// ## Example /// @@ -147,7 +139,7 @@ impl AverageWithError { AverageWithError { avg: Average::new(), v: 0. } } - /// Add an element sampled from the population. + /// Add an observation sampled from the population. #[inline] pub fn add(&mut self, sample: f64) { // This algorithm introduced by Welford in 1962 trades numerical @@ -159,7 +151,7 @@ impl AverageWithError { self.v += delta * (sample - self.avg.mean()); } - /// Determine whether the samples are empty. + /// Determine whether the sample is empty. #[inline] pub fn is_empty(&self) -> bool { self.avg.is_empty() @@ -171,7 +163,7 @@ impl AverageWithError { self.avg.mean() } - /// Return the number of samples. + /// Return the sample size. #[inline] pub fn len(&self) -> u64 { self.avg.len() diff --git a/src/lib.rs b/src/lib.rs index 0665592..966b5cf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,6 +13,10 @@ //! You can run several estimators in parallel and merge them into one with //! `merge()`. //! +//! Everything is calculated iteratively in a single pass using constant memory, +//! 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 diff --git a/src/minmax.rs b/src/minmax.rs index e83229c..7f6f95e 100644 --- a/src/minmax.rs +++ b/src/minmax.rs @@ -14,9 +14,6 @@ fn max(a: f64, b: f64) -> f64 { /// Estimate the minimum of a sequence of numbers ("population"). /// -/// Everything is calculated iteratively using constant memory, so the sequence -/// of numbers can be an iterator. -/// /// /// ## Example /// @@ -46,7 +43,7 @@ impl Min { Min::from_value(::core::f64::INFINITY) } - /// Add an element sampled from the population. + /// Add an observation sampled from the population. #[inline] pub fn add(&mut self, x: f64) { self.r.add(x); @@ -94,9 +91,6 @@ impl core::iter::FromIterator for Min { /// Estimate the maximum of a sequence of numbers ("population"). /// -/// Everything is calculated iteratively using constant memory, so the sequence -/// of numbers can be an iterator. -/// /// /// ## Example /// @@ -126,7 +120,7 @@ impl Max { Max::from_value(::core::f64::NEG_INFINITY) } - /// Add an element sampled from the population. + /// Add an observation sampled from the population. #[inline] pub fn add(&mut self, x: f64) { self.r.add(x); diff --git a/src/weighted_average.rs b/src/weighted_average.rs index 3cd0918..62fd945 100644 --- a/src/weighted_average.rs +++ b/src/weighted_average.rs @@ -32,7 +32,7 @@ impl WeightedAverage { } } - /// Add a weighted element sampled from the population. + /// 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. @@ -61,7 +61,7 @@ impl WeightedAverage { self.weight_sum } - /// Estimate the weighted mean of the sequence. + /// Estimate the weighted mean of the population. #[inline] pub fn mean(&self) -> f64 { self.weighted_avg @@ -149,7 +149,7 @@ impl WeightedAverageWithError { } } - /// Add a weighted element sampled from the population. + /// 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. @@ -182,19 +182,19 @@ impl WeightedAverageWithError { self.weight_sum_sq } - /// Estimate the weighted mean of the sequence. + /// Estimate the weighted mean of the population. #[inline] pub fn weighted_mean(&self) -> f64 { self.weighted_avg.mean() } - /// Estimate the unweighted mean of the sequence. + /// Estimate the unweighted mean of the population. #[inline] pub fn unweighted_mean(&self) -> f64 { self.unweighted_avg.mean() } - /// Return sample size. + /// Return the sample size. #[inline] pub fn len(&self) -> u64 { self.unweighted_avg.len() @@ -224,7 +224,7 @@ impl WeightedAverageWithError { self.unweighted_avg.sample_variance() } - /// Estimate the standard error of the *weighted* mean of the sequence. + /// Estimate the standard error of the *weighted* mean of the population. /// /// Returns 0 if the sum of weights is 0. ///