# Crate average[−][src]

This crate provides estimators for statistics on a sequence of numbers. The typical workflow looks like this:

1. If necessary, build your custom estimator using `concatenate`.
2. Initialize the estimator of your choice with `new()`.
3. Add some subset (called "sample") of the sequence of numbers (called "population") for which you want to estimate the statistic, using `add()` or `collect()`.
4. Calculate the statistic with `mean()` or similar.

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.

If you want Serde support, include `"serde"` in your list of features.

Note that deserializing does not currently check for all invalid inputs. For example, if you deserialize a corrupted `Variance` it may return a negative value for variance, even though that is mathematically impossible. In a future minor release some of these checks may be added.

### Example

```use average::{MeanWithError, Estimate};

let mut a: MeanWithError = (1..6).map(f64::from).collect();
println!("The mean is {} ± {}.", a.mean(), a.error());```

## 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. Everything is inlined, so there should be no overhead.

You can avoid the boilerplate code by using the `concatenate` macro.

Note that calculating moments requires calculating the lower moments, so you only need to include the highest moment in your struct.

## Calculating histograms

The `define_histogram` macro can be used to define a histogram struct that uses constant memory. See `Histogram10` (defined using `define_histogram!(Histogram10, 10)`) and the extension trait `Histogram` for the methods available to the generated struct.

## Macros

 assert_almost_eq Assert that two numbers are almost equal to each other. concatenate Concatenate several iterative estimators into one. define_histogram Define a histogram with a number of bins known at compile time. define_moments Define an estimator of all moments up to a number given at compile time. impl_from_iterator Implement `FromIterator` for an iterative estimator.

## Structs

 Histogram10 A histogram with a number of bins known at compile time. IterHistogram Iterate over all `(range, count)` pairs in the histogram. Kurtosis Estimate the arithmetic mean, the variance, the skewness and the kurtosis of a sequence of numbers ("population"). Max Estimate the maximum of a sequence of numbers ("population"). Mean Estimate the arithmetic mean of a sequence of numbers ("population"). Min Estimate the minimum of a sequence of numbers ("population"). Moments4 Estimate the first N moments of a sequence of numbers a sequence of numbers ("population"). Quantile Estimate the p-quantile of a sequence of numbers ("population"). Skewness Estimate the arithmetic mean, the variance and the skewness of a sequence of numbers ("population"). Variance Estimate the arithmetic mean and the variance of a sequence of numbers ("population"). WeightedMean Estimate the weighted and unweighted arithmetic mean of a sequence of numbers ("population"). WeightedMeanWithError Estimate the weighted and unweighted arithmetic mean and the unweighted variance of a sequence of numbers ("population").

## Traits

 Estimate Estimate a statistic of a sequence of numbers ("population"). Histogram Get the bins and ranges from a histogram. Merge Merge another sample into this one.

## Type Definitions

 MeanWithError Alias for `Variance`.