Public Types | Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Friends | List of all members
o2scl::hist_2d Class Reference

A two-dimensional histogram class. More...

#include <hist_2d.h>

Public Types

typedef boost::numeric::ublas::vector< double > ubvector
 
typedef boost::numeric::ublas::matrix< double > ubmatrix
 

Public Member Functions

 hist_2d (const hist_2d &h)
 Copy constructor.
 
hist_2doperator= (const hist_2d &h)
 Copy from operator=()
 
template<class vec_t , class vec2_t >
 hist_2d (size_t nv, const vec_t &v, const vec2_t &v2, size_t n_bins_x, size_t n_bins_y)
 Create from vectors of data.
 
template<class vec_t , class vec2_t , class vec3_t >
 hist_2d (size_t nv, const vec_t &v, const vec2_t &v2, const vec3_t &v3, size_t n_bins_x, size_t n_bins_y)
 Create from vectors of data.
 
template<class vec_t , class vec2_t >
 hist_2d (const vec_t &v, const vec2_t &v2, size_t n_bins_x, size_t n_bins_y)
 Create from vectors of data.
 
template<class vec_t , class vec2_t , class vec3_t >
 hist_2d (const vec_t &v, const vec2_t &v2, const vec3_t &v3, size_t n_bins_x, size_t n_bins_y)
 Create from vectors of data.
 
void from_table (o2scl::table<> &t, std::string colx, std::string coly, size_t n_bins_x, size_t n_bins_y)
 
void from_table (o2scl::table<> &t, std::string colx, std::string coly, std::string colz, size_t n_bins_x, size_t n_bins_y)
 
double sum_wgts ()
 Return the sum of all of the weights.
 
double integ_wgts ()
 Return the integral under the histogram. More...
 
void is_valid () const
 Internal consistency check.
 
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.
 
Initial bin setup
void set_bin_edges (uniform_grid< double > gx, uniform_grid< double > gy)
 Set the bins from two uniform_grid objects.
 
template<class vec_t >
void set_bin_edges (size_t nx, vec_t &vx, size_t ny, vec_t &vy)
 Set the bins from a vector.
 
Weight functions
void update_i (size_t i, size_t j, double val=1.0)
 Increment bin at (i,j) by value val.
 
void update (double x, double y, double val=1.0)
 Increment bin for x by value val.
 
const double & get_wgt_i (size_t i, size_t j) const
 Return contents of bin at (i,j)
 
const double & get_wgt (double x, double y) const
 Return contents of bin for x.
 
double & get_wgt_i (size_t i, size_t j)
 Return contents of bin at (i,j)
 
double & get_wgt (double x, double y)
 Return contents of bin for x.
 
void set_wgt_i (size_t i, size_t j, double val)
 Set contents of bin at (i,j) to value val.
 
void set_wgt (double x, double y, double val)
 Set contents of bin for x to value val.
 
const ubmatrixget_wgts () const
 Get a const reference to the full matrix of data.
 
ubmatrixget_wgts ()
 Get a reference to the full matrix of data.
 
Delete functions
void clear_wgts ()
 Clear the data, but leave the bins as is.
 
void clear ()
 Clear the entire histogram.
 
Bin manipulation
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.
 
size_t get_x_bin_index (double x) const
 Get the index of the bin which holds x.
 
size_t get_y_bin_index (double y) const
 Get the indey of the bin which holds y.
 
double & get_x_low_i (size_t i)
 Get the lower edge of bin of index i.
 
const double & get_x_low_i (size_t i) const
 Get the lower edge of bin of index i.
 
double & get_x_high_i (size_t i)
 Get the upper edge of bin of index i.
 
const double & get_x_high_i (size_t i) const
 Get the upper edge of bin of index i.
 
double & get_y_low_i (size_t j)
 Get the lower edge of bin of index j.
 
const double & get_y_low_i (size_t j) const
 Get the lower edge of bin of index j.
 
double & get_y_high_i (size_t j)
 Get the upper edge of bin of index j.
 
const double & get_y_high_i (size_t j) const
 Get the upper edge of bin of index j.
 
Representative functions
template<class vec_t >
void set_reps (size_t nx, vec_t &vx, size_t ny, vec_t &vy)
 Set the representative x-values for each bin.
 
template<class vec_t >
void set_x_reps (size_t nx, vec_t &vx)
 Set the representative x-values for each bin.
 
template<class vec_t >
void set_y_reps (size_t ny, vec_t &vy)
 Set the representative y-values for each bin.
 
void set_rep_mode (size_t x_mode, size_t y_mode)
 Set mode used to compute bin reps.
 
size_t get_x_rep_mode () const
 Get mode used to compute bin reps.
 
size_t get_y_rep_mode () const
 Get mode used to compute bin reps.
 
const ubvectorget_x_bins () const
 Get a reference to the full vector of bin specifications.
 
const ubvectorget_y_bins () const
 Get a reference to the full vector of bin specifications.
 
size_t size_x () const
 Return the histogram size of the x coordinate.
 
