Class hist_2d (o2scl)¶

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.