casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
36 #include <casacore/casa/iosfwd.h>
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 // forward declarations:
42 class 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 
118 template<class T> class HistAcc {
119 public:
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
129  ~HistAcc(){;}
130  // </group>
131 
132  // Copy operations.
133  // <group>
134  void copy(const HistAcc&); //# idem
135  HistAcc& operator= (const HistAcc&);
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.
157  Fallible<T> getPercentile(const Float p);
159 
160  // All bins have the same width.
161  Fallible<T> getBinWidth() const;
162 
163  // Get the internal Statistics accumulator (see StatAcc,h).
164  // It can be used to obtain statistics of the input values.
165  const StatAcc<T>& getStatistics();
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 
181 private:
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
204  void autoDefineBins();
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 
222 template<class T>
223 inline 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 
void put(const T v)
Accumulate (put) value(s) into the histogram.
Definition: HistAcc.h:223
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.
T itsUserDefinedBinWidth
Definition: HistAcc.h:184
Block< uInt > itsBinContents
Definition: HistAcc.h:182
uInt itsBufferContents
Definition: HistAcc.h:190
Fallible< T > getBinValue(const uInt index) const
Fallible< T > getBinWidth() const
All bins have the same width.
void copy(const HistAcc &)
Copy operations.
Bool itsAutoDefineMode
Definition: HistAcc.h:188
HistAcc(const uInt nBuff)
Constructors and destructor.
void printHistogram(ostream &, const String &caption)
Print histogram.
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&#39; values, i.e.
void emptyBinsWithLessThan(const uInt nmin)
Empty all bins whose contents is &lt; nmin (e.g.
Mark a value as valid or invalid.
Definition: Fallible.h:122
StatAcc< T > itsStatAcc
Definition: HistAcc.h:186
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
void put1(const T)
Accumulate a single value into the histogram.
void init()
Other internal helper function(s).
float Float
Definition: aipstype.h:54
void putBuffer(const T v)
simple 1-D array
Definition: Allocator.h:210
Makes a histogram from input values.
Definition: HistAcc.h:118
void defineBins(const T low, const T high, const T width)
Definition of histogram bins with given parameters.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Block< T > itsBuffer
Definition: HistAcc.h:189
Block< T > itsBinHighLimit
Definition: HistAcc.h:183
Fallible< T > getMedian()
HistAcc & operator=(const HistAcc &)
const StatAcc< T > & getStatistics()
Get the internal Statistics accumulator (see StatAcc,h).
Fallible< T > getPercentile(const Float p)
The median is the 50-percentile (getPercentile(50)), i.e.
void initBuffer(const uInt size)
Internal helper functions for the automatic definition of histogram parameters, using the contents of...
A statistics accumulator.
Definition: StatAcc.h:125
unsigned int uInt
Definition: aipstype.h:51