All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
hist_2d.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_2D_H
24 #define O2SCL_HIST_2D_H
25 
26 /** \file hist_2d.h
27  \brief File defining \ref o2scl::hist_2d
28 */
29 #include <iostream>
30 
31 #include <boost/numeric/ublas/vector.hpp>
32 #include <boost/numeric/ublas/matrix.hpp>
33 
34 #include <o2scl/convert_units.h>
35 #include <o2scl/interp.h>
36 #include <o2scl/uniform_grid.h>
37 #include <o2scl/table3d.h>
38 
39 // Forward definition of the hist_2d class for HDF I/O
40 namespace o2scl {
41  class hist_2d;
42 }
43 
44 // Forward definition of HDF I/O to extend friendship
45 namespace o2scl_hdf {
46  class hdf_file;
47  void hdf_input(hdf_file &hf, o2scl::hist_2d &t, std::string name);
48  void hdf_output(hdf_file &hf, o2scl::hist_2d &t, std::string name);
49 }
50 
51 #ifndef DOXYGEN_NO_O2NS
52 namespace o2scl {
53 #endif
54 
55  /** \brief A two-dimensional histogram class
56 
57  See discussion in the User's guide in the \ref hist_section
58  section.
59 
60  Typical usage begins with setting the histogram bins using
61  \ref hist_2d::set_bin_edges(). Note that if one attempts to set
62  the bins on a histogram where the bins have already been set,
63  one must ensure that the new and old bin settings have the same
64  size (in both x and y directions). This ensures that there is no
65  ambiguity in rebinning the data and also prevents accidental
66  data loss. One may set the bin edges either with generic
67  vectors, or with \ref uniform_grid objects.
68 
69  \note In order to ensure the histogram does not employ
70  user-specified representative values that are not defined, the
71  function \ref set_rep_mode() does not allow one to change the
72  mode to \ref hist::rmode_user directly. Instead, use \ref
73  set_reps() which automatically sets the mode to \ref
74  hist::rmode_user and allows the user to specify the
75  representatives.
76 
77  \comment
78 
79  This is commented out for now. The \ref twod_intp
80  object stores a reference to xrep and yrep, and thus
81  can't be used since xrep and yrep don't always exist.
82 
83  Interpolation for \ref hist_2d objects is performed by creating
84  a \ref twod_intp object from the internal histogram data. This
85  is done using \ref o2scl::hist_2d::setup_interp() .
86 
87  \endcomment
88 
89  Internally, either \ref hsize_x and \ref hsize_y should
90  both be zero or both be non-zero.
91 
92  \future Write a function to create a 1-d histogram
93  from a 2-d histogram either by selecting one bin
94  in one axis or by marginalizing over one direction.
95 
96  \future Note that here, there is a conflict between implementing
97  operator(size_t,size_t) to give matrix indexing of the histogram
98  weights, and operator(double,double) to implement
99  two-dimensional interpolation using the weights and the
100  representatives. Currently neither is implemented, but maybe
101  both should be implemented instead?
102  */
103  class hist_2d {
104 
105  public:
106 
109 
110  protected:
111 
112  /// Bin locations (Nx+1)
114 
115  /// Bin locations (Ny+1)
117 
118  /// Values (Nx,Ny)
120 
121  /// "Central" values for x-axis (N)
123 
124  /// "Central" values for y-axis (N)
126 
127  /// User-defined central values for x-axis (N)
129 
130  /// User-defined central values for y-axis (N)
132 
133  /// Number of x-bins
134  size_t hsize_x;
135 
136  /// Number of y-bins
137  size_t hsize_y;
138 
139  /// Rep mode for x
140  size_t xrmode;
141 
142  /// Rep mode for y
143  size_t yrmode;
144 
145  /// Interpolation type
146  size_t itype;
147 
148  /** \brief Allocate for a histogram of size \c nx, \c ny
149 
150  This function also sets all the weights to zero.
151  */
152  void allocate(size_t nx, size_t ny);
153 
154  /** \brief An internal function to automatically set
155  \ref xrep and \ref yrep
156  */
157  void set_reps_auto();
158 
159  public:
160 
161  hist_2d();
162 
163  virtual ~hist_2d();
164 
165  /// Copy constructor
166  hist_2d(const hist_2d &h);
167 
168  /// Copy from <tt>operator=()</tt>
169  hist_2d &operator=(const hist_2d &h);
170 
171  /** \brief If true, allow abcissa larger than largest bin limit
172  to correspond to the highest bin (default false).
173  */
175 
176  /** \brief If true, allow abcissa smaller than smallest bin
177  limit to correspond to the lowest bin (default false).
178  */
180 
181  /// \name Initial bin setup
182  //@{
183  /// Set the bins from two \ref uniform_grid objects
185 
186  /// Set the bins from a vector
187  template<class vec_t> void set_bin_edges(size_t nx, vec_t &vx,
188  size_t ny, vec_t &vy) {
189  if (nx!=hsize_x+1 || ny!=hsize_y+1) {
190  if (hsize_x!=0 || hsize_y!=0) {
191  O2SCL_ERR2("Requested binning change in non-empty ",
192  "histogram in hist_2d::set_bin_edges().",
193  exc_efailed);
194  }
195  allocate(nx-1,ny-1);
196  }
197  for(size_t i=0;i<nx;i++) xa[i]=vx[i];
198  for(size_t i=0;i<ny;i++) ya[i]=vy[i];
199  // Reset internal reps
200  if (xrep.size()>0) xrep.resize(0);
201  if (yrep.size()>0) yrep.resize(0);
202  return;
203  }
204  //@}
205 
206  /// \name Weight functions
207  //@{
208  /// Increment bin at <tt>(i,j)</tt> by value \c val
209  void update_i(size_t i, size_t j, double val=1.0) {
210  wgt(i,j)+=val;
211  return;
212  }
213 
214  /// Increment bin for \c x by value \c val
215  void update(double x, double y, double val=1.0) {
216  size_t i, j;
217  get_bin_indices(x,y,i,j);
218  update_i(i,j,val);
219  return;
220  }
221 
222  /// Return contents of bin at <tt>(i,j)</tt>
223  const double &get_wgt_i(size_t i, size_t j) const;
224 
225  /// Return contents of bin for \c x
226  const double &get_wgt(double x, double y) const {
227  size_t i, j;
228  get_bin_indices(x,y,i,j);
229  return get_wgt_i(i,j);
230  }
231 
232  /// Return contents of bin at <tt>(i,j)</tt>
233  double &get_wgt_i(size_t i, size_t j);
234 
235  /// Return contents of bin for \c x
236  double &get_wgt(double x, double y) {
237  size_t i, j;
238  get_bin_indices(x,y,i,j);
239  return get_wgt_i(i,j);
240  }
241 
242  /// Set contents of bin at <tt>(i,j)</tt> to value \c val
243  void set_wgt_i(size_t i, size_t j, double val);
244 
245  /// Set contents of bin for \c x to value \c val
246  void set_wgt(double x, double y, double val) {
247  size_t i, j;
248  get_bin_indices(x,y,i,j);
249  set_wgt_i(i,j,val);
250  return;
251  }
252 
253  /// Get a const reference to the full matrix of data
254  const ubmatrix &get_wgts() const {
255  return wgt;
256  }
257 
258  /// Get a reference to the full matrix of data
260  return wgt;
261  }
262  //@}
263 
264  /// \name Delete functions
265  //@{
266  /// Clear the data, but leave the bins as is
267  void clear_wgts();
268 
269  /// Clear the entire histogram
270  void clear();
271  //@}
272 
273  /// \name Bin manipulation
274  //@{
275  /** \brief Get the index of the bin which holds \c x and
276  the bin which holds \c y
277  */
278  void get_bin_indices(double x, double y, size_t &i, size_t &j) const;
279 
280  /// Get the index of the bin which holds \c x
281  size_t get_x_bin_index(double x) const;
282 
283  /// Get the indey of the bin which holds \c y
284  size_t get_y_bin_index(double y) const;
285 
286  /// Get the lower edge of bin of index \c i
287  double &get_x_low_i(size_t i);
288 
289  /// Get the lower edge of bin of index \c i
290  const double &get_x_low_i(size_t i) const;
291 
292  /// Get the upper edge of bin of index \c i
293  double &get_x_high_i(size_t i);
294 
295  /// Get the upper edge of bin of index \c i
296  const double &get_x_high_i(size_t i) const;
297 
298  /// Get the lower edge of bin of index \c j
299  double &get_y_low_i(size_t j);
300 
301  /// Get the lower edge of bin of index \c j
302  const double &get_y_low_i(size_t j) const;
303 
304  /// Get the upper edge of bin of index \c j
305  double &get_y_high_i(size_t j);
306 
307  /// Get the upper edge of bin of index \c j
308  const double &get_y_high_i(size_t j) const;
309  //@}
310 
311  /// \name Rep modes (default is \c rmode_avg)
312  //@{
313  static const size_t rmode_avg=0;
314  static const size_t rmode_user=1;
315  static const size_t rmode_low=2;
316  static const size_t rmode_high=3;
317  static const size_t rmode_gmean=4;
318  //@}
319 
320  /// \name Representative functions
321  //@{
322  /// Set the representative x-values for each bin
323  template<class vec_t> void set_reps(size_t nx, vec_t &vx,
324  size_t ny, vec_t &vy) {
325  if (user_xrep.size()!=hsize_x || user_yrep.size()!=hsize_y) {
326  std::string s="Expected vectors of size "+itos(hsize_x)+
327  ", "+itos(hsize_y)+" and got a vectors of size "+itos(nx)+
328  ", "+itos(ny)+" in hist_2d::set_reps().";
329  O2SCL_ERR(s.c_str(),exc_einval);
330  }
331  xrmode=rmode_user;
332  yrmode=rmode_user;
333  if (user_xrep.size()>0) user_xrep.clear();
334  if (user_yrep.size()>0) user_yrep.clear();
335  user_xrep.resize(nx);
336  user_yrep.resize(ny);
337  for(size_t i=0;i<nx;i++) user_xrep[i]=vx[i];
338  for(size_t i=0;i<ny;i++) user_yrep[i]=vy[i];
339  return;
340  }
341 
342  /// Set the representative x-values for each bin
343  template<class vec_t> void set_x_reps(size_t nx, vec_t &vx) {
344  if (hsize_x!=nx) {
345  std::string s="Expected vector of size "+itos(hsize_x)+
346  " and got a vector of size "+itos(nx)+" in hist_2d::set_reps().";
347  O2SCL_ERR(s.c_str(),exc_einval);
348  }
349  xrmode=rmode_user;
350  if (user_xrep.size()>0) user_xrep.clear();
351  user_xrep.resize(nx);
352  for(size_t i=0;i<nx;i++) user_xrep[i]=vx[i];
353  return;
354  }
355 
356  /// Set the representative y-values for each bin
357  template<class vec_t> void set_y_reps(size_t ny, vec_t &vy) {
358  if (hsize_y!=ny) {
359  std::string s="Expected vector of size "+itos(hsize_y)+
360  " and got a vector of size "+itos(ny)+" in hist_2d::set_reps().";
361  O2SCL_ERR(s.c_str(),exc_einval);
362  }
363  yrmode=rmode_user;
364  if (user_yrep.size()>0) user_yrep.clear();
365  user_yrep.resize(ny);
366  for(size_t i=0;i<ny;i++) user_yrep[i]=vy[i];
367  return;
368  }
369 
370  /// Set mode used to compute bin reps
371  void set_rep_mode(size_t x_mode, size_t y_mode);
372 
373  /// Get mode used to compute bin reps
374  size_t get_x_rep_mode() const {
375  return xrmode;
376  }
377 
378  /// Get mode used to compute bin reps
379  size_t get_y_rep_mode() const {
380  return yrmode;
381  }
382 
383  /// Get a reference to the full vector of bin specifications
384  const ubvector &get_x_bins() const {
385  return xa;
386  }
387 
388  /// Get a reference to the full vector of bin specifications
389  const ubvector &get_y_bins() const {
390  return ya;
391  }
392 
393  /// Return the histogram size of the x coordinate
394  size_t size_x() const {
395  return hsize_x;
396  }
397 
398  /// Return the histogram size of the y coordinate
399  size_t size_y() const {
400  return hsize_y;
401  }
402 
403  /** \brief Get a reference to the user-specified reps for x coordinates
404 
405  This function will call the error handler if the x-axis
406  representative mode is not \ref hist::rmode_user .
407 
408  \warning This vector reference is only valid so long as
409  the representative mode is unchanged and the function
410  clear() is not called.
411 
412  This member function is used by the \o2 HDF I/O functions.
413  */
414  const ubvector &get_user_reps_x() const {
415  if (xrmode!=rmode_user) {
416  O2SCL_ERR("Not user mode in hist::get_user_reps_x().",
417  exc_efailed);
418  }
419  return user_xrep;
420  }
421 
422  /** \brief Get a reference to the user-specified reps for y coordinates
423 
424  This function will call the error handler if the y-axis
425  representative mode is not \ref hist::rmode_user .
426 
427  \warning This vector reference is only valid so long as
428  the representative mode is unchanged and the function
429  clear() is not called.
430 
431  This member function is used by the \o2 HDF I/O functions.
432  */
433  const ubvector &get_user_reps_y() const {
434  if (yrmode!=rmode_user) {
435  O2SCL_ERR("Not user mode in hist::get_user_reps_y().",
436  exc_efailed);
437  }
438  return user_yrep;
439  }
440 
441  /** \brief Return the rep of bin of index \c i
442 
443  Note that this function returns a value and not a reference.
444  This is because we can't return a reference to the internally
445  computed representatives, since they don't always exist.
446  */
447  double get_x_rep_i(size_t i);
448 
449  /** \brief Return the rep of bin of index \c j
450 
451  Note that this function returns a value and not a reference.
452  This is because we can't return a reference to the internally
453  computed representatives, since they don't always exist.
454  */
455  double get_y_rep_i(size_t j);
456  //@}
457 
458  /* \brief Set up a twod_intp object for interpolation
459 
460  \future This is commented out for now. The \ref twod_intp
461  object stores a reference to xrep and yrep, and thus
462  can't be used since xrep and yrep don't always exist.
463  */
464  //void setup_interp(twod_intp &ti, bool x_first=true) {
465  //ti.set_data(hsize_x,hsize_y,xrep,yrep,wgt,x_first);
466  //return;
467  //}
468 
469  /// Internal consistency check
470  void is_valid() const;
471 
472  /** \brief Create a table3d object based on the histogram data
473  */
474  void copy_to_table(table3d &t, std::string xreps_name,
475  std::string yreps_name, std::string weights);
476 
477  friend void o2scl_hdf::hdf_output(o2scl_hdf::hdf_file &hf,
478  o2scl::hist_2d &h, std::string name);
479  friend void o2scl_hdf::hdf_input(o2scl_hdf::hdf_file &hf,
480  o2scl::hist_2d &h, std::string name);
481 
482  };
483 
484 #ifndef DOXYGEN_NO_O2NS
485 }
486 #endif
487 
488 #endif
void allocate(size_t nx, size_t ny)
Allocate for a histogram of size nx, ny.
void set_reps_auto()
An internal function to automatically set xrep and yrep.
const ubvector & get_x_bins() const
Get a reference to the full vector of bin specifications.
Definition: hist_2d.h:384
ubvector ya
Bin locations (Ny+1)
Definition: hist_2d.h:116
size_t get_x_rep_mode() const
Get mode used to compute bin reps.
Definition: hist_2d.h:374
ubvector xa
Bin locations (Nx+1)
Definition: hist_2d.h:113
double & get_y_high_i(size_t j)
Get the upper edge of bin of index j.
void set_y_reps(size_t ny, vec_t &vy)
Set the representative y-values for each bin.
Definition: hist_2d.h:357
size_t hsize_y
Number of y-bins.
Definition: hist_2d.h:137
void set_bin_edges(uniform_grid< double > gx, uniform_grid< double > gy)
Set the bins from two uniform_grid objects.
hist_2d & operator=(const hist_2d &h)
Copy from operator=()
invalid argument supplied by user
Definition: err_hnd.h:59
const ubvector & get_y_bins() const
Get a reference to the full vector of bin specifications.
Definition: hist_2d.h:389
double & get_x_high_i(size_t i)
Get the upper edge of bin of index i.
void set_wgt(double x, double y, double val)
Set contents of bin for x to value val.
Definition: hist_2d.h:246
size_t get_y_rep_mode() const
Get mode used to compute bin reps.
Definition: hist_2d.h:379
ubvector yrep
"Central" values for y-axis (N)
Definition: hist_2d.h:125
void set_reps(size_t nx, vec_t &vx, size_t ny, vec_t &vy)
Set the representative x-values for each bin.
Definition: hist_2d.h:323
A two-dimensional histogram class.
Definition: hist_2d.h:103
size_t itype
Interpolation type.
Definition: hist_2d.h:146
void is_valid() const
Internal consistency check.
double get_y_rep_i(size_t j)
Return the rep of bin of index j.
size_t get_y_bin_index(double y) const
Get the indey of the bin which holds y.
void set_rep_mode(size_t x_mode, size_t y_mode)
Set mode used to compute bin reps.
void set_x_reps(size_t nx, vec_t &vx)
Set the representative x-values for each bin.
Definition: hist_2d.h:343
ubmatrix & get_wgts()
Get a reference to the full matrix of data.
Definition: hist_2d.h:259
const ubvector & get_user_reps_x() const
Get a reference to the user-specified reps for x coordinates.
Definition: hist_2d.h:414
generic failure
Definition: err_hnd.h:61
bool extend_lhs
If true, allow abcissa smaller than smallest bin limit to correspond to the lowest bin (default false...
Definition: hist_2d.h:179
const ubvector & get_user_reps_y() const
Get a reference to the user-specified reps for y coordinates.
Definition: hist_2d.h:433
double & get_y_low_i(size_t j)
Get the lower edge of bin of index j.
void get_bin_indices(double x, double y, size_t &i, size_t &j) const
Get the index of the bin which holds x and the bin which holds y.
bool extend_rhs
If true, allow abcissa larger than largest bin limit to correspond to the highest bin (default false)...
Definition: hist_2d.h:174
void clear()
Clear the entire histogram.
ubvector xrep
"Central" values for x-axis (N)
Definition: hist_2d.h:122
void update(double x, double y, double val=1.0)
Increment bin for x by value val.
Definition: hist_2d.h:215
const double & get_wgt(double x, double y) const
Return contents of bin for x.
Definition: hist_2d.h:226
#define O2SCL_ERR2(d, d2, n)
Set an error, two-string version.
Definition: err_hnd.h:281
ubmatrix wgt
Values (Nx,Ny)
Definition: hist_2d.h:119
void set_bin_edges(size_t nx, vec_t &vx, size_t ny, vec_t &vy)
Set the bins from a vector.
Definition: hist_2d.h:187
void set_wgt_i(size_t i, size_t j, double val)
Set contents of bin at (i,j) to value val.
size_t size_x() const
Return the histogram size of the x coordinate.
Definition: hist_2d.h:394
ubvector user_yrep
User-defined central values for y-axis (N)
Definition: hist_2d.h:131
void copy_to_table(table3d &t, std::string xreps_name, std::string yreps_name, std::string weights)
Create a table3d object based on the histogram data.
size_t xrmode
Rep mode for x.
Definition: hist_2d.h:140
#define O2SCL_ERR(d, n)
Set an error with message d and code n.
Definition: err_hnd.h:273
size_t size_y() const
Return the histogram size of the y coordinate.
Definition: hist_2d.h:399
double get_x_rep_i(size_t i)
Return the rep of bin of index i.
const ubmatrix & get_wgts() const
Get a const reference to the full matrix of data.
Definition: hist_2d.h:254
void clear_wgts()
Clear the data, but leave the bins as is.
const double & get_wgt_i(size_t i, size_t j) const
Return contents of bin at (i,j)
void update_i(size_t i, size_t j, double val=1.0)
Increment bin at (i,j) by value val.
Definition: hist_2d.h:209
A class representing a uniform linear or logarithmic grid.
Definition: uniform_grid.h:38
A data structure containing many slices of two-dimensional data points defined on a grid...
Definition: table3d.h:76
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
size_t get_x_bin_index(double x) const
Get the index of the bin which holds x.
double & get_wgt(double x, double y)
Return contents of bin for x.
Definition: hist_2d.h:236
double & get_x_low_i(size_t i)
Get the lower edge of bin of index i.
ubvector user_xrep
User-defined central values for x-axis (N)
Definition: hist_2d.h:128
std::string itos(int x)
Convert an integer to a string.
size_t hsize_x
Number of x-bins.
Definition: hist_2d.h:134
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
size_t yrmode
Rep mode for y.
Definition: hist_2d.h:143

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..