source: trunk/yat/statistics/Histogram.h @ 2032

Last change on this file since 2032 was 2032, checked in by Peter, 12 years ago

fixes #555

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.5 KB
Line 
1#ifndef _theplu_yat_statistics_histogram_
2#define _theplu_yat_statistics_histogram_
3
4// $Id: Histogram.h 2032 2009-08-19 21:41:30Z peter $
5
6/*
7  Copyright (C) 2004 Jari Häkkinen
8  Copyright (C) 2005 Jari Häkkinen, Peter Johansson
9  Copyright (C) 2006 Jari Häkkinen
10  Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
11  Copyright (C) 2009 Peter Johansson
12
13  This file is part of the yat library, http://dev.thep.lu.se/yat
14
15  The yat library is free software; you can redistribute it and/or
16  modify it under the terms of the GNU General Public License as
17  published by the Free Software Foundation; either version 3 of the
18  License, or (at your option) any later version.
19
20  The yat library is distributed in the hope that it will be useful,
21  but WITHOUT ANY WARRANTY; without even the implied warranty of
22  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23  General Public License for more details.
24
25  You should have received a copy of the GNU General Public License
26  along with yat. If not, see <http://www.gnu.org/licenses/>.
27*/
28
29#include "AveragerWeighted.h"
30#include "yat/utility/iterator_traits.h"
31
32#include <string>
33#include <vector>
34
35namespace theplu {
36namespace yat {
37namespace statistics {
38
39  ///
40  /// @brief Histograms provide a convenient way of presenting the
41  /// distribution of a set of data.
42  ///
43  /// A histogram consists of a set of
44  /// bins which count the number of events falling into these
45  /// bins. Currently only one dimensional histograms with uniformly
46  /// spaced bins are supported.
47  ///
48  class Histogram
49  {
50  public:
51
52    ///
53    /// The default constructor.
54    ///
55    Histogram(void);
56
57    ///
58    /// The copy constructor.
59    ///
60    Histogram(const Histogram&);
61
62    ///
63    /// Construct a histogram object that covers \f$(xmin,xmax]\f$
64    /// with the bin spacing \f$(xmax-xmin)/n\f$.
65    ///
66    Histogram(const double xmin, const double xmax, const size_t n);
67
68    virtual ~Histogram(void);
69
70    ///
71    /// Update the histogram by adding \a weight to the bin whose
72    /// range contains the observation \a x. No bins are updated when
73    /// \a x lies outside the range of the histogram but the value is
74    /// added to the overall integral of the histogram.
75    ///
76    /// @short Add a data point to the histogram.
77    ///
78    /// @return 0 if \a x lies within the range of the histogram, -1
79    /// if \a x is smaller than the lower limit of the histogram, and
80    /// similarly, 1 is returned if \a x is greater than or equal to
81    /// the upper limit.
82    ///
83    int add(const double x,const double weight=1.0);
84
85    ///
86    /// Gives access to the AveragerWeighted object that keeps track of
87    /// average of all events presented to the histogram.
88    ///
89    /// @short Average of all events presented to the histogram.
90    ///
91    /// @return A const reference to an AveragerWeighted object.
92    ///
93    const AveragerWeighted& averager_all(void) const;
94
95    ///
96    /// Gives access to the AveragerWeighted object that keeps track of
97    /// average of events that fits within the histogram lower and
98    /// upper limits. This function is equivalent to averager().
99    ///
100    /// @short Average of events fitting within histogram.
101    ///
102    /// @return A const reference to an AveragerWeighted object.
103    ///
104    const AveragerWeighted& averager_histogram(void) const;
105
106    ///
107    /// @return The number of bins in the histogram
108    ///
109    size_t nof_bins(void) const;
110
111    ///
112    ///  There are two ways to normalize the counts.
113    ///
114    /// If choice is true: The normalized count is the count in a
115    /// bin divided by the total number of observations. In this
116    /// case the relative counts are normalized to sum to unity (
117    /// minus values outside histogram).  This is the intuitive case
118    /// where the height of the histogram bar represents the
119    /// proportion of the data in each class.
120    ///
121    /// If choice is false: The normalized count is the count in the
122    /// class divided by the number of observations times the bin
123    /// width. For this normalization, the area (or integral) under
124    /// the histogram is equal to unity (minus the missing area
125    /// corresponding to counts outside histogram). From a
126    /// probabilistic point of view, this normalization results in a
127    /// relative histogram that is most akin to the probability
128    /// density function If you want to overlay a probability density
129    /// on top of the histogram, use this normalization. Although this
130    /// normalization is less intuitive (relative frequencies greater
131    /// than 1 are quite permissible), it is the appropriate
132    /// normalization if you are using the histogram to model a
133    /// probability density function.
134    ///
135    /// @short Normalizing the histogram
136    ///
137    void normalize(bool choice = true);
138
139    ///
140    /// @return The value in the middle of bin \a k.
141    ///
142    /// @note No check is done that \a k is within the size of the
143    /// histogram.
144    ///
145    double observation_value(const size_t k) const;
146
147    ///
148    /// Set everyting to default values, here it means that everything
149    /// is set to zero except the boundary values that are kept.
150    ///
151    void reset(void);
152
153    ///
154    /// @return The width of the bins in the histogram.
155    ///
156    double spacing(void) const;
157
158    ///
159    /// @return The histogram upper boundary.
160    ///
161    /// @note The upper boundary value is outside the histogram.
162    ///
163    double xmax(void) const;
164
165    ///
166    /// @return The histogram lower boundary.
167    ///
168    /// @note The lower boundary value is inside the histogram.
169    ///
170    double xmin(void) const;
171
172    ///
173    /// @return The count of bin \a k in the histogram.
174    ///
175    double operator[](size_t k) const;
176
177    ///
178    /// The assignment operator
179    ///
180    const Histogram& operator=(const Histogram&);
181
182    /**
183       \brief Addition operator
184
185       \note The bins in lhs and rhs must match, i.e., min, max, and
186       nof_bins() must be equal in lhs and rhs.
187
188       \since New in yat 0.6
189    */
190    const Histogram& operator+=(const Histogram& rhs);
191
192  private:
193    // Returns zero if outside boundaries
194    size_t bin(double d);
195
196    std::vector<double> histogram_;
197    double xmax_;
198    double xmin_;
199    statistics::AveragerWeighted sum_all_;      // average of all data
200    statistics::AveragerWeighted sum_histogram_;// average of data in histogram
201  };
202
203  /**
204     Add a range [first, last) of values to Histogram.
205
206     \relates Histogram
207   */
208  template<typename ForwardIterator>
209  void add(Histogram& h, 
210           ForwardIterator first, ForwardIterator last)
211  {
212    while (first!=last) {
213      h.add(utility::iterator_traits<ForwardIterator>().data(),
214            utility::iterator_traits<ForwardIterator>().weight());
215      ++first;
216    }
217  }
218
219  /**
220     The Histogram output operator
221     
222     \relates Histogram
223  */
224  std::ostream& operator<<(std::ostream& s,const Histogram&);
225
226}}} // of namespace statistics, yat, and theplu
227
228#endif
Note: See TracBrowser for help on using the repository browser.