source: trunk/c++_tools/statistics/Histogram.h @ 675

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

References #83. Changing project name to yat. Compilation will fail in this revision.

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