source: trunk/yat/statistics/Histogram.h

Last change on this file was 3550, checked in by Peter, 5 years ago

Update copyright years. Happy New Year

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.5 KB
Line 
1#ifndef _theplu_yat_statistics_histogram_
2#define _theplu_yat_statistics_histogram_
3
4// $Id: Histogram.h 3550 2017-01-03 05:41:02Z 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, 2010, 2016 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/concept_check.h"
31#include "yat/utility/iterator_traits.h"
32
33#include <boost/concept_check.hpp>
34#include <boost/iterator/iterator_concepts.hpp>
35
36#include <iosfwd>
37#include <string>
38#include <vector>
39
40namespace theplu {
41namespace yat {
42namespace statistics {
43
44  ///
45  /// @brief Histograms provide a convenient way of presenting the
46  /// distribution of a set of data.
47  ///
48  /// A histogram consists of a set of
49  /// bins which count the number of events falling into these
50  /// bins. Currently only one dimensional histograms with uniformly
51  /// spaced bins are supported.
52  ///
53  class Histogram
54  {
55  public:
56
57    ///
58    /// The default constructor.
59    ///
60    Histogram(void);
61
62    /**
63       \brief The istream constructor.
64
65       This constructor creates a Histogram from output (possibly)
66       created with operator<<. Note that the output from operator<<
67       does not contain all information required to restore the
68       Histogram. The values of all bins are restored, but the
69       averagers, averager_all(void) and averager_histogram(void), and
70       more specifically the second moment (sum_xx) in the averagers
71       cannot be restored due to lack of information in the output.
72
73       \since New in yat 0.7
74    */
75    Histogram(std::istream&);
76
77    ///
78    /// The copy constructor.
79    ///
80    Histogram(const Histogram&);
81
82    ///
83    /// Construct a histogram object that covers \f$(xmin,xmax]\f$
84    /// with the bin spacing \f$(xmax-xmin)/n\f$.
85    ///
86    Histogram(const double xmin, const double xmax, const size_t n);
87
88    virtual ~Histogram(void);
89
90    ///
91    /// Update the histogram by adding \a weight to the bin whose
92    /// range contains the observation \a x. No bins are updated when
93    /// \a x lies outside the range of the histogram but the value is
94    /// added to the overall integral of the histogram.
95    ///
96    /// @short Add a data point to the histogram.
97    ///
98    /// @return 0 if \a x lies within the range of the histogram, -1
99    /// if \a x is smaller than the lower limit of the histogram, and
100    /// similarly, 1 is returned if \a x is greater than or equal to
101    /// the upper limit.
102    ///
103    int add(const double x,const double weight=1.0);
104
105    ///
106    /// Gives access to the AveragerWeighted object that keeps track of
107    /// average of all events presented to the histogram.
108    ///
109    /// @short Average of all events presented to the histogram.
110    ///
111    /// @return A const reference to an AveragerWeighted object.
112    ///
113    const AveragerWeighted& averager_all(void) const;
114
115    ///
116    /// Gives access to the AveragerWeighted object that keeps track of
117    /// average of events that fits within the histogram lower and
118    /// upper limits. This function is equivalent to averager().
119    ///
120    /// @short Average of events fitting within histogram.
121    ///
122    /// @return A const reference to an AveragerWeighted object.
123    ///
124    const AveragerWeighted& averager_histogram(void) const;
125
126    ///
127    /// @return The number of bins in the histogram
128    ///
129    size_t nof_bins(void) const;
130
131    ///
132    ///  There are two ways to normalize the counts.
133    ///
134    /// If choice is true: The normalized count is the count in a
135    /// bin divided by the total number of observations. In this
136    /// case the relative counts are normalized to sum to unity (
137    /// minus values outside histogram).  This is the intuitive case
138    /// where the height of the histogram bar represents the
139    /// proportion of the data in each class.
140    ///
141    /// If choice is false: The normalized count is the count in the
142    /// class divided by the number of observations times the bin
143    /// width. For this normalization, the area (or integral) under
144    /// the histogram is equal to unity (minus the missing area
145    /// corresponding to counts outside histogram). From a
146    /// probabilistic point of view, this normalization results in a
147    /// relative histogram that is most akin to the probability
148    /// density function If you want to overlay a probability density
149    /// on top of the histogram, use this normalization. Although this
150    /// normalization is less intuitive (relative frequencies greater
151    /// than 1 are quite permissible), it is the appropriate
152    /// normalization if you are using the histogram to model a
153    /// probability density function.
154    ///
155    /// @short Normalizing the histogram
156    ///
157    void normalize(bool choice = true);
158
159    ///
160    /// @return The value in the middle of bin \a k.
161    ///
162    /// @note No check is done that \a k is within the size of the
163    /// histogram.
164    ///
165    double observation_value(const size_t k) const;
166
167    /**
168       multiply value of each bin with \a factor
169       
170       \since New in yat 0.6
171     */
172    void rescale(double factor);
173
174    ///
175    /// Set everyting to default values, here it means that everything
176    /// is set to zero except the boundary values that are kept.
177    ///
178    void reset(void);
179
180    ///
181    /// @return The width of the bins in the histogram.
182    ///
183    double spacing(void) const;
184
185    ///
186    /// @return The histogram upper boundary.
187    ///
188    /// @note The upper boundary value is outside the histogram.
189    ///
190    double xmax(void) const;
191
192    ///
193    /// @return The histogram lower boundary.
194    ///
195    /// @note The lower boundary value is inside the histogram.
196    ///
197    double xmin(void) const;
198
199    ///
200    /// @return The count of bin \a k in the histogram.
201    ///
202    double operator[](size_t k) const;
203
204    ///
205    /// The assignment operator
206    ///
207    const Histogram& operator=(const Histogram&);
208
209    /**
210       \brief Addition operator
211
212       \note The bins in lhs and rhs must match, i.e., min, max, and
213       nof_bins() must be equal in lhs and rhs.
214
215       \since New in yat 0.6
216    */
217    const Histogram& operator+=(const Histogram& rhs);
218
219  private:
220    // Returns zero if outside boundaries
221    size_t bin(double d);
222
223    std::vector<double> histogram_;
224    double xmax_;
225    double xmin_;
226    statistics::AveragerWeighted sum_all_;      // average of all data
227    statistics::AveragerWeighted sum_histogram_;// average of data in histogram
228  };
229
230  /**
231     Add a range [first, last) of values to Histogram.
232
233     Type Requirements:
234     - \c Iterator models a \ref concept_data_iterator
235     - \c Iterator models a \single_pass_iterator
236
237     \relates Histogram
238   */
239  template<typename Iterator>
240  void add(Histogram& h, Iterator first, Iterator last)
241  {
242    BOOST_CONCEPT_ASSERT((boost_concepts::SinglePassIterator<Iterator>));
243    BOOST_CONCEPT_ASSERT((utility::DataIteratorConcept<Iterator>));
244    utility::iterator_traits<Iterator> traits;
245    while (first!=last) {
246      h.add(traits.data(first), traits.weight(first));
247      ++first;
248    }
249  }
250
251  /**
252     The Histogram output operator
253
254     \relates Histogram
255  */
256  std::ostream& operator<<(std::ostream& s,const Histogram&);
257
258}}} // of namespace statistics, yat, and theplu
259
260#endif
Note: See TracBrowser for help on using the repository browser.