Template Class RunningStats

Class Documentation

template<typename T>
class RunningStats

Computation of running average and variance using Welford’s algorithm.

This class can keep track of mean and variance of a stream of data using an efficient online algorithm. The required memory is constant, and time to insert a new value and update the stats is also constant.

You can also add and subtract instances of this class which behaves as if you merged / diffed the streams that created the stats.

Template Parameters:

T – Type of the values. It has to support operator+ and operator- with T.

Public Functions

void reset()

Reset the statistics to represent an empty sequence.

void addSample(T x)

Add a new sample to the statistics.

Note

This function runs in O(1) time.

Parameters:

x – [in] The sample to add.

void removeSample(T x)

Remove a sample from the statistics.

Note

This function runs in O(1) time.

Note

It is the responsibility of the caller to make sure the sample being removed has actually been added before. If that is not true, the computed statistics will stop being valid.

Note

Removing from an empty instance does nothing.

Parameters:

x – [in] The sample to remove.

size_t getCount() const

Get the number of stored samples.

Returns:

The number of samples.

T getMean() const

Get the mean of stored samples.

Note

This function runs in O(1) time.

Returns:

The mean.

T getVariance() const

Get the variance of stored samples.

Note

This function runs in O(1) time.

Returns:

The variance.

T getSampleVariance() const

Get the sample variance of stored samples (like variance, but divided by count-1 instead of count, should be unbiased estimator).

Note

This function runs in O(1) time.

Returns:

The sample variance.

T getStandardDeviation() const

Get standard deviation of stored samples.

Note

The standard deviation computation is based on the sample variance.

Note

This function runs in O(1) time.

Returns:

The standard deviation.

RunningStats<T> &operator+=(const RunningStats<T> &other)

Combine the two sequences represented by this and other and represent their joint stats.

Note

This function runs in O(1) time.

Parameters:

other – [in] The other stats to merge.

Returns:

This.

RunningStats<T> operator+(const RunningStats<T> &other) const

Combine the two sequences represented by this and other and represent their joint stats.

Note

This function runs in O(1) time.

Parameters:

other – [in] The other stats to merge.

Returns:

The combined stats.

RunningStats<T> &operator+=(const T &sample)

Add the sample to the stats.

Note

This function runs in O(1) time.

Parameters:

sample – [in] The sample to add.

Returns:

This.

RunningStats<T> operator+(const T &sample) const

Return a copy of this with the added sample.

Note

This function runs in O(1) time.

Parameters:

sample – [in] The sample to add.

Returns:

The new stats.

RunningStats<T> &operator-=(const RunningStats<T> &other)

Subtract the sequence represented by other from the sequence represented by this and update the stats.

Note

If other is longer than this, empty stats will be returned.

Note

This function runs in O(1) time.

Parameters:

other – [in] The stats to subtract.

Returns:

This.

RunningStats<T> operator-(const RunningStats<T> &other) const

Subtract the sequence represented by other from the sequence represented by this and return the updated stats.

Note

If other is longer than this, empty stats will be returned.

Note

This function runs in O(1) time.

Parameters:

other – [in] The stats to subtract.

Returns:

The stats with other removed.

RunningStats<T> &operator-=(const T &sample)

Remove a sample from the statistics.

Note

This function runs in O(1) time.

Note

It is the responsibility of the caller to make sure the sample being removed has actually been added before. If that is not true, the computed statistics will stop being valid.

Note

Removing from an empty instance does nothing.

Parameters:

sample – [in] The sample to remove.

Returns:

This.

RunningStats<T> operator-(const T &sample) const

Remove a sample from the statistics.

Note

This function runs in O(1) time.

Note

It is the responsibility of the caller to make sure the sample being removed has actually been added before. If that is not true, the computed statistics will stop being valid.

Note

Removing from an empty instance does nothing.

Parameters:

sample – [in] The sample to remove.

Returns:

The stats with sample removed.

Protected Attributes

size_t count = {0u}

Number of represented samples.

T mean = {RunningStats<T>::zero()}

Mean of represented samples.

T var = {RunningStats<T>::zero()}

Sk term of the computation such that var(X0…Xk) = this->var/this->count.

Protected Static Functions

static T multiplyScalar(const T &val, double scalar)

val * scalar

Parameters:

  • val – [in] The value to multiply.

  • scalar – [in] The scalar to multiply with.

Returns:

val * scalar

static T multiply(const T &val1, const T &val2)

val1 * val2

Parameters:

  • val1 – [in] Multiplicand.

  • val2 – [in] Multiplicand.

Returns:

val1 * val2

static T sqrt(const T &val)

Return the square root of the given value (whatever meaning that might have).

Parameters:

val – [in] The value to take root of.

Returns:

The square root.

static T zero()

Return a T value representing zero.

Returns:

0.