source: trunk/yat/statistics/Averager.h @ 1122

Last change on this file since 1122 was 1122, checked in by Peter, 14 years ago

refs #335 - Changed so Averager classes are consistently returning NaN when Averager is empty or for some other reason the estimation ends up with things like zero by zero division. Previously zero was returned from some functions and Nan from some functions. I did not change anythuing in NCC.

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