# source:trunk/lib/statistics/Histogram.h@372

Last change on this file since 372 was 372, checked in by Peter, 17 years ago

modified function normalize in histogram

• Property svn:eol-style set to `native`
• Property svn:keywords set to `Author Date Id Revision`
File size: 5.4 KB
Line
1// \$Id: Histogram.h 372 2005-08-05 14:14:02Z peter \$
2
3#ifndef _theplu_statistics_histogram_
4#define _theplu_statistics_histogram_
5
6#include <c++_tools/statistics/AveragerWeighted.h>
7
8#include <string>
9#include <vector>
10
11
12namespace theplu {
13namespace statistics {
14
15  ///
16  /// Histograms provide a convenient way of presenting the
17  /// distribution of a set of data. A histogram consists of a set of
18  /// bins which count the number of events falling into these
19  /// bins. Currently only one dimensional histograms with uniformly
20  /// spaced bins are supported.
21  ///
22  class Histogram
23  {
24  public:
25
26    ///
27    /// The default constructor.
28    ///
29    Histogram(void);
30
31    ///
32    /// The copy constructor.
33    ///
34    Histogram(const Histogram&);
35
36    ///
37    /// Construct a histogram object that covers \f\$(xmin,xmax]\f\$
38    /// with the bin spacing \f\$(xmax-xmin)/n\f\$.
39    ///
40    Histogram(const double xmin, const double xmax, const size_t n);
41
42    virtual ~Histogram(void);
43
44    ///
45    /// Update the histogram by adding \a weight to the bin whose
46    /// range contains the observation \a x. No bins are updated when
47    /// \a x lies outside the range of the histogram but the value is
48    /// added to the overall integral of the histogram.
49    ///
50    /// @short Add an data point to the histogram.
51    ///
52    /// @return 0 if \a x lies within the range of the histogram, -1
53    /// if \a x is smaller than the lower limit of the histogram, and
54    /// similarly, 1 is returned if \a x is greater than or equal to
55    /// the upper limit.
56    ///
57    int add(const double x,const double weight=1.0);
58
59    ///
60    /// Gives access to the AveragerWeighted object that keeps track of
61    /// average of all events presented to the histogram.
62    ///
63    /// @short Average of all events presented to the histogram.
64    ///
65    /// @return A const reference to an AveragerWeighted object.
66    ///
67    inline const statistics::AveragerWeighted& averager_all(void) const
68      { return sum_all_; }
69
70    ///
71    /// Gives access to the AveragerWeighted object that keeps track of
72    /// average of events that fits within the histogram lower and
73    /// upper limits. This function is equivalent to averager().
74    ///
75    /// @short Average of events fitting within histogram.
76    ///
77    /// @return A const reference to an AveragerWeighted object.
78    ///
79    inline const statistics::AveragerWeighted& averager_histogram(void) const
80      { return sum_histogram_; }
81
82    ///
83    /// @return The number of bins in the histogram
84    ///
85    inline size_t nof_bins(void) const { return histogram_.size(); }
86
87    ///
88    ///  There are two ways to normalize the counts.
89    ///
90    /// If choice is true: The normalized count is the count in a
91    /// bin divided by the total number of observations. In this
92    /// case the relative counts are normalized to sum to unity (
93    /// minus values outside histogram).  This is the intuitive case
94    /// where the height of the histogram bar represents the
95    /// proportion of the data in each class.
96    ///
97    /// If choice is false: The normalized count is the count in the
98    /// class divided by the number of observations times the bin
99    /// width. For this normalization, the area (or integral) under
100    /// the histogram is equal to unity (minus the missing area
101    /// corresponding to counts outside histogram). From a
102    /// probabilistic point of view, this normalization results in a
103    /// relative histogram that is most akin to the probability
104    /// density function If you want to overlay a probability density
105    /// on top of the histogram, use this normalization. Although this
106    /// normalization is less intuitive (relative frequencies greater
107    /// than 1 are quite permissible), it is the appropriate
108    /// normalization if you are using the histogram to model a
109    /// probability density function.
110    ///
111    /// @short Normalizing the histogram
112    ///
113    void normalize(bool choice = true);
114
115    ///
116    /// @return The value in the middle of bin \a k.
117    ///
118    /// @note No check is done that \a k is within the size of the
119    /// histogram.
120    ///
121    inline double observation_value(const size_t k) const
122      { return xmin_+spacing()*(k+0.5); }
123
124    ///
125    /// Set everyting to default values, here it means that everything
126    /// is set to zero except the boundary values that are kept.
127    ///
128    void reset(void);
129
130    ///
131    /// @return The width of the bins in the histogram.
132    ///
133    inline double spacing(void) const { return (xmax_-xmin_)/nof_bins(); }
134
135    ///
136    /// @return The histogram upper boundary.
137    ///
138    /// @note The upper boundary value is outside the histogram.
139    ///
140    inline double xmax(void) const { return xmax_; }
141
142    ///
143    /// @return The histogram lower boundary.
144    ///
145    /// @note The lower boundary value is inside the histogram.
146    ///
147    inline double xmin(void) const { return xmin_; }
148
149    ///
150    /// @return The count of bin \a k in the histogram.
151    ///
152    inline double operator[](size_t k) const { return histogram_[k]; }
153
154    ///
155    /// The assignment operator
156    ///
157    const Histogram& operator=(const Histogram&);
158
159  private:
160    // Returns zero if outside boundaries
161    inline size_t bin(double d)
162    { return (((d<xmin_) || (d>xmax_)) ? 0 :
163              static_cast<size_t>(floor((d-xmin_)/spacing() ))); }
164
165    std::vector<double> histogram_;
166    double xmax_;
167    double xmin_;
168    statistics::AveragerWeighted sum_all_;      // average of all data
169    statistics::AveragerWeighted sum_histogram_;// average of data in histogram
170  };
171
172///
173/// The Histogram output operator
174///
175std::ostream& operator<<(std::ostream& s,const Histogram&);
176
177}} // of namespace statistics and namespace theplu
178
179#endif
Note: See TracBrowser for help on using the repository browser.