Class hist_2d (o2scl)¶
-
class
o2scl
::
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.- 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.
- Idea for Future:
Create a copy_from_table3d() function.
- 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?
Initial bin setup
-
void
set_bin_edges
(uniform_grid<double> gx, uniform_grid<double> gy)¶ Set the bins from two uniform_grid objects.
Weight functions
-
void
update_i
(size_t i, size_t j, double val = 1.0)¶ Increment bin at
(i,j)
by valueval
.
-
void
update
(double x, double y, double val = 1.0)¶ Increment bin for
x
by valueval
.
-
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 valueval
.
-
void
set_wgt
(double x, double y, double val)¶ Set contents of bin for
x
to valueval
.
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 holdsy
.
-
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
.
Rep modes (default is \c rmode_avg)
-
const size_t
rmode_avg
= 0¶
-
const size_t
rmode_user
= 1¶
-
const size_t
rmode_low
= 2¶
-
const size_t
rmode_high
= 3¶
-
const size_t
rmode_gmean
= 4¶
Representative functions
-
template<class
vec_t
>
voidset_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
>
voidset_x_reps
(size_t nx, vec_t &vx)¶ Set the representative x-values for each bin.
-
template<class
vec_t
>
voidset_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.
-
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.
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.
-
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.
-
void
is_valid
() const¶ Internal consistency check.
Public Types
-
typedef boost::numeric::ublas::vector<double>
ubvector
¶
-
typedef boost::numeric::ublas::matrix<double>
ubmatrix
¶
Public Functions
-
hist_2d
()¶
-
~hist_2d
()¶
-
hist_2d &
operator=
(const hist_2d &h)¶ Copy from
operator=()
-
template<class
vec_t
, classvec2_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
, classvec2_t
, classvec3_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
, classvec2_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
, classvec2_t
, classvec3_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.
-
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.
-
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.