# Crate average[−][src]

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

- If necessary, build your custom estimator using
`concatenate`

. - Initialize the estimator of your choice with
`new()`

. - Add some subset (called "sample") of the sequence of numbers (called
"population") for which you want to estimate the statistic, using
`add()`

or`collect()`

. - 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(); a.add(42.); println!("The mean is {} ± {}.", a.mean(), a.error());

## 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`

).

## 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!(..., 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 |

## Structs

Histogram10 |
A histogram with a number of bins known at compile time. |

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 |