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

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

updating copyright years

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.3 KB
Line 
1#ifndef _theplu_yat_statistics_histogram_
2#define _theplu_yat_statistics_histogram_
3
4// $Id: Histogram.h 1888 2009-03-31 19:13:10Z 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  private:
183    // Returns zero if outside boundaries
184    size_t bin(double d);
185
186    std::vector<double> histogram_;
187    double xmax_;
188    double xmin_;
189    statistics::AveragerWeighted sum_all_;      // average of all data
190    statistics::AveragerWeighted sum_histogram_;// average of data in histogram
191  };
192
193  /**
194     Add a range [first, last) of values to Histogram.
195
196     \relates Histogram
197   */
198  template<typename ForwardIterator>
199  void add(Histogram& h, 
200           ForwardIterator first, ForwardIterator last)
201  {
202    while (first!=last) {
203      h.add(utility::iterator_traits<ForwardIterator>().data(),
204            utility::iterator_traits<ForwardIterator>().weight());
205      ++first;
206    }
207  }
208
209  /**
210     The Histogram output operator
211     
212     \relates Histogram
213  */
214  std::ostream& operator<<(std::ostream& s,const Histogram&);
215
216}}} // of namespace statistics, yat, and theplu
217
218#endif
Note: See TracBrowser for help on using the repository browser.