HistAcc.h

Classes

HistAcc -- Makes a histogram from input values. (full description)

template<class T> class HistAcc

Interface

Public Members

HistAcc(const uInt nBuff)

HistAcc(const uInt nBuff, const T width)

HistAcc(const T low, const T high, const T width)

HistAcc(const HistAcc&)

~HistAcc()

void copy(const HistAcc&)

HistAcc& operator= (const HistAcc&)

inline void put(const T v)

void put(const Array<T>& vv)

void put(const Block<T>& vv)

void reset()

void emptyBinsWithLessThan(const uInt nmin)

Fallible<T> getPercentile(const Float p)

Fallible<T> getMedian()

Fallible<T> getBinWidth() const

const StatAcc<T>& getStatistics()

Fallible<uInt> getHistogram(Block<uInt>& bins, Block<T>& values)

uInt getSpurious(uInt& tooSmall, uInt& tooLarge)

void printHistogram(ostream&, const String& caption)

Private Members

void put1(const T)

void defineBins(const T low, const T high, const T width)

void initBuffer(const uInt size)

void putBuffer(const T v)

void clearBuffer()

void autoDefineBins()

void init()

Fallible<T> getBinValue(const uInt index) const

Description

Review Status

Programs:

Tests:

tHistAcc

Prerequisite

module Arrays
Arrays module

Etymology

HistAcc stands for `Histogram Accumulator'.

Template Type Argument Requirements (T)

The accepted input types are real, i.e. Int, uInt, Float, Double, but not Complex.

Synopsis

Makes a histogram from input values. The histogram bin parameters may be defined, or determined from the first n input values. The input values are fed to HistAcc via the member function `put'. They can be fed individually, or in the form of an Array.

The histogram `bins' can be defined via the constructor in the form of loop variables: low bin, high bin, bin-width. It is also possible to let the bin parameters be determined automatically from the first n (e.g. n=50) input values. If the actual nr of input values is less than n when the histogram is interrogated in some way, the bin parameters will be determined from what is available.

Example

It is usually convenient to let the bins be defined automatically:

   Matrix<T> vv(30,100);        // an array of input values
   vv = ...                     // fill the array
   HistAcc<T> h(25);            // use the first 25 values to define bins 
   h.put(vv);                   // accumulate values into histogram 
   h.printHistogram(cout,"vv"); // print the histogram of vv
   Fallible<Double> median = h1.getMedian();  // return the median

In some cases the bin parameters are pre-defined:

   Vector<T> vv(100,0);        // a vector (array) of values
   vv = ...                    // fill the vector
   HistAcc<T> h(-10,20,3);     // bins with width 3, between -10 and 20
   h.put(vv);                  // accumulate values into histogram   
   uInt n = h.getSpurious(l,h);// get the number outside the bins

The internal statistics accumulator can be interrogated explicitly or implicitly:

   StatAcc<T> s = h.getStatistics();     // return the internal StatAcc
   Fallible<Double> mean = s.getMean();  // get the mean of the input values
   Fallible<Double> mean = h.getStatistics().getMean();  // alternative

Motivation

To Do

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

Member Description

HistAcc(const uInt nBuff, const T width)

Constructors and destructor. If the bin-parameters low, high and width (for lowest and highest bin, and binwidth) are not specified, they will be determined automatically from the first nBuff input values (which are stored in a temporary buffer).

HistAcc(const T low, const T high, const T width)

HistAcc(const HistAcc&)

~HistAcc()

HistAcc(const uInt nBuff)

HistAcc& operator= (const HistAcc&)

Copy operations.

void copy(const HistAcc&)

Copy operations.

void put(const Array<T>& vv)

Accumulate (put) value(s) into the histogram.

void put(const Block<T>& vv)

Accumulate (put) value(s) into the histogram.

inline void put(const T v)

Accumulate (put) value(s) into the histogram.

void reset()

Reset the contents of the bins to zero, but retain the current bin definition.

void emptyBinsWithLessThan(const uInt nmin)

Empty all bins whose contents is < nmin (e.g. nmin=2). This is useful to remove `noise' values from the histogram.

Fallible<T> getPercentile(const Float p)

The median is the 50-percentile (getPercentile(50)), i.e. the value which has 50 percent of the input values below it. Calculation takes into account the spurious input values, i.e. values that fell outside the bins.

Fallible<T> getMedian()

Fallible<T> getBinWidth() const

All bins have the same width.

const StatAcc<T>& getStatistics()

Get the internal Statistics accumulator (see StatAcc,h). It can be used to obtain statistics of the input values.

Fallible<uInt> getHistogram(Block<uInt>& bins, Block<T>& values)

The return value is the nr of histogram bins, and is invalid if the number is zero. The given blocks/vectors are resized, and contain the contents and centre values of the bins.

uInt getSpurious(uInt& tooSmall, uInt& tooLarge)

Get the nr of `spurious' values, i.e. the ones that fell outside the defined bins.

void printHistogram(ostream&, const String& caption)

Print histogram.

void put1(const T)

Accumulate a single value into the histogram.

void defineBins(const T low, const T high, const T width)

Definition of histogram bins with given parameters.

void clearBuffer()

Internal helper functions for the automatic definition of histogram parameters, using the contents of itsBuffer.

void autoDefineBins()

Internal helper functions for the automatic definition of histogram parameters, using the contents of itsBuffer.

void initBuffer(const uInt size)
void putBuffer(const T v)

Internal helper functions for the automatic definition of histogram parameters, using the contents of itsBuffer.

void init()
Fallible<T> getBinValue(const uInt index) const

Other internal helper function(s).