Improve documentation
This commit is contained in:
parent
0d1e1c4f12
commit
cfab296f58
@ -1,8 +1,8 @@
|
|||||||
# average
|
# average
|
||||||
|
|
||||||
Calculate the average of a sequence and its error iteratively, using constant
|
Calculate the average of a sequence and its error iteratively in a single pass,
|
||||||
memory and avoiding numerical problems. The calculation can be easily parallelized
|
using constant memory and avoiding numerical problems. The calculation can be
|
||||||
by using `Average::merge`.
|
easily parallelized by using `merge`.
|
||||||
|
|
||||||
[Documentation](https://docs.rs/average) |
|
[Documentation](https://docs.rs/average) |
|
||||||
[crates.io](https://crates.io/crates/average)
|
[crates.io](https://crates.io/crates/average)
|
||||||
|
@ -5,10 +5,6 @@ use conv::ApproxFrom;
|
|||||||
|
|
||||||
/// Estimate the arithmetic mean of a sequence of numbers ("population").
|
/// 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
|
/// ## Example
|
||||||
///
|
///
|
||||||
@ -33,7 +29,7 @@ impl Average {
|
|||||||
Average { avg: 0., n: 0 }
|
Average { avg: 0., n: 0 }
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Add an element sampled from the population.
|
/// Add an observation sampled from the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn add(&mut self, sample: f64) {
|
pub fn add(&mut self, sample: f64) {
|
||||||
// This algorithm introduced by Welford in 1962 trades numerical
|
// This algorithm introduced by Welford in 1962 trades numerical
|
||||||
@ -45,7 +41,7 @@ impl Average {
|
|||||||
self.avg += delta / f64::approx_from(self.n).unwrap();
|
self.avg += delta / f64::approx_from(self.n).unwrap();
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Determine whether the samples are empty.
|
/// Determine whether the sample is empty.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn is_empty(&self) -> bool {
|
pub fn is_empty(&self) -> bool {
|
||||||
self.n == 0
|
self.n == 0
|
||||||
@ -57,7 +53,7 @@ impl Average {
|
|||||||
self.avg
|
self.avg
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Return the number of samples.
|
/// Return the sample size.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn len(&self) -> u64 {
|
pub fn len(&self) -> u64 {
|
||||||
self.n
|
self.n
|
||||||
@ -120,10 +116,6 @@ impl core::iter::FromIterator<f64> for Average {
|
|||||||
///
|
///
|
||||||
/// This can be used to estimate the standard error of the mean.
|
/// 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
|
/// ## Example
|
||||||
///
|
///
|
||||||
@ -147,7 +139,7 @@ impl AverageWithError {
|
|||||||
AverageWithError { avg: Average::new(), v: 0. }
|
AverageWithError { avg: Average::new(), v: 0. }
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Add an element sampled from the population.
|
/// Add an observation sampled from the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn add(&mut self, sample: f64) {
|
pub fn add(&mut self, sample: f64) {
|
||||||
// This algorithm introduced by Welford in 1962 trades numerical
|
// This algorithm introduced by Welford in 1962 trades numerical
|
||||||
@ -159,7 +151,7 @@ impl AverageWithError {
|
|||||||
self.v += delta * (sample - self.avg.mean());
|
self.v += delta * (sample - self.avg.mean());
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Determine whether the samples are empty.
|
/// Determine whether the sample is empty.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn is_empty(&self) -> bool {
|
pub fn is_empty(&self) -> bool {
|
||||||
self.avg.is_empty()
|
self.avg.is_empty()
|
||||||
@ -171,7 +163,7 @@ impl AverageWithError {
|
|||||||
self.avg.mean()
|
self.avg.mean()
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Return the number of samples.
|
/// Return the sample size.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn len(&self) -> u64 {
|
pub fn len(&self) -> u64 {
|
||||||
self.avg.len()
|
self.avg.len()
|
||||||
|
@ -13,6 +13,10 @@
|
|||||||
//! You can run several estimators in parallel and merge them into one with
|
//! You can run several estimators in parallel and merge them into one with
|
||||||
//! `merge()`.
|
//! `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
|
//! [`Average`]: ./average/struct.Average.html
|
||||||
//! [`AverageWithError`]: ./average/struct.AverageWithError.html
|
//! [`AverageWithError`]: ./average/struct.AverageWithError.html
|
||||||
//! [`WeightedAverage`]: ./weighted_average/struct.WeightedAverage.html
|
//! [`WeightedAverage`]: ./weighted_average/struct.WeightedAverage.html
|
||||||
|
@ -14,9 +14,6 @@ fn max(a: f64, b: f64) -> f64 {
|
|||||||
|
|
||||||
/// Estimate the minimum of a sequence of numbers ("population").
|
/// 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
|
/// ## Example
|
||||||
///
|
///
|
||||||
@ -46,7 +43,7 @@ impl Min {
|
|||||||
Min::from_value(::core::f64::INFINITY)
|
Min::from_value(::core::f64::INFINITY)
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Add an element sampled from the population.
|
/// Add an observation sampled from the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn add(&mut self, x: f64) {
|
pub fn add(&mut self, x: f64) {
|
||||||
self.r.add(x);
|
self.r.add(x);
|
||||||
@ -94,9 +91,6 @@ impl core::iter::FromIterator<f64> for Min {
|
|||||||
|
|
||||||
/// Estimate the maximum of a sequence of numbers ("population").
|
/// 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
|
/// ## Example
|
||||||
///
|
///
|
||||||
@ -126,7 +120,7 @@ impl Max {
|
|||||||
Max::from_value(::core::f64::NEG_INFINITY)
|
Max::from_value(::core::f64::NEG_INFINITY)
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Add an element sampled from the population.
|
/// Add an observation sampled from the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn add(&mut self, x: f64) {
|
pub fn add(&mut self, x: f64) {
|
||||||
self.r.add(x);
|
self.r.add(x);
|
||||||
|
@ -32,7 +32,7 @@ impl WeightedAverage {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Add a weighted element sampled from the population.
|
/// Add a weighted observation sampled from the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn add(&mut self, sample: f64, weight: f64) {
|
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 average was suggested by Welford in 1962.
|
||||||
@ -61,7 +61,7 @@ impl WeightedAverage {
|
|||||||
self.weight_sum
|
self.weight_sum
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Estimate the weighted mean of the sequence.
|
/// Estimate the weighted mean of the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn mean(&self) -> f64 {
|
pub fn mean(&self) -> f64 {
|
||||||
self.weighted_avg
|
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]
|
#[inline]
|
||||||
pub fn add(&mut self, sample: f64, weight: f64) {
|
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 average was suggested by Welford in 1962.
|
||||||
@ -182,19 +182,19 @@ impl WeightedAverageWithError {
|
|||||||
self.weight_sum_sq
|
self.weight_sum_sq
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Estimate the weighted mean of the sequence.
|
/// Estimate the weighted mean of the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn weighted_mean(&self) -> f64 {
|
pub fn weighted_mean(&self) -> f64 {
|
||||||
self.weighted_avg.mean()
|
self.weighted_avg.mean()
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Estimate the unweighted mean of the sequence.
|
/// Estimate the unweighted mean of the population.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn unweighted_mean(&self) -> f64 {
|
pub fn unweighted_mean(&self) -> f64 {
|
||||||
self.unweighted_avg.mean()
|
self.unweighted_avg.mean()
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Return sample size.
|
/// Return the sample size.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn len(&self) -> u64 {
|
pub fn len(&self) -> u64 {
|
||||||
self.unweighted_avg.len()
|
self.unweighted_avg.len()
|
||||||
@ -224,7 +224,7 @@ impl WeightedAverageWithError {
|
|||||||
self.unweighted_avg.sample_variance()
|
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.
|
/// Returns 0 if the sum of weights is 0.
|
||||||
///
|
///
|
||||||
|
Loading…
x
Reference in New Issue
Block a user