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

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

refs #512. added relates tag in namespace statistics.

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