RunningAverage

Arduino library to calculate the running average by means of a circular buffer.

Description

The RunningAverage object gives a running average of the last N floating point numbers, giving them all equal weight. This is done by adding new data to an internal circular buffer, removing the oldest and replace it by the newest. The size of the internal buffer can be set in the constructor.

By keeping track of the _sum the runningAverage can be calculated fast (only 1 division) at any time. This is done with getFastAverage(). However the constant adding and subtracting when adding new elements to the RA object possibly introduces an ever increasing error. In tests adding up to 1500000 numbers this error was always small. But that is no proof. In version 0.2.16 a fix was added that uses the calculation of the sum in getAverage() to update the internal _sum.

Related

• https://github.com/RobTillaart/Correlation
• https://github.com/RobTillaart/GST - Golden standard test metrics
• https://github.com/RobTillaart/Histogram
• https://github.com/RobTillaart/RunningAngle
• https://github.com/RobTillaart/RunningAverage
• https://github.com/RobTillaart/RunningMedian
• https://github.com/RobTillaart/statHelpers - combinations & permutations
• https://github.com/RobTillaart/Statistic

Interface

#include "RunningAverage.h"

Constructor

• RunningAverage(uint16_t size) allocates dynamic memory, one float (4 bytes) per element. No default size (yet).
• ~RunningAverage() destructor to free the memory allocated.

Basic

• void clear() empties the internal buffer.
• void add(float value) wrapper for addValue()
• void addValue(float value) adds a new value to the object, if the internal buffer is full, the oldest element is removed.
• void fillValue(float value, uint16_t number) adds number elements of value. Good for initializing the system to a certain starting average.
• float getValue(uint16_t position) returns the value at position from the additions. Position 0 is the first one to disappear.
• float getAverage() iterates over all elements to get the average, slower but accurate. Updates the variables used by getFastAverage() to improve its accuracy again.
• float getFastAverage() reuses previous calculated values, therefore faster. Accuracy can drift.

Extended functions

• float getStandardDeviation() returns the standard deviation of the current content. Needs more than one element to be calculable.
• float getStandardError() returns the standard error of the current content.
• float getMin() returns minimum since last clear, does not need to be in the buffer any more.
• float getMax() returns maximum since last clear, does not need to be in the buffer any more.
• float getMinInBuffer() returns minimum in the internal buffer.
• float getMaxInBuffer() returns maximum in the internal buffer.

Admin functions

• bool bufferIsFull() returns true if buffer is full.
• float getElement(uint16_t index) get element directly from internal buffer at index. (debug)
• uint16_t getSize() returns the size of the internal array.
• uint16_t getCount() returns the number of slots used of the internal array.

Partial functions

• void setPartial(uint16_t partial = 0) use only a part of the internal array. Allows to change the weight and history factor. 0 ==> use all == default.
• uint16_t getPartial() returns the set value for partial.

Last functions

These functions get the basic statistics of the last N added elements. Returns NAN if there are no elements and it will reduce count if there are less than count elements in the buffer.

• float getAverageLast(uint16_t count) get the average of the last count elements.
• float getMinInBufferLast(uint16_t count) get the minimum of the last count elements.
• float getMaxInBufferLast(uint16_t count) get the maximum of the last count elements.

These functions are useful in cases where you might want to calculate and display the statistics of a subset of the added elements. Reason might be to compare this with the numbers of the whole buffer to notice changes earlier. Otherwise one should create multiple RunningAverage objects each with its own length, effectively having multiple copies of the data added.

Note: if called with a value larger or equal to getCount() (including getSize()) as parameter, the functions will return the statistics of the whole buffer.

Subset (experimental)

• float getAverageSubset(uint16_t start, uint16_t count) Get the average of subset - count elements from start.

Operation

See examples

Future

Must

• update documentation, explain better

Should

• check for optimizations.
  • divide by count happens often ...
• clear(bool zero = true) to suppress setting all to 0. ?

Could

• create a double based derived class? Template class?
• add error handling (important?).
• investigate modus() most frequently occurring value.
  • difficult with floats ?
  • what to do when on two or more values are on par?

Wont

• default size for constructor
  • unknown what would be a good choice.
• clear(bool zero = true) to suppress setting all to 0. ?
  • makes addValue() slightly more complex
  • could introduce conflicts due to randomness data?

Support

If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.

Thank you,