Loading...
Searching...
No Matches
HistAcc.h
Go to the documentation of this file.
//# HistAcc.h: Histogram Accumulator
//# Copyright (C) 1996,1999,2000,2001
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef SCIMATH_HISTACC_H
#define SCIMATH_HISTACC_H
#include <casacore/casa/aips.h>
#include <casacore/casa/Utilities/Fallible.h>
#include <casacore/scimath/Mathematics/StatAcc.h>
#include <casacore/casa/Containers/Block.h>
#include <casacore/casa/iosfwd.h>
#include <casacore/casa/Arrays/ArrayFwd.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// forward declarations:
class String;
// <reviewed reviewer="" date="" tests="tHistAcc" demos="">
// <prerequisite>
// <li> module Arrays
// <li> <linkto module="Arrays:description">Arrays </linkto> module
// </prerequisite>
//
// <summary>
// Makes a histogram from input values.
// </summary>
//
// <etymology>
// HistAcc stands for `Histogram Accumulator'.
// </etymology>
//
// <templating arg=T>
// <li> The accepted input types are real, i.e. Int, uInt, Float, Double,
// but not Complex.
// </templating>
// <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.
// </synopsis>
//
// <example>
// It is usually convenient to let the bins be defined automatically:
// <srcblock>
// 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
// </srcblock>
//
// In some cases the bin parameters are pre-defined:
// <srcblock>
// 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
// </srcblock>
//
// The internal statistics accumulator can be interrogated explicitly
// or implicitly:
// <srcblock>
// 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
// </srcblock>
// </example>
//
// <motivation>
// </motivation>
//
// <todo asof="">
// </todo>
// ***************************************************************************
template<class T> class HistAcc {
public:
// 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).
// <group>
HistAcc(const uInt nBuff); //# fully automatic
HistAcc(const uInt nBuff, const T width); //# semi-automatic
HistAcc(const T low, const T high, const T width); //# fully specified
HistAcc(const HistAcc&); //# copy an existing one
~HistAcc(){;}
// </group>
// Copy operations.
// <group>
void copy(const HistAcc&); //# idem
HistAcc& operator= (const HistAcc&);
// </group>
// Accumulate (put) value(s) into the histogram.
// <group>
inline void put(const T v); //# single value
void put(const Array<T>& vv); //# array
void put(const Block<T>& vv); //# block (simple array)
// </group>
// Reset the contents of the bins to zero, but retain the current
// bin definition.
void reset();
// Empty all bins whose contents is < nmin (e.g. nmin=2).
// This is useful to remove `noise' values from the histogram.
void emptyBinsWithLessThan(const uInt nmin);
// 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> getPercentile(const Float p);
Fallible<T> getMedian();
// All bins have the same width.
Fallible<T> getBinWidth() const;
// Get the internal Statistics accumulator (see StatAcc,h).
// It can be used to obtain statistics of the input values.
const StatAcc<T>& getStatistics();
// 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.
Fallible<uInt> getHistogram(Block<uInt>& bins, Block<T>& values);
// Get the nr of `spurious' values, i.e. the ones that fell
// outside the defined bins.
uInt getSpurious(uInt& tooSmall, uInt& tooLarge);
// Print histogram.
// <group>
void printHistogram(ostream&, const String& caption);
// </group>
private:
Block<uInt> itsBinContents; //# Contents of histogram bins
Block<T> itsBinHighLimit; //# High limit of each bin
T itsUserDefinedBinWidth; //# if defined
StatAcc<T> itsStatAcc; //# private Statistics Accumulator
Bool itsAutoDefineMode; //# If true: automatic mode
Block<T> itsBuffer; //# temporary storage of input T-values
uInt itsBufferContents; //# nr of T-values in buffer
// Accumulate a single value into the histogram.
void put1(const T);
// Definition of histogram bins with given parameters.
void defineBins(const T low, const T high, const T width);
// Internal helper functions for the automatic definition of
// histogram parameters, using the contents of itsBuffer.
// <group>
void initBuffer(const uInt size);
void putBuffer(const T v); //# add input value to itsBuffer
void clearBuffer(); //# transfer from buffer to bins
void autoDefineBins();
// </group>
// Other internal helper function(s).
// <group>
void init();
Fallible<T> getBinValue(const uInt index) const; //# bin centre value
// </group>
};
//*************************** inline functions, have to be in HistAcc.h ****
// Accumulate a single value:
template<class T>
inline void HistAcc<T>::put(const T v) {
put1(v);
}
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/scimath/Mathematics/HistAcc.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::Array
Definition Array.h:155
casacore::Block
simple 1-D array
Definition Block.h:198
casacore::Fallible
Mark a value as valid or invalid.
Definition Fallible.h:121
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::HistAcc
HistAcc(const uInt nBuff)
Makes a histogram from input values.
casacore::StatAcc
StatAcc()
A statistics accumulator
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::defineBins
void defineBins(const T low, const T high, const T width)
Definition of histogram bins with given parameters.
casacore::autoDefineBins
void autoDefineBins()
casacore::clearBuffer
void clearBuffer()
casacore::put1
void put1(const T)
Accumulate a single value into the histogram.
casacore::itsBinHighLimit
Block< T > itsBinHighLimit
Definition HistAcc.h:180
casacore::putBuffer
void putBuffer(const T v)
casacore::~HistAcc
~HistAcc()
Definition HistAcc.h:126
casacore::itsBufferContents
uInt itsBufferContents
Definition HistAcc.h:187
casacore::printHistogram
void printHistogram(ostream &, const String &caption)
Get the nr of `spurious' values, i.e.
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::initBuffer
void initBuffer(const uInt size)
Internal helper functions for the automatic definition of histogram parameters, using the contents of...
casacore::getBinWidth
Fallible< T > getBinWidth() const
All bins have the same width.
casacore::reset
void reset()
Reset the contents of the bins to zero, but retain the current bin definition.
casacore::copy
void copy(double *target, int npixels) const
casacore::getMedian
Fallible< T > getMedian()
casacore::Float
float Float
Definition aipstype.h:52
casacore::itsStatAcc
StatAcc< T > itsStatAcc
Definition HistAcc.h:183
casacore::init
void init()
Other internal helper function(s).
casacore::operator=
Record & operator=(const Record &other)
Copy the data in the other record to this record.
casacore::getHistogram
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.
casacore::itsBinContents
Block< uInt > itsBinContents
Definition HistAcc.h:179
casacore::getBinValue
Fallible< T > getBinValue(const uInt index) const
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::size
uInt size() const
Definition RecordInterface.h:224
casacore::itsBuffer
Block< T > itsBuffer
Definition HistAcc.h:186
casacore::itsUserDefinedBinWidth
T itsUserDefinedBinWidth
Definition HistAcc.h:181
casacore::put
void put(const T v)
Accumulate (put) value(s) into the histogram.
casacore::getPercentile
Fallible< T > getPercentile(const Float p)
Empty all bins whose contents is < nmin (e.g.
casacore::itsAutoDefineMode
Bool itsAutoDefineMode
Definition HistAcc.h:185
casacore::getStatistics
const StatAcc< T > & getStatistics()
Get the internal Statistics accumulator (see StatAcc,h).