size_t size_y () const
 Return the histogram size of the y coordinate.
 
const ubvectorget_user_reps_x () const
 Get a reference to the user-specified reps for x coordinates. More...
 
const ubvectorget_user_reps_y () const
 Get a reference to the user-specified reps for y coordinates. More...
 
double get_x_rep_i (size_t i)
 Return the rep of bin of index i. More...
 
double get_y_rep_i (size_t j)
 Return the rep of bin of index j. More...
 

Public Attributes

bool extend_rhs
 If true, allow abcissa larger than largest bin limit to correspond to the highest bin (default false).
 
bool extend_lhs
 If true, allow abcissa smaller than smallest bin limit to correspond to the lowest bin (default false).
 

Static Public Attributes

Rep modes (default is \c rmode_avg)
static const size_t rmode_avg =0
 
static const size_t rmode_user =1
 
static const size_t rmode_low =2
 
static const size_t rmode_high =3
 
static const size_t rmode_gmean =4
 

Protected Member Functions

void allocate (size_t nx, size_t ny)
 Allocate for a histogram of size nx, ny. More...
 
void set_reps_auto ()
 An internal function to automatically set xrep and yrep.
 

Protected Attributes

ubvector xa
 Bin locations (Nx+1)
 
ubvector ya
 Bin locations (Ny+1)
 
ubmatrix wgt
 Values (Nx,Ny)
 
ubvector xrep
 "Central" values for x-axis (N)
 
ubvector yrep
 "Central" values for y-axis (N)
 
ubvector user_xrep
 User-defined central values for x-axis (N)
 
ubvector user_yrep
 User-defined central values for y-axis (N)
 
size_t hsize_x
 Number of x-bins.
 
size_t hsize_y
 Number of y-bins.
 
size_t xrmode
 Rep mode for x.
 
size_t yrmode
 Rep mode for y.
 

Friends

void o2scl_hdf::hdf_output (o2scl_hdf::hdf_file &hf, o2scl::hist_2d &h, std::string name)
 
void o2scl_hdf::hdf_input (o2scl_hdf::hdf_file &hf, o2scl::hist_2d &h, std::string name)
 

Detailed Description

See discussion in the User's guide in the Histograms section.

Typical usage begins with setting the histogram bins using hist_2d::set_bin_edges(). Note that if one attempts to set the bins on a histogram where the bins have already been set, one must ensure that the new and old bin settings have the same size (in both x and y directions). This ensures that there is no ambiguity in rebinning the data and also prevents accidental data loss. One may set the bin edges either with generic vectors, or with uniform_grid objects.

Note
In order to ensure the histogram does not employ user-specified representative values that are not defined, the function set_rep_mode() does not allow one to change the mode to hist::rmode_user directly. Instead, use set_reps() which automatically sets the mode to hist::rmode_user and allows the user to specify the representatives.

Internally, either hsize_x and hsize_y should both be zero or both be non-zero.

Idea for Future:
Write a function to create a 1-d histogram from a 2-d histogram either by selecting one bin in one axis or by marginalizing over one direction.
Idea for Future:
Note that here, there is a conflict between implementing operator(size_t,size_t) to give matrix indexing of the histogram weights, and operator(double,double) to implement two-dimensional interpolation using the weights and the representatives. Currently neither is implemented, but maybe both should be implemented instead?

Definition at line 103 of file hist_2d.h.

Member Function Documentation

◆ allocate()

void o2scl::hist_2d::allocate ( size_t  nx,
size_t  ny 
)
protected

This function also sets all the weights to zero.

◆ get_user_reps_x()

const ubvector& o2scl::hist_2d::get_user_reps_x ( ) const
inline

This function will call the error handler if the x-axis representative mode is not hist::rmode_user .

Warning
This vector reference is only valid so long as the representative mode is unchanged and the function clear() is not called.

This member function is used by the O2scl HDF I/O functions.

Definition at line 511 of file hist_2d.h.

◆ get_user_reps_y()

const ubvector& o2scl::hist_2d::get_user_reps_y ( ) const
inline

This function will call the error handler if the y-axis representative mode is not hist::rmode_user .

Warning
This vector reference is only valid so long as the representative mode is unchanged and the function clear() is not called.

This member function is used by the O2scl HDF I/O functions.

Definition at line 530 of file hist_2d.h.

◆ get_x_rep_i()

double o2scl::hist_2d::get_x_rep_i ( size_t  i)

Note that this function returns a value and not a reference. This is because we can't return a reference to the internally computed representatives, since they don't always exist.

◆ get_y_rep_i()

double o2scl::hist_2d::get_y_rep_i ( size_t  j)

Note that this function returns a value and not a reference. This is because we can't return a reference to the internally computed representatives, since they don't always exist.

◆ integ_wgts()

double o2scl::hist_2d::integ_wgts ( )

This function returns the sum of

\[ w_{i,j} ( \mathrm{x,high}_i - \mathrm{x,low}_i) ( \mathrm{y,high}_j - \mathrm{y,low}_j) \, . \]


The documentation for this class was generated from the following file:

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).