casacore
StatAcc.h
Go to the documentation of this file.
1 //# StatAcc.h: Statistics 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_STATACC_H
30 #define SCIMATH_STATACC_H
31 
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/BasicMath/Math.h>
34 #include <casacore/casa/Utilities/Fallible.h>
35 #include <casacore/casa/iosfwd.h>
36 #include <casacore/casa/Arrays/ArrayFwd.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 // forward declarations:
41 template <class T> class Block;
42 class String;
43 
44 // <reviewed reviewer="" date="" tests="tStatAcc" demos="">
45 
46 // <prerequisite>
47 // <li> module Arrays
48 // <li> <linkto module="Arrays:description">Arrays </linkto> module
49 // </prerequisite>
50 //
51 // <summary>
52 // A statistics accumulator
53 // </summary>
54 //
55 // <etymology>
56 // StatAcc stands for `Statistics Accumulator'.
57 // </etymology>
58 //
59 // <templating arg=T>
60 // <li> A statistics accumulator accepts (weighted) input values and
61 // calculates simple statistice (min, max, weighted mean, rms etc).
62 // The accepted input types are real, i.e. Int, uInt, Float, Double,
63 // but not Complex. The reason for this is that the < operator of
64 // Complex (needed for min/max) works on the norm in any case, and
65 // the sqrt function (needed for rms) yields an ambiguous result.
66 //
67 // Restriction to real types also allows the internal arithmetic type
68 // to be Double rather than the input type. The latter would give
69 // all kinds of complications with weighting, accuracy and overflow
70 // if the input type would be Int or uInt.
71 // </templating>
72 
73 // <synopsis>
74 // The (weighted) values are fed to StatAcc via the member function
75 // `put'. They can be fed individually, or in the form of an
76 // Array. The weights are optional (default = 1) and always have
77 // type Float.
78 //
79 // Asking for a result does not change the internal state. The
80 // type of the returned results is always Fallible<Double>.
81 // A result is invalid if no input values with non-zero weight
82 // have been accumulated yet.
83 //
84 // The accumulator
85 // can be re-initialised with the function `reset'. Accumulators
86 // can be added to each other, which is as if their combined values had been
87 // accumulated in the same accumulator.
88 //
89 // Some functions have been provided to display a summary of the
90 // statistics results. One may choose between a one-line format
91 // (with an optional associated header line), and a list.
92 // </synopsis>
93 //
94 // <example>
95 // <srcblock>
96 // StatAcc<T> s; // T is Float, Double, Int etc
97 // Matrix<T> vv(2,5); // a matrix (array) of input values
98 // Matrix<Float> wgt(2,5); // an associated matrix of weights
99 // .... fill vv and wgt with values and individual weights ...
100 // s.put(vv,wgt); // accumulate the weighted values
101 // Fallible<Double> min = s.getMin(); // return the minimum value
102 //
103 // s.reset(); // re-initialise
104 // s.put(vv); // if wgt omitted, default = 1.0
105 // if (s.getRms().isValid() { // check validity of rms
106 // ... use it ...
107 // }
108 // </srcblock>
109 // </example>
110 //
111 // <motivation>
112 // One often needs simple statistics of a series of values, which
113 // may occur by themselves or in arrays at various points in a program.
114 // Sincs it is a pain to have to assign accumulation variables, and to
115 // write statistics evaluation code (including exceptions),
116 // this helper class is provided.
117 // </motivation>
118 //
119 // <todo asof="">
120 // </todo>
121 
122 
123 // ***************************************************************************
124 
125 template<class T> class StatAcc {
126 public:
127  // constructors and destructor.
128  // <group>
130  StatAcc(const StatAcc&);
131  ~StatAcc(){;}
132  // </group>
133 
134  // Reset or copy the accumulator attributes.
135  // <group>
136  void reset();
137  void copy(const StatAcc&);
138  // </group>
139 
140  // Operators for adding and copying accumulators.
141  // <group>
145  // </group>
146 
147  // Accumulate input value(s) v with weight w.
148  // If weight is omitted, the default=1.
149  // <group>
150  inline void put(const T v);
151  inline void put(const T v, const Float w);
152  void put(const Array<T>& v);
153  void put(const Array<T>& v, const Array<Float>& w);
154  void put(const Block<T>& v);
155  void put(const Block<T>& v, const Block<Float>& w);
156  // </group>
157 
158  // Get statistics results one at a time.
159  // Count is the nr of values accumulated.
160  // Wtot is the sum of the weights.
161  // Rms is defined w.r.t. the mean, and is the square of Variance.
162  // RmsAbs is the root-mean-square of the absolute input values.
163  // <group>
164  Double getWtot() const;
165  uInt getCount() const;
172  // </group>
173 
174  // Print summary of accumulated statistics.
175  // Line is a one-line summary, including the (short) caption.
176  // LineHeader gives a one-line explanation of the numbers.
177  // List uses a separate line for each result (mean, max etc).
178  // <group>
179  void printSummaryList(std::ostream&, const String& caption) const;
180  void printSummaryLine(std::ostream&, const String& caption) const;
181  void printSummaryLineHeader(std::ostream&, const String& caption) const;
182  // </group>
183 
184 private:
185  Double itsWtot; //# Sum of weights
186  Double itsWsum; //# Sum of weighted values
187  Double itsWssum; //# Sum of weighted squares
188  Double itsMin; //# Minimum value
189  Double itsMax; //# Maximum value
190  uInt itsCount; //# Number of samples
191 
192  // Accumulate a single weighted value.
193  void put1(const T, const Float);
194 
195 };
196 
197 
198 
199 //*************************** inline functions, have to be in StatAcc.h ****
200 
201 
202 // Accumulate a single value:
203 
204 template<class T>
205 inline void StatAcc<T>::put(const T v) {
206  put1(v, 1); // default weight = 1
207 }
208 
209 template<class T>
210 inline void StatAcc<T>::put(const T v, const Float w) {
211  put1(v, w);
212 }
213 
214 
215 
216 } //# NAMESPACE CASACORE - END
217 
218 #ifndef CASACORE_NO_AUTO_TEMPLATES
219 #include <casacore/scimath/Mathematics/StatAcc.tcc>
220 #endif //# CASACORE_NO_AUTO_TEMPLATES
221 #endif
222 
223 
224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
simple 1-D array
Definition: Block.h:200
Mark a value as valid or invalid.
Definition: Fallible.h:123
A statistics accumulator
Definition: StatAcc.h:125
void reset()
Reset or copy the accumulator attributes.
Double getWtot() const
Get statistics results one at a time.
void put(const Block< T > &v, const Block< Float > &w)
StatAcc & operator=(const StatAcc &)
Operators for adding and copying accumulators.
StatAcc()
constructors and destructor.
void copy(const StatAcc &)
Fallible< Double > getRms() const
Double itsWtot
Definition: StatAcc.h:185
void put(const T v)
Accumulate input value(s) v with weight w.
Definition: StatAcc.h:205
void put(const Array< T > &v, const Array< Float > &w)
uInt getCount() const
Fallible< Double > getVariance() const
Fallible< Double > getMean() const
Double itsWssum
Definition: StatAcc.h:187
void put(const Array< T > &v)
void printSummaryLineHeader(std::ostream &, const String &caption) const
Fallible< Double > getMax() const
void put(const Block< T > &v)
void printSummaryList(std::ostream &, const String &caption) const
Print summary of accumulated statistics.
StatAcc operator+(const StatAcc &)
StatAcc(const StatAcc &)
Fallible< Double > getMin() const
void put1(const T, const Float)
Accumulate a single weighted value.
void printSummaryLine(std::ostream &, const String &caption) const
Fallible< Double > getRmsAbs() const
StatAcc & operator+=(const StatAcc &)
Double itsWsum
Definition: StatAcc.h:186
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
double Double
Definition: aipstype.h:55