# Crate average[−][src]

## Expand description

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`

or`define_moments`

. - 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 `"serde1"`

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`

). - Arbitrary higher moments (
`define_moments`

). - 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 |

impl_from_par_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 (“population”). |

Quantile | `std` or `libm` Estimate the p-quantile of a sequence of numbers (“population”). |

SampleOutOfRangeError | A sample is out of range of the histogram. |

Skewness | `std` or `libm` 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”). |

## Enums

InvalidRangeError | Invalid ranges were specified for constructing the histogram. |

## Traits

Estimate | Estimate a statistic of a sequence of numbers (“population”). |

Histogram | Get the bins and ranges from a histogram. |

Merge | Merge with another estimator. |

## Type Definitions

MeanWithError | Alias for |