From 80e92f61764da9b2f3447550cd294f77e68f35a1 Mon Sep 17 00:00:00 2001 From: Vinzent Steinberg Date: Mon, 29 May 2017 00:39:33 +0200 Subject: [PATCH] Update documentation --- Cargo.toml | 5 +++-- README.md | 12 ++++++----- src/lib.rs | 51 ++++++++++++++++++++++++++++++++++------------ src/moments/mod.rs | 1 + 4 files changed, 49 insertions(+), 20 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 7ca9209..1be497b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,10 +4,11 @@ name = "average" version = "0.5.0" license = "MIT/Apache-2.0" repository = "https://github.com/vks/average" -description = "Calculate the average of a sequence and its error iteratively" +description = "Calculate statistics iteratively" readme = "README.md" categories = ["science", "no-std"] -keywords = ["statistics", "stats"] +keywords = ["statistics", "stats", "mean", "variance", "skewness", + "kurtosis", "quantile"] [dependencies] conv = "0.3" diff --git a/README.md b/README.md index 7cdb6fe..31995c8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # average -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 +Calculate statistics of a sequence iteratively in a single pass, using +constant memory and avoiding numerical problems. The calculations can be easily parallelized by using `merge`. [Documentation](https://docs.rs/average) | @@ -9,7 +9,9 @@ easily parallelized by using `merge`. [![Build Status](https://travis-ci.org/vks/average.svg?branch=master)](https://travis-ci.org/vks/average) -## Advantages over naive calculation of average and variance +## Implemented statistics -* Avoids loss of precision due to cancellation. -* Only needs a single pass over the samples, at the cost of a division inside the loop. +* Mean and its error. +* Variance, skewness, kurtosis. +* Minium and maximum. +* Quantile. diff --git a/src/lib.rs b/src/lib.rs index a77ea08..aa62f95 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,14 +1,11 @@ -//! This crate provides estimators for the weighted and unweighted average of a -//! sequence of numbers, and for their standard errors. The typical workflow -//! looks like this: +//! This crate provides estimators for statistics on a sequence of numbers. The +//! typical workflow looks like this: //! -//! 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()` +//! 1. Initialize the estimator of your choice with `new()`. +//! 2. Add some subset (called "sample") of the sequence of numbers (called +//! "population") for which you want to estimate the statistic, using `add()` //! or `collect()`. -//! 3. Calculate the arithmetic mean with `mean()` and its standard error with -//! `error()`. +//! 3. Calculate the statistic with `mean()` or similar. //! //! You can run several estimators in parallel and merge them into one with //! `merge()`. @@ -17,10 +14,38 @@ //! so the sequence of numbers can be an iterator. The used algorithms try to //! avoid numerical instabilities. //! -//! [`Mean`]: ./average/struct.Mean.html -//! [`MeanWithError`]: ./average/struct.MeanWithError.html -//! [`WeightedMean`]: ./weighted_average/struct.WeightedMean.html -//! [`WeightedMeanWithError`]: ./weighted_average/struct.WeightedMeanWithError.html +//! +//! ## Estimators +//! +//! * Mean ([`Mean`]) and its error ([`MeanWithError`]). +//! * Weighted mean ([`WeightedMean`]) and its error +//! ([`WeightedMeanWithError`]). +//! * Variance ([`Variance`]), skewness ([`Skewness`]) and kurtosis +//! ([`Kurtosis`]). +//! * Quantiles ([`Quantile`]). +//! * Minimum ([`Min`]) and maximum ([`Max`]). +//! +//! [`Mean`]: ./struct.Mean.html +//! [`MeanWithError`]: ./type.MeanWithError.html +//! [`WeightedMean`]: ./struct.WeightedMean.html +//! [`WeightedMeanWithError`]: ./struct.WeightedMeanWithError.html +//! [`Variance`]: ./struct.Variance.html +//! [`Skewness`]: ./struct.Skewness.html +//! [`Kurtosis`]: ./struct.Kurtosis.html +//! [`Quantile`]: ./struct.Quantile.html +//! [`Min`]: ./struct.Min.html +//! [`Max`]: ./struct.Max.html +//! +//! +//! ## Estimating several statistics at once +//! +//! The estimators are designed to have minimal state. The recommended way to +//! calculate several of them at once is to create a struct with all the +//! estimators you need. You can then implement `add` for your struct by +//! forwarding to the underlying estimators. +//! +//! Note that calculating moments requires calculating the lower moments, so you +//! only need to include the highest moment in your struct. //! //! //! ## Example diff --git a/src/moments/mod.rs b/src/moments/mod.rs index d96921d..687d169 100644 --- a/src/moments/mod.rs +++ b/src/moments/mod.rs @@ -3,4 +3,5 @@ include!("variance.rs"); include!("skewness.rs"); include!("kurtosis.rs"); +/// Alias for `Variance`. pub type MeanWithError = Variance;