A two-dimensional histogram class. More...

#include <hist_2d.h>

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.

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_2d &	operator= (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 a 2D histogram 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 a 2D histogram from vectors of data obtaining weights from a third column.

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 a 2D histogram 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 a 2D histogram from vectors of data, obtaining weights from the third vector. More...

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.

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

double	sum_wgts ()
	Return the sum of all of the weights.

double	integ_wgts ()
	Return the integral under the histogram. More...

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 ubmatrix &	get_wgts () const
	Get a const reference to the full matrix of data.

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

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.

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 ubvector &	get_x_bins () const
	Get a reference to the full vector of bin specifications.

const ubvector &	get_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 ubvector &	get_user_reps_x () const
	Get a reference to the user-specified reps for x coordinates. More...

const ubvector &	get_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...

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.

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)

Constructor & Destructor Documentation

◆ hist_2d()

template<class vec_t , class vec2_t , class vec3_t >

o2scl::hist_2d::hist_2d	(	const vec_t &	v,
		const vec2_t &	v2,
		const vec3_t &	v3,
		size_t	n_bins_x,
		size_t	n_bins_y
	)

inline

Definition at line 235 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.

◆ from_table()

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

inline

Definition at line 255 of file hist_2d.h.

◆ 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 519 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 538 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:

/home/awsteiner/wcs/o2scl/src/other/hist_2d.h

Detailed Description

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Representative functions

Constructor & Destructor Documentation

◆ hist_2d()

Member Function Documentation

◆ allocate()

◆ from_table()

◆ get_user_reps_x()

◆ get_user_reps_y()

◆ get_x_rep_i()

◆ get_y_rep_i()

◆ integ_wgts()