casacore
HistAcc.h
Go to the documentation of this file.
1//# HistAcc.h: Histogram Accumulator
2//# Copyright (C) 1996,1999,2000,2001
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//#
27//# $Id$
28
29#ifndef SCIMATH_HISTACC_H
30#define SCIMATH_HISTACC_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Utilities/Fallible.h>
34#include <casacore/scimath/Mathematics/StatAcc.h>
35#include <casacore/casa/Containers/Block.h>
36#include <casacore/casa/iosfwd.h>
37#include <casacore/casa/Arrays/ArrayFwd.h>
38
39namespace casacore { //# NAMESPACE CASACORE - BEGIN
40
41// forward declarations:
42class String;
43
44// <reviewed reviewer="" date="" tests="tHistAcc" demos="">
45
46// <prerequisite>
47// <li> module Arrays
48// <li> <linkto module="Arrays:description">Arrays </linkto> module
49// </prerequisite>
50//
51// <summary>
52// Makes a histogram from input values.
53// </summary>
54//
55// <etymology>
56// HistAcc stands for `Histogram Accumulator'.
57// </etymology>
58//
59// <templating arg=T>
60// <li> The accepted input types are real, i.e. Int, uInt, Float, Double,
61// but not Complex.
62// </templating>
63
64// <synopsis>
65// Makes a histogram from input values. The histogram bin parameters
66// may be defined, or determined from the first n input values.
67// The input values are fed to HistAcc via the member function `put'.
68// They can be fed individually, or in the form of an Array.
69//
70// The histogram `bins' can be defined via the constructor in the
71// form of loop variables: low bin, high bin, bin-width.
72// It is also possible to let the bin parameters be determined
73// automatically from the first n (e.g. n=50) input values.
74// If the actual nr of input values is less than n when the histogram
75// is interrogated in some way, the bin parameters will be determined
76// from what is available.
77// </synopsis>
78//
79// <example>
80// It is usually convenient to let the bins be defined automatically:
81// <srcblock>
82// Matrix<T> vv(30,100); // an array of input values
83// vv = ... // fill the array
84// HistAcc<T> h(25); // use the first 25 values to define bins
85// h.put(vv); // accumulate values into histogram
86// h.printHistogram(cout,"vv"); // print the histogram of vv
87// Fallible<Double> median = h1.getMedian(); // return the median
88// </srcblock>
89//
90// In some cases the bin parameters are pre-defined:
91// <srcblock>
92// Vector<T> vv(100,0); // a vector (array) of values
93// vv = ... // fill the vector
94// HistAcc<T> h(-10,20,3); // bins with width 3, between -10 and 20
95// h.put(vv); // accumulate values into histogram
96// uInt n = h.getSpurious(l,h);// get the number outside the bins
97// </srcblock>
98//
99// The internal statistics accumulator can be interrogated explicitly
100// or implicitly:
101// <srcblock>
102// StatAcc<T> s = h.getStatistics(); // return the internal StatAcc
103// Fallible<Double> mean = s.getMean(); // get the mean of the input values
104// Fallible<Double> mean = h.getStatistics().getMean(); // alternative
105// </srcblock>
106
107// </example>
108//
109// <motivation>
110// </motivation>
111//
112// <todo asof="">
113// </todo>
114
115
116// ***************************************************************************
117
118template<class T> class HistAcc {
119public:
120 // Constructors and destructor. If the bin-parameters low, high
121 // and width (for lowest and highest bin, and binwidth) are not
122 // specified, they will be determined automatically from the
123 // first nBuff input values (which are stored in a temporary buffer).
124 // <group>
125 HistAcc(const uInt nBuff); //# fully automatic
126 HistAcc(const uInt nBuff, const T width); //# semi-automatic
127 HistAcc(const T low, const T high, const T width); //# fully specified
128 HistAcc(const HistAcc&); //# copy an existing one
130 // </group>
131
132 // Copy operations.
133 // <group>
134 void copy(const HistAcc&); //# idem
136 // </group>
137
138 // Accumulate (put) value(s) into the histogram.
139 // <group>
140 inline void put(const T v); //# single value
141 void put(const Array<T>& vv); //# array
142 void put(const Block<T>& vv); //# block (simple array)
143 // </group>
144
145 // Reset the contents of the bins to zero, but retain the current
146 // bin definition.
147 void reset();
148
149 // Empty all bins whose contents is < nmin (e.g. nmin=2).
150 // This is useful to remove `noise' values from the histogram.
151 void emptyBinsWithLessThan(const uInt nmin);
152
153 // The median is the 50-percentile (getPercentile(50)), i.e. the
154 // value which has 50 percent of the input values below it.
155 // Calculation takes into account the spurious
156 // input values, i.e. values that fell outside the bins.
159
160 // All bins have the same width.
162
163 // Get the internal Statistics accumulator (see StatAcc,h).
164 // It can be used to obtain statistics of the input values.
166
167 // The return value is the nr of histogram bins, and is invalid
168 // if the number is zero. The given blocks/vectors are resized,
169 // and contain the contents and centre values of the bins.
171
172 // Get the nr of `spurious' values, i.e. the ones that fell
173 // outside the defined bins.
174 uInt getSpurious(uInt& tooSmall, uInt& tooLarge);
175
176 // Print histogram.
177 // <group>
178 void printHistogram(ostream&, const String& caption);
179 // </group>
180
181private:
182 Block<uInt> itsBinContents; //# Contents of histogram bins
183 Block<T> itsBinHighLimit; //# High limit of each bin
184 T itsUserDefinedBinWidth; //# if defined
185
186 StatAcc<T> itsStatAcc; //# private Statistics Accumulator
187
188 Bool itsAutoDefineMode; //# If true: automatic mode
189 Block<T> itsBuffer; //# temporary storage of input T-values
190 uInt itsBufferContents; //# nr of T-values in buffer
191
192 // Accumulate a single value into the histogram.
193 void put1(const T);
194
195 // Definition of histogram bins with given parameters.
196 void defineBins(const T low, const T high, const T width);
197
198 // Internal helper functions for the automatic definition of
199 // histogram parameters, using the contents of itsBuffer.
200 // <group>
201 void initBuffer(const uInt size);
202 void putBuffer(const T v); //# add input value to itsBuffer
203 void clearBuffer(); //# transfer from buffer to bins
205 // </group>
206
207 // Other internal helper function(s).
208 // <group>
209 void init();
210 Fallible<T> getBinValue(const uInt index) const; //# bin centre value
211 // </group>
212
213};
214
215
216
217//*************************** inline functions, have to be in HistAcc.h ****
218
219
220// Accumulate a single value:
221
222template<class T>
223inline void HistAcc<T>::put(const T v) {
224 put1(v);
225}
226
227
228} //# NAMESPACE CASACORE - END
229
230#ifndef CASACORE_NO_AUTO_TEMPLATES
231#include <casacore/scimath/Mathematics/HistAcc.tcc>
232#endif //# CASACORE_NO_AUTO_TEMPLATES
233#endif
234
235
236
237
238
239
240
241
242
243
244
245
simple 1-D array
Definition: Block.h:200
Mark a value as valid or invalid.
Definition: Fallible.h:123
Makes a histogram from input values.
Definition: HistAcc.h:118
void put(const T v)
Accumulate (put) value(s) into the histogram.
Definition: HistAcc.h:223
const StatAcc< T > & getStatistics()
Get the internal Statistics accumulator (see StatAcc,h).
void put1(const T)
Accumulate a single value into the histogram.
HistAcc(const uInt nBuff)
Constructors and destructor.
void emptyBinsWithLessThan(const uInt nmin)
Empty all bins whose contents is < nmin (e.g.
Block< T > itsBinHighLimit
Definition: HistAcc.h:183
Fallible< T > getMedian()
void copy(const HistAcc &)
Copy operations.
void defineBins(const T low, const T high, const T width)
Definition of histogram bins with given parameters.
StatAcc< T > itsStatAcc
Definition: HistAcc.h:186
Bool itsAutoDefineMode
Definition: HistAcc.h:188
Fallible< T > getPercentile(const Float p)
The median is the 50-percentile (getPercentile(50)), i.e.
Block< T > itsBuffer
Definition: HistAcc.h:189
T itsUserDefinedBinWidth
Definition: HistAcc.h:184
void put(const Array< T > &vv)
void printHistogram(ostream &, const String &caption)
Print histogram.
void putBuffer(const T v)
uInt itsBufferContents
Definition: HistAcc.h:190
Block< uInt > itsBinContents
Definition: HistAcc.h:182
HistAcc(const uInt nBuff, const T width)
void reset()
Reset the contents of the bins to zero, but retain the current bin definition.
uInt getSpurious(uInt &tooSmall, uInt &tooLarge)
Get the nr of ‘spurious’ values, i.e.
void put(const Block< T > &vv)
HistAcc(const T low, const T high, const T width)
void initBuffer(const uInt size)
Internal helper functions for the automatic definition of histogram parameters, using the contents of...
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.
HistAcc(const HistAcc &)
void init()
Other internal helper function(s).
Fallible< T > getBinValue(const uInt index) const
Fallible< T > getBinWidth() const
All bins have the same width.
HistAcc & operator=(const HistAcc &)
A statistics accumulator
Definition: StatAcc.h:125
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
float Float
Definition: aipstype.h:54
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42