All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
hist.h
Go to the documentation of this file.
1 /*
2  -------------------------------------------------------------------
3 
4  Copyright (C) 2010-2014, Andrew W. Steiner
5 
6  This file is part of O2scl.
7 
8  O2scl is free software; you can redistribute it and/or modify
9  it under the terms of the GNU General Public License as published by
10  the Free Software Foundation; either version 3 of the License, or
11  (at your option) any later version.
12 
13  O2scl is distributed in the hope that it will be useful,
14  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  GNU General Public License for more details.
17 
18  You should have received a copy of the GNU General Public License
19  along with O2scl. If not, see <http://www.gnu.org/licenses/>.
20 
21  -------------------------------------------------------------------
22 */
23 #ifndef O2SCL_HIST_H
24 #define O2SCL_HIST_H
25 
26 /** \file hist.h
27  \brief File defining \ref o2scl::hist
28 */
29 #include <iostream>
30 
31 #include <boost/numeric/ublas/vector.hpp>
32 
33 #include <o2scl/convert_units.h>
34 #include <o2scl/interp.h>
35 #include <o2scl/uniform_grid.h>
36 #include <o2scl/table.h>
37 
38 // Forward definition of the hist class for HDF I/O
39 namespace o2scl {
40  class hist;
41 }
42 
43 // Forward definition of HDF I/O to extend friendship in hist
44 namespace o2scl_hdf {
45  class hdf_file;
46  void hdf_input(hdf_file &hf, o2scl::hist &t, std::string name);
47  void hdf_output(hdf_file &hf, o2scl::hist &t, std::string name);
48 }
49 
50 #ifndef DOXYGEN_NO_O2NS
51 namespace o2scl {
52 #endif
53 
54  /** \brief A one-dimensional histogram class
55 
56  See discussion in the User's guide in the \ref hist_section
57  section.
58 
59  One may set the histogram bins using \ref set_bin_edges() or one
60  may manually set the limit of one bin using the reference
61  returned by get_bin_low(), get_bin_low_i(), get_bin_high(), or
62  get_bin_high_i(). Note that if one attempts to set the bins on a
63  histogram where the bins have already been set, one must ensure
64  that the new and old bin sets have the same size. This ensures
65  that there is no ambiguity in rebinning the data and also
66  prevents accidental data loss. One may set the bin edges
67  either with a generic vector, or as a \ref uniform_grid object.
68 
69  To save space, representative vectors are not allocated until
70  they are used.
71 
72  \note In order to ensure the histogram does not employ
73  user-specified representative values that are not defined, the
74  function \ref set_rep_mode() does not allow one to change the
75  mode to \ref rmode_user directly. Instead, use \ref set_reps()
76  which automatically sets the mode to \ref rmode_user and allows
77  the user to specify the representatives.
78 
79  \note If the user changes the bin edges and the histogram is in
80  mode \ref rmode_user, the bin weights will not be modified and
81  the same representative values will be assumed for the new bin
82  edges.
83 
84  \hline
85 
86  \todo Check implementation of <tt>hist::extend_lhs</tt>.
87  \todo More testing.
88 
89  \future
90  - Add a counter which counts the number of calls to update()?
91  - Add conversions back and forth from GSL histograms
92  - Create extend_lhs too?
93  - Would be nice not to have to create a new \ref
94  o2scl::search_vec object in \ref o2scl::hist::get_bin_index()
95  (make a search_vec data member?)
96  - Consider adding the analogs of the GSL histogram
97  sampling functions (separate class?)
98  - Add a function which computes the bin sizes?
99  - Allow rebinning?
100  - Add histograms of float and integer values
101  - Allow addition and other operations for two histograms.
102  - Make the interpolation functions \c const (this is a bit
103  complicated because of \ref o2scl::hist::set_reps_auto() ).
104 
105  \hline
106 
107  Internally, none of the vectors should have memory allocated for
108  them when hsize is zero, and the vector sizes should match the
109  histogram size. These and other checks are performed by \ref
110  is_valid() . Also, the function \ref set_reps_auto() should not
111  be called when mode is \ref rmode_user.
112  */
113  class hist {
114 
115  public:
116 
118 
119  protected:
120 
121  /// Bin locations (N+1)
123 
124  /// Bin contents (N)
126 
127  /// Bin representative values (N)
129 
130  /// User-defined representative values (N)
132 
133  /// Number of bins
134  size_t hsize;
135 
136  /// Representative mode
137  size_t rmode;
138 
139  /// Interpolation type
140  size_t itype;
141 
142  /** \brief Set the representative array according to current
143  rmode (if not in user rep mode)
144  */
145  void set_reps_auto();
146 
147  /// Interpolation typedef
149 
150  /** \brief Allocate vectors for a histogram of size \c n
151 
152  This function also sets all the weights to zero.
153  */
154  void allocate(size_t n);
155 
156  public:
157 
158  /// Create an empty histogram
159  hist();
160 
161  ~hist();
162 
163  /// Copy constructor
164  hist(const hist &h);
165 
166  /// Copy constructor
167  hist &operator=(const hist &h);
168 
169  /// The histogram size
170  size_t size() const {
171  return hsize;
172  }
173 
174  /** \brief If true, allow abcissae beyond the last bin (default false)
175 
176  If this is true, the histogram will allow data with
177  corresponding to bins larger than the largest bin
178  (for increasing bin settings) or smaller than the
179  smallest bin (for decreasing bin settings).
180  */
182 
183  /** \brief If true, allow abcissae before the first bin (default false)
184  */
186 
187  /// \name Initial bin setup
188  //@{
189  /** \brief Set bins from a \ref uniform_grid object
190 
191  If the current histogram is not empty, then the
192  number of bins reported by \ref uniform_grid<>::get_nbins()
193  should be equal to the current histogram size so that the
194  number of bins is equal and we can use the same weights.
195 
196  If either the histogram is empty, or the current
197  representative mode is not \ref rmode_user, then the
198  representative mode is automatically set to \ref rmode_avg (or
199  \ref rmode_gmean if \ref uniform_grid::is_log() returns \c
200  true ) .
201  */
203 
204  /** \brief Set the bins from a vector
205 
206  The parameter \c n is the size of the vector, equal to the
207  number of edges (always one more than the number of bins). If
208  the current histogram is not empty, then \c n should be equal
209  one larger to the size reported by \ref size() so that the
210  number of bins is equal and we can use the same weights.
211  */
212  template<class vec_t> void set_bin_edges(size_t n, const vec_t &v) {
213  if (n!=hsize+1) {
214  if (hsize!=0) {
215  O2SCL_ERR2("Requested binning change in non-empty ",
216  "histogram in hist::set_bin_edges().",exc_efailed);
217  }
218  allocate(n-1);
219  }
220  for(size_t i=0;i<n;i++) ubin[i]=v[i];
221  // Reset internal reps
222  if (urep.size()>0) urep.clear();
223  return;
224  }
225  //@}
226 
227  /// \name Weight functions
228  //@{
229  /// Increment bin for \c x by value \c val
230  void update(double x, double val=1.0);
231 
232  /// Increment bin with index \c i by value \c val
233  void update_i(size_t i, double val=1.0) {
234  uwgt[i]+=val;
235  return;
236  }
237 
238  /// Return contents of bin with index \c i
239  const double &get_wgt_i(size_t i) const;
240 
241  /// Return contents of bin with index \c i
242  double &get_wgt_i(size_t i);
243 
244  /// Return contents of bin for \c x
245  const double &get_wgt(double x) const {
246  return get_wgt_i(get_bin_index(x));
247  }
248 
249  /// Return contents of bin for \c x
250  double &get_wgt(double x) {
251  return get_wgt_i(get_bin_index(x));
252  }
253 
254  /// Set contents of bin with index \c i to value \c val
255  void set_wgt_i(size_t i, double val);
256 
257  /// Set contents of bin for \c x to value \c val
258  void set_wgt(double x, double val) {
259  set_wgt_i(get_bin_index(x),val);
260  return;
261  }
262 
263  /// Get a reference to the full y vector
264  const ubvector &get_wgts() const {
265  return uwgt;
266  }
267 
268  /// Get a reference to the weight for the bin at index \c i
269  const double &operator[](size_t i) const {
270  return uwgt[i];
271  }
272 
273  /// Get a reference to the weight for the bin at index \c i
274  double &operator[](size_t i) {
275  return uwgt[i];
276  }
277  //@}
278 
279  /// \name Bin manipulation
280  //@{
281  /** \brief Get the index of the bin which holds \c x
282 
283  Always returns a value between 0 and size() (inclusive)
284  */
285  size_t get_bin_index(double x) const;
286 
287  /// Get the lower edge of bin of index \c i
288  double &get_bin_low_i(size_t i);
289 
290  /// Get the lower edge of bin of index \c i
291  const double &get_bin_low_i(size_t i) const;
292 
293  /// Get the upper edge of bin of index \c i
294  double &get_bin_high_i(size_t i);
295 
296  /// Get the upper edge of bin of index \c i
297  const double &get_bin_high_i(size_t i) const;
298 
299  /// Get the lower edge of bin of index \c i
300  double &get_bin_low(double x) {
301  return get_bin_low_i(get_bin_index(x));
302  }
303 
304  /// Get the lower edge of bin of index \c i
305  const double &get_bin_low(double x) const {
306  return get_bin_low_i(get_bin_index(x));
307  }
308 
309  /// Get the upper edge of bin of index \c i
310  double &get_bin_high(double x) {
311  return get_bin_high_i(get_bin_index(x));
312  }
313 
314  /// Get the upper edge of bin of index \c i
315  const double &get_bin_high(double x) const {
316  return get_bin_high_i(get_bin_index(x));
317  }
318 
319  /// Get a reference to the full vector of bin specifications
320  const ubvector &get_bins() const {
321  return ubin;
322  }
323  //@}
324 
325  /// \name Max and min functions
326  //@{
327  /** \brief Get maximum weight
328  */
329  double get_max_wgt() const;
330 
331  /** \brief Get the bin index of the maximum weight
332  */
333  size_t get_max_index() const;
334 
335  /** \brief Get the representative for the bin with maximum weight
336  */
337  double get_max_rep();
338 
339  /** \brief Get minimum weight
340  */
341  double get_min_wgt() const;
342 
343  /** \brief Get the bin index of the minimum weight
344  */
345  size_t get_min_index() const;
346 
347  /** \brief Get the representative for the bin with minimum weight
348  */
349  double get_min_rep();
350  //@}
351 
352  /// \name Delete functions
353  //@{
354  /// Clear the data, but leave the bins as is
355  void clear_wgts();
356 
357  /// Clear the entire histogram
358  void clear();
359  //@}
360 
361  /// \name Representative modes (default is rmode_avg)
362  // Using \c rmode_avg in documentation doesn't work.
363  //@{
364  /// Average lower and upper edge
365  static const size_t rmode_avg=0;
366  /// Use user-specified representative
367  static const size_t rmode_user=1;
368  /// Use lower edge
369  static const size_t rmode_low=2;
370  /// Use upper edge
371  static const size_t rmode_high=3;
372  /// Use the geometric mean of the lower and upper edges
373  static const size_t rmode_gmean=4;
374  //@}
375 
376  /// \name Representative functions
377  //@{
378  /// Set the representative x-values for each bin
379  template<class vec_t> void set_reps(size_t n, const vec_t &v) {
380  if (n!=hsize) {
381  std::string s="Expected a vector of size "+itos(hsize)+
382  " and got a vector of size "+itos(n)+" in hist::set_reps().";
383  O2SCL_ERR(s.c_str(),exc_einval);
384  }
386  if (user_rep.size()>0) user_rep.clear();
387  user_rep.resize(n);
388  for(size_t i=0;i<n;i++) user_rep[i]=v[i];
389  return;
390  }
391 
392  /** \brief Set mode used to compute bin representatives
393 
394  Acceptable inputs are \ref rmode_avg, \ref rmode_low,
395  \ref rmode_high, and \ref rmode_gmean .
396  */
397  void set_rep_mode(size_t mode);
398 
399  /// Get mode used to compute bin representatives
400  size_t get_rep_mode() const {
401  return rmode;
402  }
403 
404  /** \brief Return the representative of bin of index \c i
405 
406  Note that this function returns a value and not a reference.
407  This is because we can't return a reference to the internally
408  computed representatives, since they don't always exist.
409  */
410  double get_rep_i(size_t i);
411 
412  /// Return the representative of bin containing \c x
413  double get_rep(double x) {
414  return get_rep_i(get_bin_index(x));
415  }
416 
417  /** \brief Create a vector filled with the representatives for
418  each bin
419  */
420  template<class resize_vec_t> void create_rep_vec(resize_vec_t &v) {
421  v.resize(hsize);
422  for(size_t i=0;i<hsize;i++) {
423  v[i]=get_rep_i(i);
424  }
425  return;
426  }
427  //@}
428 
429  /// \name Evaluation and interpolation functions
430  //@{
431  /// Return the value of the function at \c x
432  double operator()(double x);
433 
434  /// Return the value of the function at \c x
435  double interp(double x);
436 
437  /// Return the derivative of the function at \c x
438  double deriv(double x);
439 
440  /// Return the second derivative of the function at \c x
441  double deriv2(double x);
442 
443  /// Return the integral of the function between \c x and \c y
444  double integ(double x, double y);
445 
446  /// Set the interpolation type
447  void set_interp_type(size_t interp_type);
448  //@}
449 
450  /// \name Other functions
451  //@{
452  /** \brief Renormalize the weights to fix the integral
453 
454  This computes the integral using \ref integ() and so the
455  action of this function depends on the interpolation type.
456  If the histogram is empty, an exception is thrown.
457  */
458  void normalize(double new_sum);
459 
460  /// Internal consistency check
461  void is_valid() const;
462 
463  /** \brief Copy histogram data to a table
464 
465  First, if the table \c t has less rows than the histogram has
466  bins, then new rows are added to the table and values in the
467  new rows of the current columns are set to zero. Second, this
468  creates new columns in the table named \c reps, \c
469  lower_edges, \c upper_edges, and \c weights . Finally,
470  the histogram data is copied to the four new columns.
471  */
472  void copy_to_table(table<> &t, std::string reps, std::string lower_edges,
473  std::string upper_edges, std::string weights);
474  //@}
475 
476  // Allow HDF I/O function to access hist data
477  friend void o2scl_hdf::hdf_output(o2scl_hdf::hdf_file &hf, o2scl::hist &h,
478  std::string name);
479 
480  // Allow HDF I/O function to access hist data
482  std::string name);
483 
484  };
485 
486 #ifndef DOXYGEN_NO_O2NS
487 }
488 #endif
489 
490 #endif
Interpolation class for pre-specified vector.
Definition: interp.h:1420
interp_vec< ubvector > interp_t
Interpolation typedef.
Definition: hist.h:148
ubvector ubin
Bin locations (N+1)
Definition: hist.h:122
size_t get_bin_index(double x) const
Get the index of the bin which holds x.
const double & get_wgt_i(size_t i) const
Return contents of bin with index i.
size_t itype
Interpolation type.
Definition: hist.h:140
const double & operator[](size_t i) const
Get a reference to the weight for the bin at index i.
Definition: hist.h:269
double & get_bin_low_i(size_t i)
Get the lower edge of bin of index i.
Data table table class.
Definition: table.h:47
double get_max_rep()
Get the representative for the bin with maximum weight.
void set_wgt_i(size_t i, double val)
Set contents of bin with index i to value val.
void copy_to_table(table<> &t, std::string reps, std::string lower_edges, std::string upper_edges, std::string weights)
Copy histogram data to a table.
double get_max_wgt() const
Get maximum weight.
void set_wgt(double x, double val)
Set contents of bin for x to value val.
Definition: hist.h:258
invalid argument supplied by user
Definition: err_hnd.h:59
const double & get_wgt(double x) const
Return contents of bin for x.
Definition: hist.h:245
ubvector uwgt
Bin contents (N)
Definition: hist.h:125
bool extend_rhs
If true, allow abcissae beyond the last bin (default false)
Definition: hist.h:181
double integ(double x, double y)
Return the integral of the function between x and y.
const ubvector & get_wgts() const
Get a reference to the full y vector.
Definition: hist.h:264
void is_valid() const
Internal consistency check.
double operator()(double x)
Return the value of the function at x.
size_t size() const
The histogram size.
Definition: hist.h:170
generic failure
Definition: err_hnd.h:61
A one-dimensional histogram class.
Definition: hist.h:113
ubvector urep
Bin representative values (N)
Definition: hist.h:128
double get_min_wgt() const
Get minimum weight.
double get_rep_i(size_t i)
Return the representative of bin of index i.
static const size_t rmode_avg
Average lower and upper edge.
Definition: hist.h:365
double interp(double x)
Return the value of the function at x.
bool extend_lhs
If true, allow abcissae before the first bin (default false)
Definition: hist.h:185
size_t get_rep_mode() const
Get mode used to compute bin representatives.
Definition: hist.h:400
size_t get_max_index() const
Get the bin index of the maximum weight.
static const size_t rmode_high
Use upper edge.
Definition: hist.h:371
double deriv(double x)
Return the derivative of the function at x.
const double & get_bin_high(double x) const
Get the upper edge of bin of index i.
Definition: hist.h:315
double get_rep(double x)
Return the representative of bin containing x.
Definition: hist.h:413
void update_i(size_t i, double val=1.0)
Increment bin with index i by value val.
Definition: hist.h:233
ubvector user_rep
User-defined representative values (N)
Definition: hist.h:131
#define O2SCL_ERR2(d, d2, n)
Set an error, two-string version.
Definition: err_hnd.h:281
void set_rep_mode(size_t mode)
Set mode used to compute bin representatives.
void normalize(double new_sum)
Renormalize the weights to fix the integral.
void clear_wgts()
Clear the data, but leave the bins as is.
static const size_t rmode_gmean
Use the geometric mean of the lower and upper edges.
Definition: hist.h:373
#define O2SCL_ERR(d, n)
Set an error with message d and code n.
Definition: err_hnd.h:273
double deriv2(double x)
Return the second derivative of the function at x.
double & get_wgt(double x)
Return contents of bin for x.
Definition: hist.h:250
static const size_t rmode_user
Use user-specified representative.
Definition: hist.h:367
double & get_bin_low(double x)
Get the lower edge of bin of index i.
Definition: hist.h:300
hist & operator=(const hist &h)
Copy constructor.
void update(double x, double val=1.0)
Increment bin for x by value val.
double & get_bin_high(double x)
Get the upper edge of bin of index i.
Definition: hist.h:310
size_t get_min_index() const
Get the bin index of the minimum weight.
size_t rmode
Representative mode.
Definition: hist.h:137
A class representing a uniform linear or logarithmic grid.
Definition: uniform_grid.h:38
void set_reps(size_t n, const vec_t &v)
Set the representative x-values for each bin.
Definition: hist.h:379
size_t hsize
Number of bins.
Definition: hist.h:134
void create_rep_vec(resize_vec_t &v)
Create a vector filled with the representatives for each bin.
Definition: hist.h:420
Store data in an O<span style='position: relative; top: 0.3em; font-size: 0.8em'>2</span>scl O$_2$scl...
Definition: hdf_file.h:93
void set_interp_type(size_t interp_type)
Set the interpolation type.
void set_reps_auto()
Set the representative array according to current rmode (if not in user rep mode) ...
double & operator[](size_t i)
Get a reference to the weight for the bin at index i.
Definition: hist.h:274
static const size_t rmode_low
Use lower edge.
Definition: hist.h:369
void set_bin_edges(uniform_grid< double > g)
Set bins from a uniform_grid object.
void allocate(size_t n)
Allocate vectors for a histogram of size n.
const ubvector & get_bins() const
Get a reference to the full vector of bin specifications.
Definition: hist.h:320
std::string itos(int x)
Convert an integer to a string.
hist()
Create an empty histogram.
double & get_bin_high_i(size_t i)
Get the upper edge of bin of index i.
void hdf_input(hdf_file &hf, o2scl::table< vec_t > &t, std::string name)
Input a o2scl::table object from a hdf_file.
Definition: hdf_io.h:55
void set_bin_edges(size_t n, const vec_t &v)
Set the bins from a vector.
Definition: hist.h:212
void clear()
Clear the entire histogram.
const double & get_bin_low(double x) const
Get the lower edge of bin of index i.
Definition: hist.h:305
double get_min_rep()
Get the representative for the bin with minimum weight.

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).
Hosted at Get Object-oriented Scientific Computing
Lib at SourceForge.net. Fast, secure and Free Open Source software
downloads..