StatAcc.h

Go to the documentation of this file.
00001 //# StatAcc.h: Statistics Accumulator
00002 //# Copyright (C) 1996,1999,2000,2001
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //#
00027 //# $Id$
00028 
00029 #ifndef SCIMATH_STATACC_H
00030 #define SCIMATH_STATACC_H
00031 
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/casa/BasicMath/Math.h>
00034 #include <casacore/casa/Utilities/Fallible.h>
00035 #include <casacore/casa/iosfwd.h>
00036 
00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00038 
00039 // forward declarations:
00040 template <class T> class Array;
00041 template <class T> class Block;
00042 class String;
00043 
00044 // <reviewed reviewer="" date="" tests="tStatAcc" demos="">
00045 
00046 // <prerequisite>
00047 //   <li> module Arrays
00048 //   <li> <linkto module="Arrays:description">Arrays </linkto> module
00049 // </prerequisite>
00050 //
00051 // <summary> 
00052 // A statistics accumulator 
00053 // </summary>
00054 //
00055 // <etymology>
00056 // StatAcc stands for `Statistics Accumulator'. 
00057 // </etymology>
00058 //
00059 // <templating arg=T>
00060 // <li> A statistics accumulator accepts (weighted) input values and 
00061 // calculates simple statistice (min, max, weighted mean, rms etc).
00062 // The accepted input types are real, i.e. Int, uInt, Float, Double, 
00063 // but not Complex. The reason for this is that the < operator of
00064 // Complex (needed for min/max) works on the norm in any case, and
00065 // the sqrt function (needed for rms) yields an ambiguous result.
00066 //   
00067 // Restriction to real types also allows the internal arithmetic type 
00068 // to be Double rather than the input type. The latter would give
00069 // all kinds of complications with weighting, accuracy and overflow
00070 // if the input type would be Int or uInt.
00071 // </templating>
00072 
00073 // <synopsis>
00074 // The (weighted) values are fed to StatAcc via the member function
00075 // `put'. They can be fed individually, or in the form of an
00076 // Array. The weights are optional (default = 1) and always have 
00077 // type Float.
00078 //
00079 // Asking for a result does not change the internal state. The 
00080 // type of the returned results is always Fallible<Double>.
00081 // A result is invalid if no input values with non-zero weight
00082 // have been accumulated yet.
00083 //
00084 // The accumulator
00085 // can be re-initialised with the function `reset'. Accumulators
00086 // can be added to each other, which is as if their combined values had been
00087 // accumulated in the same accumulator.
00088 // 
00089 // Some functions have been provided to display a summary of the
00090 // statistics results. One may choose between a one-line format
00091 // (with an optional associated header line), and a list.
00092 // </synopsis> 
00093 //
00094 // <example>
00095 // <srcblock>
00096 //   StatAcc<T> s;               // T is Float, Double, Int etc
00097 //   Matrix<T> vv(2,5);          // a matrix (array) of input values
00098 //   Matrix<Float> wgt(2,5);     // an associated matrix of weights
00099 //   .... fill vv and wgt with values and individual weights ... 
00100 //   s.put(vv,wgt);              // accumulate the weighted values   
00101 //   Fallible<Double> min = s.getMin();    // return the minimum value
00102 //
00103 //   s.reset();                  // re-initialise
00104 //   s.put(vv);                  // if wgt omitted, default = 1.0
00105 //   if (s.getRms().isValid() {  // check validity of rms
00106 //         ... use it ...
00107 //   }
00108 // </srcblock>
00109 // </example>
00110 //
00111 // <motivation>
00112 // One often needs simple statistics of a series of values, which 
00113 // may occur by themselves or in arrays at various points in a program.  
00114 // Sincs it is a pain to have to assign accumulation variables, and to
00115 // write statistics evaluation code (including exceptions),
00116 // this helper class is provided.
00117 // </motivation>
00118 //
00119 // <todo asof="">
00120 // </todo>
00121 
00122 
00123 // *************************************************************************** 
00124 
00125 template<class T> class StatAcc  {
00126 public:
00127     // constructors and destructor.
00128     // <group>
00129     StatAcc();  
00130     StatAcc(const StatAcc&);  
00131     ~StatAcc(){;} 
00132     // </group>
00133 
00134     // Reset or copy the accumulator attributes.
00135     // <group>
00136     void reset();
00137     void copy(const StatAcc&);
00138     // </group>
00139 
00140     // Operators for adding and copying accumulators.
00141     // <group>
00142     StatAcc& operator= (const StatAcc&);
00143     StatAcc operator+ (const StatAcc&);
00144     StatAcc& operator+= (const StatAcc&);        
00145     // </group>
00146 
00147     // Accumulate input value(s) v with weight w.
00148     // If weight is omitted, the default=1.
00149     // <group>
00150     inline void put(const T v);           
00151     inline void put(const T v, const Float w);
00152     void put(const Array<T>& v);      
00153     void put(const Array<T>& v, const Array<Float>& w);
00154     void put(const Block<T>& v);      
00155     void put(const Block<T>& v, const Block<Float>& w);
00156     // </group>
00157 
00158     // Get statistics results one at a time.
00159     // Count is the nr of values accumulated.
00160     // Wtot is the sum of the weights. 
00161     // Rms is defined w.r.t. the mean, and is the square of Variance. 
00162     // RmsAbs is the root-mean-square of the absolute input values.
00163     // <group>
00164     Double getWtot() const;           
00165     uInt             getCount() const;
00166     Fallible<Double> getMin() const;        
00167     Fallible<Double> getMax() const;      
00168     Fallible<Double> getMean() const;        
00169     Fallible<Double> getRms() const;      
00170     Fallible<Double> getVariance() const;      
00171     Fallible<Double> getRmsAbs() const; 
00172     // </group>
00173 
00174     // Print summary of accumulated statistics.
00175     // Line is a one-line summary, including the (short) caption.
00176     // LineHeader gives a one-line explanation of the numbers.
00177     // List uses a separate line for each result (mean, max etc).
00178     // <group>
00179     void printSummaryList(std::ostream&, const String& caption) const; 
00180     void printSummaryLine(std::ostream&, const String& caption) const;  
00181     void printSummaryLineHeader(std::ostream&, const String& caption) const; 
00182     // </group>
00183         
00184 private:
00185     Double itsWtot;               //# Sum of weights
00186     Double itsWsum;               //# Sum of weighted values
00187     Double itsWssum;              //# Sum of weighted squares
00188     Double itsMin;                //# Minimum value
00189     Double itsMax;                //# Maximum value       
00190     uInt   itsCount;              //# Number of samples
00191 
00192     // Accumulate a single weighted value.
00193     void put1(const T, const Float);
00194 
00195 };
00196 
00197 
00198 
00199 //*************************** inline functions, have to be in StatAcc.h ****
00200 
00201 
00202 // Accumulate a single value:
00203 
00204 template<class T> 
00205 inline void StatAcc<T>::put(const T v) {
00206     put1(v, 1);                                        // default weight = 1
00207 }
00208 
00209 template<class T> 
00210 inline void StatAcc<T>::put(const T v, const Float w) {
00211     put1(v, w);
00212 }    
00213 
00214 
00215 
00216 } //# NAMESPACE CASACORE - END
00217 
00218 #ifndef CASACORE_NO_AUTO_TEMPLATES
00219 #include <casacore/scimath/Mathematics/StatAcc.tcc>
00220 #endif //# CASACORE_NO_AUTO_TEMPLATES
00221 #endif
00222 
00223 
00224 
00225 
00226 
00227 
00228 
00229 
00230 
00231 
00232 
00233 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1