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

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

Addresses #436.

  • 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 1486 2008-09-09 21:17:19Z jari $
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 Jari Häkkinen, Peter Johansson
11  Copyright (C) 2008 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 this program; if not, write to the Free Software
27  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
28  02111-1307, USA.
29*/
30
31#include "AveragerWeighted.h"
32#include "yat/utility/iterator_traits.h"
33
34#include <string>
35#include <vector>
36
37namespace theplu {
38namespace yat {
39namespace statistics {
40
41  ///
42  /// @brief Histograms provide a convenient way of presenting the
43  /// distribution of a set of data.
44  ///
45  /// A histogram consists of a set of
46  /// bins which count the number of events falling into these
47  /// bins. Currently only one dimensional histograms with uniformly
48  /// spaced bins are supported.
49  ///
50  class Histogram
51  {
52  public:
53
54    ///
55    /// The default constructor.
56    ///
57    Histogram(void);
58
59    ///
60    /// The copy constructor.
61    ///
62    Histogram(const Histogram&);
63
64    ///
65    /// Construct a histogram object that covers \f$(xmin,xmax]\f$
66    /// with the bin spacing \f$(xmax-xmin)/n\f$.
67    ///
68    Histogram(const double xmin, const double xmax, const size_t n);
69
70    virtual ~Histogram(void);
71
72    ///
73    /// Update the histogram by adding \a weight to the bin whose
74    /// range contains the observation \a x. No bins are updated when
75    /// \a x lies outside the range of the histogram but the value is
76    /// added to the overall integral of the histogram.
77    ///
78    /// @short Add a data point to the histogram.
79    ///
80    /// @return 0 if \a x lies within the range of the histogram, -1
81    /// if \a x is smaller than the lower limit of the histogram, and
82    /// similarly, 1 is returned if \a x is greater than or equal to
83    /// the upper limit.
84    ///
85    int add(const double x,const double weight=1.0);
86
87    ///
88    /// Gives access to the AveragerWeighted object that keeps track of
89    /// average of all events presented to the histogram.
90    ///
91    /// @short Average of all events presented to the histogram.
92    ///
93    /// @return A const reference to an AveragerWeighted object.
94    ///
95    const AveragerWeighted& averager_all(void) const;
96
97    ///
98    /// Gives access to the AveragerWeighted object that keeps track of
99    /// average of events that fits within the histogram lower and
100    /// upper limits. This function is equivalent to averager().
101    ///
102    /// @short Average of events fitting within histogram.
103    ///
104    /// @return A const reference to an AveragerWeighted object.
105    ///
106    const AveragerWeighted& averager_histogram(void) const;
107
108    ///
109    /// @return The number of bins in the histogram
110    ///
111    size_t nof_bins(void) const;
112
113    ///
114    ///  There are two ways to normalize the counts.
115    ///
116    /// If choice is true: The normalized count is the count in a
117    /// bin divided by the total number of observations. In this
118    /// case the relative counts are normalized to sum to unity (
119    /// minus values outside histogram).  This is the intuitive case
120    /// where the height of the histogram bar represents the
121    /// proportion of the data in each class.
122    ///
123    /// If choice is false: The normalized count is the count in the
124    /// class divided by the number of observations times the bin
125    /// width. For this normalization, the area (or integral) under
126    /// the histogram is equal to unity (minus the missing area
127    /// corresponding to counts outside histogram). From a
128    /// probabilistic point of view, this normalization results in a
129    /// relative histogram that is most akin to the probability
130    /// density function If you want to overlay a probability density
131    /// on top of the histogram, use this normalization. Although this
132    /// normalization is less intuitive (relative frequencies greater
133    /// than 1 are quite permissible), it is the appropriate
134    /// normalization if you are using the histogram to model a
135    /// probability density function.
136    ///
137    /// @short Normalizing the histogram
138    ///
139    void normalize(bool choice = true);
140
141    ///
142    /// @return The value in the middle of bin \a k.
143    ///
144    /// @note No check is done that \a k is within the size of the
145    /// histogram.
146    ///
147    double observation_value(const size_t k) const;
148
149    ///
150    /// Set everyting to default values, here it means that everything
151    /// is set to zero except the boundary values that are kept.
152    ///
153    void reset(void);
154
155    ///
156    /// @return The width of the bins in the histogram.
157    ///
158    double spacing(void) const;
159
160    ///
161    /// @return The histogram upper boundary.
162    ///
163    /// @note The upper boundary value is outside the histogram.
164    ///
165    double xmax(void) const;
166
167    ///
168    /// @return The histogram lower boundary.
169    ///
170    /// @note The lower boundary value is inside the histogram.
171    ///
172    double xmin(void) const;
173
174    ///
175    /// @return The count of bin \a k in the histogram.
176    ///
177    double operator[](size_t k) const;
178
179    ///
180    /// The assignment operator
181    ///
182    const Histogram& operator=(const Histogram&);
183
184  private:
185    // Returns zero if outside boundaries
186    size_t bin(double d);
187
188    std::vector<double> histogram_;
189    double xmax_;
190    double xmin_;
191    statistics::AveragerWeighted sum_all_;      // average of all data
192    statistics::AveragerWeighted sum_histogram_;// average of data in histogram
193  };
194
195  /**
196     Add a range [first, last) of values to 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///
212std::ostream& operator<<(std::ostream& s,const Histogram&);
213
214}}} // of namespace statistics, yat, and theplu
215
216#endif
Note: See TracBrowser for help on using the repository browser.