# source:trunk/yat/statistics/Averager.h@703

Last change on this file since 703 was 703, checked in by Jari Häkkinen, 16 years ago

• Property svn:eol-style set to native
• Property svn:keywords set to Author Date Id Revision
File size: 5.0 KB
Line
1#ifndef _theplu_yat_statistics_averager_
2#define _theplu_yat_statistics_averager_
3
4// $Id: Averager.h 703 2006-12-18 00:47:44Z jari$
5
6/*
7  Copyright (C) The authors contributing to this file.
8
9  This file is part of the yat library, http://lev.thep.lu.se/trac/yat
10
11  The yat library is free software; you can redistribute it and/or
12  modify it under the terms of the GNU General Public License as
13  published by the Free Software Foundation; either version 2 of the
15
16  The yat library is distributed in the hope that it will be useful,
17  but WITHOUT ANY WARRANTY; without even the implied warranty of
18  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19  General Public License for more details.
20
21  You should have received a copy of the GNU General Public License
22  along with this program; if not, write to the Free Software
23  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
24  02111-1307, USA.
25*/
26
27#include <cmath>
28#include <sys/types.h>
29
30namespace theplu{
31namespace yat{
32namespace statistics{
33
34  class ostream;
35
36  ///
37  /// Class to calculate simple (first and second moments) averages.
38  ///
39  /// @see AveragerWeighted AveragerPair AveragerPairWeighted
40  ///
41  class Averager
42  {
43  public:
44
45    ///
46    /// Default constructor
47    ///
48    Averager(void);
49
50    ///
51    /// Constructor taking sum of \a x, sum of squared x, \a xx, and
52    /// number of samples \a n.
53    ///
54    Averager(double x, double xx, u_long n);
55
56    ///
57    /// Copy constructor
58    ///
59    Averager(const Averager& a);
60
61    ///
62    /// Adding \a n (default=1) number of data point(s) with value \a d.
63    ///
64    void add(double d, u_long n=1);
65
66    ///
67    /// Adding each value in an array \a v \a n (default=1)
68    /// number of times. The requirements for the type T of the
69    /// array \a v are: operator[] returning an element and function
70    /// size() returning the number of elements.
71    ///
72    ///
73    template <typename T>
74    void  add_values(const T& v, u_long n=1);
75
76    /**
77       @brief Coeffient of variation
78
79       Coeffient of variation (cv) is defined as ratio between the
80       standard deviation and the mean: \f$\frac{\sigma}{\mu} \f$.
81
82       @return standard deviation divided by mean.
83    */
84    inline double cv(void) const { return x_ ? std()/mean() : 0; }
85
86    ///
87    /// @return Mean of presented data, \f$\frac{1}{n}\sum x_i \f$
88    ///
89    inline double mean(void) const { return n_ ? x_/n_ : 0; }
90
91    ///
92    /// @return Number of data points
93    ///
94    inline u_long n(void) const { return n_; }
95
96    ///
97    /// @brief Rescales the object
98    ///
99    /// \f$\forall x_i \rightarrow a*x_i \f$,
100    /// \f$\forall x_i^2 \rightarrow a^2*x_i^2 \f$
101    ///
102    inline void rescale(double a);
103
104    ///
105    /// @return Standard error, i.e. standard deviation of the mean
106    /// \f$\sqrt{variance()/n} \f$
107    ///
108    inline double standard_error(void) const { return sqrt(variance()/n_); }
109
110    ///
111    /// @brief The standard deviation is defined as the square root of
112    /// the variance.
113    ///
114    /// @return The standard deviation, root of the variance().
115    ///
116    inline double std(void) const { return sqrt(variance()); }
117
118    ///
119    /// @brief The standard deviation is defined as the square root of
120    /// the variance.
121    ///
122    /// @return Standard deviation around \a m, root of the variance(m).
123    ///
124    inline double std(double m) const { return sqrt(variance(m)); }
125
126    ///
127    /// @return The sum of x
128    ///
129    inline double sum_x(void) const { return x_; }
130
131    ///
132    /// @return The sum of squares
133    ///
134    inline double sum_xx(void) const { return xx_; }
135
136    ///
137    /// @return \f$\sum_i (x_i-m)^2 \f$
138    ///
139    inline double sum_xx_centered(void) const { return xx_-x_*x_/n_; }
140
141    ///
142    /// @brief The variance with know mean
143    ///
144    /// The variance is calculated as
145    /// \f$\frac{1}{n}\sum (x_i-m)^2 \f$.
146    ///
147    /// @return Variance when the mean is known to be \a m.
148    ///
149    inline double variance(double m) const
150    { return n_ ? (xx_ - 2*m*x_ + m*m*n()) /n_ : 0; }
151
152    ///
153    /// @brief The estimated variance
154    ///
155    /// The variance is calculated as \f$\frac{1}{N}\sum_i 156 /// (x_i-m)^2 \f$, where \f$m \f$ is the mean.
157    ///
158    /// @return Estimation of variance
159    ///
160    inline double variance(void) const
161    { return n_>1 ? sum_xx_centered()/n_ : 0; }
162
163    ///
164    /// The variance is calculated using the \f$(n-1) \f$ correction,
165    /// which means it is the best unbiased estimator of the variance
166    /// \f$\frac{1}{N-1}\sum_i (x_i-m)^2 \f$, where \f$m \f$ is the
167    /// mean.
168    ///
169    /// @return unbiased estimation of variance
170    ///
171    inline double variance_unbiased(void) const
172    { return (n_>1) ? sum_xx_centered()/(n_-1) : 0; }
173
174    ///
175    /// @brief Reset everything to zero
176    ///
177    void reset(void);
178
179    ///
180    /// @brief The assignment operator
181    ///
182    const Averager& operator=(const Averager&);
183
184    ///
185    /// Operator to add another Averager
186    ///
187    const Averager& operator+=(const Averager&);
188
189  private:
190    u_long  n_;
191    double  x_, xx_;
192  };
193
194  // Template implementations
195  template <typename T>
196  void  Averager::add_values(const T& v, u_long n)
197  {
198    for (size_t i=0; i<v.size(); i++)