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

Moments: Improve docs

Browse Source
This commit is contained in:
Vinzent Steinberg 2018-07-06 10:08:18 +02:00
parent 41e7df435d
commit 9f1c28147c
1 changed files with 27 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
src/moments/mod.rs
View File

@ -15,11 +15,23 @@ include!("kurtosis.rs");
/// Alias for `Variance`. /// Alias for `Variance`.
pub type MeanWithError = Variance; pub type MeanWithError = Variance;
/// The maximal order of the moment to be calculated.
const MAX_P: usize = 4; const MAX_P: usize = 4;
/// Estimate the first N moments of a sequence of numbers a sequence of numbers
/// ("population").
///
/// This uses a [general algorithm][paper] and is less efficient than the
/// specialized implementations (such as [`Mean`], [`Variance`], [`Skewness`]
/// and [`Kurtosis`]).
///
/// [paper]: https://doi.org/10.1007/s00180-015-0637-z.
/// [`Mean`]: ./struct.Mean.html
/// [`Variance`]: ./struct.Variance.html
/// [`Skewness`]: ./struct.Skewness.html
/// [`Kurtosis`]: ./struct.Kurtosis.html
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
// https://doi.org/10.1007/s00180-015-0637-z.
pub struct Moments { pub struct Moments {
/// Number of samples. /// Number of samples.
/// ///
@ -35,6 +47,7 @@ pub struct Moments {
} }
impl Moments { impl Moments {
/// Create a new moments estimator.
#[inline] #[inline]
pub fn new() -> Moments { pub fn new() -> Moments {
Moments { Moments {
@ -44,21 +57,27 @@ impl Moments {
} }
} }
/// 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
} }
/// Return the sample size.
#[inline] #[inline]
pub fn len(&self) -> u64 { pub fn len(&self) -> u64 {
self.n self.n
} }
/// Estimate the mean of the population.
///
/// Returns 0 for an empty sample.
#[inline] #[inline]
pub fn mean(&self) -> f64 { pub fn mean(&self) -> f64 {
self.avg self.avg
} }
/// Estimate the `p`th central moment of the population.
#[inline] #[inline]
pub fn central_moment(&self, p: usize) -> f64 { pub fn central_moment(&self, p: usize) -> f64 {
let n = f64::approx_from(self.n).unwrap(); let n = f64::approx_from(self.n).unwrap();
@ -69,6 +88,7 @@ impl Moments {
} }
} }
/// Estimate the `p`th standardized moment of the population.
#[inline] #[inline]
pub fn standardized_moment(&self, p: usize) -> f64 { pub fn standardized_moment(&self, p: usize) -> f64 {
let variance = self.central_moment(2); let variance = self.central_moment(2);
@ -82,6 +102,9 @@ impl Moments {
} }
} }
/// Calculate the sample variance.
///
/// This is an unbiased estimator of the variance of the population.
#[inline] #[inline]
pub fn sample_variance(&self) -> f64 { pub fn sample_variance(&self) -> f64 {
if self.n < 2 { if self.n < 2 {
@ -90,6 +113,7 @@ impl Moments {
self.m[0] / f64::approx_from(self.n - 1).unwrap() self.m[0] / f64::approx_from(self.n - 1).unwrap()
} }
/// Calculate the sample skewness.
#[inline] #[inline]
pub fn sample_skewness(&self) -> f64 { pub fn sample_skewness(&self) -> f64 {
if self.n < 2 { if self.n < 2 {
@ -106,6 +130,7 @@ impl Moments {
self.central_moment(3) / (self.central_moment(2) / n).powf(1.5) self.central_moment(3) / (self.central_moment(2) / n).powf(1.5)
} }
/// Calculate the sample excess kurtosis.
#[inline] #[inline]
pub fn sample_excess_kurtosis(&self) -> f64 { pub fn sample_excess_kurtosis(&self) -> f64 {
if self.n < 4 { if self.n < 4 {
@ -117,6 +142,7 @@ impl Moments {
3. * pow(n - 1., 2) / ((n - 2.) * (n - 3.)) 3. * pow(n - 1., 2) / ((n - 2.) * (n - 3.))
} }
/// Add an observation sampled from the population.
#[inline] #[inline]
pub fn add(&mut self, x: f64) { pub fn add(&mut self, x: f64) {
self.n += 1; self.n += 1;