StatAcc.h

Classes

StatAcc -- A statistics accumulator (full description)

template<class T> class StatAcc

Interface

Public Members

StatAcc()

StatAcc(const StatAcc&)

~StatAcc()

void reset()

void copy(const StatAcc&)

StatAcc& operator= (const StatAcc&)

StatAcc operator+ (const StatAcc&)

StatAcc& operator+= (const StatAcc&)

inline void put(const T v)

inline void put(const T v, const Float w)

void put(const Array<T>& v)

void put(const Array<T>& v, const Array<Float>& w)

void put(const Block<T>& v)

void put(const Block<T>& v, const Block<Float>& w)

Double getWtot() const

uInt getCount() const

Fallible<Double> getMin() const

Fallible<Double> getMax() const

Fallible<Double> getMean() const

Fallible<Double> getRms() const

Fallible<Double> getVariance() const

Fallible<Double> getRmsAbs() const

void printSummaryList(std::ostream&, const ostream& caption) const

void printSummaryLine(std::ostream&, const ostream& caption) const

void printSummaryLineHeader(std::ostream&, const ostream& caption) const

Private Members

void put1(const T, const Float)

Description

Review Status

Programs:

Tests:

tStatAcc

Prerequisite

module Arrays
Arrays module

Etymology

StatAcc stands for `Statistics Accumulator'.

Template Type Argument Requirements (T)

Restriction to real types also allows the internal arithmetic type to be Double rather than the input type. The latter would give all kinds of complications with weighting, accuracy and overflow if the input type would be Int or uInt.

Synopsis

The (weighted) values are fed to StatAcc via the member function `put'. They can be fed individually, or in the form of an Array. The weights are optional (default = 1) and always have type Float.

Asking for a result does not change the internal state. The type of the returned results is always Fallible. A result is invalid if no input values with non-zero weight have been accumulated yet.

The accumulator can be re-initialised with the function `reset'. Accumulators can be added to each other, which is as if their combined values had been accumulated in the same accumulator.

Some functions have been provided to display a summary of the statistics results. One may choose between a one-line format (with an optional associated header line), and a list.

Example

   StatAcc<T> s;               // T is Float, Double, Int etc
   Matrix<T> vv(2,5);          // a matrix (array) of input values
   Matrix<Float> wgt(2,5);     // an associated matrix of weights
   .... fill vv and wgt with values and individual weights ... 
   s.put(vv,wgt);              // accumulate the weighted values   
   Fallible<Double> min = s.getMin();    // return the minimum value

   s.reset();                  // re-initialise
   s.put(vv);                  // if wgt omitted, default = 1.0
   if (s.getRms().isValid() {  // check validity of rms
         ... use it ...
   }

Motivation

One often needs simple statistics of a series of values, which may occur by themselves or in arrays at various points in a program. Sincs it is a pain to have to assign accumulation variables, and to write statistics evaluation code (including exceptions), this helper class is provided.

To Do

***************************************************************************

Member Description

StatAcc()
StatAcc(const StatAcc&)
~StatAcc()

constructors and destructor.

void reset()
void copy(const StatAcc&)

Reset or copy the accumulator attributes.

StatAcc& operator= (const StatAcc&)
StatAcc operator+ (const StatAcc&)
StatAcc& operator+= (const StatAcc&)

Operators for adding and copying accumulators.

inline void put(const T v)
inline void put(const T v, const Float w)
void put(const Array<T>& v)
void put(const Array<T>& v, const Array<Float>& w)
void put(const Block<T>& v)
void put(const Block<T>& v, const Block<Float>& w)

Accumulate input value(s) v with weight w. If weight is omitted, the default=1.

Double getWtot() const
uInt getCount() const
Fallible<Double> getMin() const
Fallible<Double> getMax() const
Fallible<Double> getMean() const
Fallible<Double> getRms() const
Fallible<Double> getVariance() const
Fallible<Double> getRmsAbs() const

Get statistics results one at a time. Count is the nr of values accumulated. Wtot is the sum of the weights. Rms is defined w.r.t. the mean, and is the square of Variance. RmsAbs is the root-mean-square of the absolute input values.

void printSummaryList(std::ostream&, const ostream& caption) const
void printSummaryLine(std::ostream&, const ostream& caption) const
void printSummaryLineHeader(std::ostream&, const ostream& caption) const

Print summary of accumulated statistics. Line is a one-line summary, including the (short) caption. LineHeader gives a one-line explanation of the numbers. List uses a separate line for each result (mean, max etc).

void put1(const T, const Float)

Accumulate a single weighted value.