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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40// forward declarations:
41template <class T> class Block;
42class 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
125template<class T> class StatAcc {
126public:
127 // constructors and destructor.
128 // <group>
130 StatAcc(const 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
184private:
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
204template<class T>
205inline void StatAcc<T>::put(const T v) {
206 put1(v, 1); // default weight = 1
207}
208
209template<class T>
210inline 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)
Fallible< Double > getRms() const
StatAcc()
constructors and destructor.
void copy(const StatAcc &)
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 > getMin() const
StatAcc & operator+=(const StatAcc &)
Fallible< Double > getMean() const
Double itsWssum
Definition: StatAcc.h:187
void put(const Array< T > &v)
void printSummaryLineHeader(std::ostream &, const String &caption) const
void put(const Block< T > &v)
void printSummaryList(std::ostream &, const String &caption) const
Print summary of accumulated statistics.
Fallible< Double > getVariance() const
StatAcc operator+(const StatAcc &)
StatAcc(const StatAcc &)
void put1(const T, const Float)
Accumulate a single weighted value.
Fallible< Double > getMax() const
void printSummaryLine(std::ostream &, const String &caption) const
Fallible< Double > getRmsAbs() const
Double itsWsum
Definition: StatAcc.h:186
StatAcc & operator=(const StatAcc &)
Operators for adding and copying accumulators.
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