Class hist_2d (o2scl)

O2scl : Class List

class hist_2d

A two-dimensional histogram class.

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

To create a histogram, one can begin by setting the histogram bins using hist_2d::set_bin_edges() and then filling the data with update(), update_i(), set_wgt() or set_wgt_i() .

One can also use tabulated data to fill this histogram using, e.g. hist_2d::from_table(o2scl::table<> &, std::string,std::string, size_t, size_t)

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.

You can empty all of the histogram bins using clear_wgts() or clear everything using clear() .

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

Todo

  • Future: Create a copy_from_table3d() function.

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

  • 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?

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.

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

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>
inline void set_bin_edges(size_t nx, vec_t &vx, size_t ny, vec_t &vy)

Set the bins from a vector.

Weight functions

inline void update_i(size_t i, size_t j, double val = 1.0)

Increment bin at (i,j) by value val.

inline 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)

inline 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)

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

inline void set_wgt(double x, double y, double val)

Set contents of bin for x to value val.

inline const ubmatrix &get_wgts() const

Get a const reference to the full matrix of data.

inline ubmatrix &get_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>
inline 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>
inline void set_x_reps(size_t nx, vec_t &vx)

Set the representative x-values for each bin.

template<class vec_t>
inline 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.

inline size_t get_x_rep_mode() const

Get mode used to compute bin reps.

inline size_t get_y_rep_mode() const

Get mode used to compute bin reps.

inline const ubvector &get_x_bins() const

Get a reference to the full vector of bin specifications.

inline const ubvector &get_y_bins() const

Get a reference to the full vector of bin specifications.

inline size_t size_x() const

Return the histogram size of the x coordinate.

inline size_t size_y() const

Return the histogram size of the y coordinate.

inline const ubvector &get_user_reps_x() const

Get a reference to the user-specified reps for x coordinates.

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

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

Warning

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

inline const ubvector &get_user_reps_y() const

Get a reference to the user-specified reps for y coordinates.

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

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

Warning

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

double get_x_rep_i(size_t i)

Return the rep of bin of index 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.

double get_y_rep_i(size_t j)

Return the rep of bin of index 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.

template<class resize_vec_t>
inline void create_x_rep_vec(resize_vec_t &v)

Create a vector filled with the representatives for each bin.

template<class resize_vec_t>
inline void create_y_rep_vec(resize_vec_t &v)

Create a vector filled with the representatives for each bin.

void is_valid() const

Internal consistency check.

void copy_to_table3d(table3d &t, std::string xreps_name, std::string yreps_name, std::string weights)

Create a table3d object based on the histogram data.

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

Public Types

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

Public Functions

hist_2d()
virtual ~hist_2d()
hist_2d(const hist_2d &h)

Copy constructor.

hist_2d &operator=(const hist_2d &h)

Copy from operator=()

template<class vec_t, class vec2_t>
inline hist_2d(size_t nv, const vec_t &v, const vec2_t &v2, size_t n_bins_x, size_t n_bins_y)

Create a 2D histogram from vectors of data.

template<class vec_t, class vec2_t, class vec3_t>
inline 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 a 2D histogram from vectors of data obtaining weights from a third column.

template<class vec_t, class vec2_t>
inline hist_2d(const vec_t &v, const vec2_t &v2, size_t n_bins_x, size_t n_bins_y)

Create a 2D histogram from vectors of data.

template<class vec_t, class vec2_t, class vec3_t>
inline 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 a 2D histogram from vectors of data, obtaining weights from the third vector.

inline void from_table(o2scl::table<> &t, std::string colx, std::string coly, size_t n_bins_x, size_t n_bins_y)

Create a 2D histogram object from a table.

inline 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)

Create a 2D histogram object from a table, obtaining weights from the third column.

double sum_wgts()

Return the sum of all of the weights.

double integ_wgts()

Return the integral under the histogram.

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) \, . \]

Public Members

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

Protected Functions

void allocate(size_t nx, size_t ny)

Allocate for a histogram of size nx, ny.

This function also sets all the weights to zero.

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.