Class hist (o2scl)¶

class hist¶

A one-dimensional histogram class.

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

One may set the histogram bins using set_bin_edges() or one may manually set the limit of one bin using the reference returned by get_bin_low(), get_bin_low_i(), get_bin_high(), or get_bin_high_i(). 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 sets have the same size. 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 a generic vector, or as a uniform_grid object.

Representative vectors are not allocated and set until they are used.

Todo

Check implementation of <tt>hist::extend_lhs</tt>.
More testing.
Future: Add a counter which counts the number of calls to update()?
Future: Add conversions back and forth from GSL histograms
Future: Create extend_lhs too?
Future: Would be nice not to have to create a new ref o2scl::search_vec object in ref o2scl::hist::get_bin_index() (make a search_vec data member?)
Future: Consider adding the analogs of the GSL histogram sampling functions (separate class?)
Future: Add a function which computes the bin sizes?
Future: Allow rebinning?
Future: Add histograms of float and integer values
Future: Allow addition and other operations for two histograms.
Future: Make the interpolation functions c const (this is a bit complicated because of ref o2scl::hist::set_reps_auto() ).

Internally, none of the vectors should have memory allocated for them when hsize is zero, and the vector sizes should match the histogram size. These and other checks are performed by is_valid() . Also, the function set_reps_auto() should not be called when mode is rmode_user.

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 rmode_user directly. Instead, use set_reps() which automatically sets the mode to rmode_user and allows the user to specify the representatives.

Note

If the user changes the bin edges and the histogram is in mode rmode_user, the bin weights will not be modified and the same representative values will be assumed for the new bin edges.

Representative modes (default is rmode_avg)

static const size_t rmode_avg = 0¶: Average lower and upper edge.

static const size_t rmode_user = 1¶: Use user-specified representative.

static const size_t rmode_low = 2¶: Use lower edge.

static const size_t rmode_high = 3¶: Use upper edge.

static const size_t rmode_gmean = 4¶: Use the geometric mean of the lower and upper edges.

Initial bin setup

void set_bin_edges(uniform_grid<double> g)¶

Set bins from a uniform_grid object.

If the current histogram is not empty, then the number of bins reported by uniform_grid<>::get_nbins() should be equal to the current histogram size so that the number of bins is equal and we can use the same weights.

If either the histogram is empty, or the current representative mode is not rmode_user, then the representative mode is automatically set to rmode_avg (or rmode_gmean if uniform_grid::is_log() returns true ) .

template<class vec_t> inline void set_bin_edges(size_t n, const vec_t &v)¶

Set the bins from a vector.

The parameter n is the size of the vector, equal to the number of edges (always one more than the number of bins). If the current histogram is not empty, then n should be equal one larger to the size reported by size() so that the number of bins is equal and we can use the same weights.

Weight functions

void update(double x, double val = 1.0)¶: Increment bin for x by value val.

inline void update_i(size_t i, double val = 1.0)¶: Increment bin with index i by value val.

template<class vec_t> inline void update_vec(const vec_t &v)¶: Update from a vector of values.

const double &get_wgt_i(size_t i) const¶: Return contents of bin with index i.

double &get_wgt_i(size_t i)¶: Return contents of bin with index i.

inline const double &get_wgt(double x) const¶: Return contents of bin for x.

inline double &get_wgt(double x)¶: Return contents of bin for x.

void set_wgt_i(size_t i, double val)¶: Set contents of bin with index i to value val.

inline void set_wgt(double x, double val)¶: Set contents of bin for x to value val.

inline const ubvector &get_wgts() const¶: Get a reference to the full y vector.

inline const double &operator[](size_t i) const¶: Get a reference to the weight for the bin at index i.

inline double &operator[](size_t i)¶: Get a reference to the weight for the bin at index i.

Bin manipulation

size_t get_bin_index(double x) const¶

Get the index of the bin which holds x.

Always returns a value between 0 and size() (inclusive)

double &get_bin_low_i(size_t i)¶: Get the lower edge of bin of index i.

const double &get_bin_low_i(size_t i) const¶: Get the lower edge of bin of index i.

double &get_bin_high_i(size_t i)¶: Get the upper edge of bin of index i.

const double &get_bin_high_i(size_t i) const¶: Get the upper edge of bin of index i.

inline double &get_bin_low(double x)¶: Get the lower edge of bin of index i.

inline const double &get_bin_low(double x) const¶: Get the lower edge of bin of index i.

inline double &get_bin_high(double x)¶: Get the upper edge of bin of index i.

inline const double &get_bin_high(double x) const¶: Get the upper edge of bin of index i.

inline const ubvector &get_bins() const¶: Get a reference to the full vector of bin specifications.

int function(std::string func)¶

Apply a function.

This function sets the weights equal to a function of six variables:

i: the bin index
n: the total number of bins
l: the lower edge of the bin
h: the upper edge of the bin
r: the bin representative value
w: the original weight

Max and min functions

double get_max_wgt() const¶: Get maximum weight.

size_t get_max_index() const¶: Get the bin index of the maximum weight.

double get_max_rep()¶: Get the representative for the bin with maximum weight.

double get_min_wgt() const¶: Get minimum weight.

size_t get_min_index() const¶: Get the bin index of the minimum weight.

double get_min_rep()¶: Get the representative for the bin with minimum weight.

Delete functions

void clear_wgts()¶: Clear the data, but leave the bins as is.

void clear()¶: Clear the entire histogram.

Representative functions

template<class vec_t> inline void set_reps(size_t n, const vec_t &v)¶: Set the representative x-values for each bin.

void set_rep_mode(size_t mode)¶

Set mode used to compute bin representatives.

Acceptable inputs are rmode_avg, rmode_low, rmode_high, and rmode_gmean .

inline size_t get_rep_mode() const¶: Get mode used to compute bin representatives.

double get_rep_i(size_t i)¶

Return the representative 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.

inline double get_rep(double x)¶: Return the representative of bin containing x.

template<class resize_vec_t> inline void create_rep_vec(resize_vec_t &v)¶: Create a vector filled with the representatives for each bin.

Evaluation and interpolation functions

double operator()(double x)¶: Return the value of the function at x.

double interp(double x)¶: Return the value of the function at x.

double deriv(double x)¶: Return the derivative of the function at x.

double deriv2(double x)¶: Return the second derivative of the function at x.

double integ(double x, double y)¶: Return the integral of the function between x and y.

void set_interp_type(size_t interp_type)¶: Set the interpolation type.

inline size_t get_interp_type() const¶: Get the interpolation type.

Other functions

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

double integ_wgts()¶

Return the integral under the histogram.

This function returns

\[ \sum_{i=0}^{N-1} w_i ( \mathrm{high}_i - \mathrm{low}_i) \, . \]

where \( N \) is the size of the histogram.

template<class vec_t> inline void copy_reps(vec_t &v)¶: This function copies all bin representative values to the vector v, presuming that it has already been allocated.

void swap_reps(ubvector &v)¶

Get the representative values for the bins and store them in vector v using std::swap .

This function resizes the vector v if necessary.

void normalize(double new_sum = 1.0)¶

Renormalize the weights to fix the integral.

This computes the integral using integ() and so the action of this function depends on the interpolation type. If the histogram is empty, an exception is thrown.

Todo:: Create a version which uses integ_wgts() instead of integ().

void is_valid() const¶

Internal consistency check.

This function principally checks that the sizes of the internal vectors match up.

void copy_to_table(table<> &t, std::string reps, std::string lower_edges, std::string upper_edges, std::string weights)¶

Copy histogram data to a table.

First, if the table t has less rows than the histogram has bins, then new rows are added to the table and values in the new rows of the current columns are set to zero. Second, this creates new columns in the table named reps, lower_edges, upper_edges, and weights . Finally, the histogram data is copied to the four new columns.

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

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

Public Types

typedef boost::numeric::ublas::vector<double> ubvector¶

Public Functions

hist()¶: Create an empty histogram.

~hist()¶

hist(const hist &h)¶: Copy constructor.

hist &operator=(const hist &h)¶: Copy constructor.

template<class vec_t> inline hist(size_t nv, const vec_t &v, size_t n_bins)¶

Create a histogram from the first nv entries in a vector of data.

This function creates a histogram with n_bins equally spaced bins from the minimum element to the maximum element in v . The values of extend_lhs and extend_rhs are set to true, so the first and last bin are guaranteed to be at least 1.

template<class vec_t, class vec2_t> inline hist(size_t nv, const vec_t &v, const vec2_t &w, size_t n_bins)¶

Create a histogram from the first nv entries in a vector of data and a vector of weights.

template<class vec_t> inline hist(const vec_t &v, size_t n_bins)¶

Create a histogram from a vector of data.

template<class vec_t, class vec2_t> inline hist(const vec_t &v, const vec2_t &w, size_t n_bins)¶

Create a histogram from a vector of data and a vector of weights.

inline void from_table(o2scl::table<> &t, std::string colx, size_t n_bins)¶: Create a histogram from a column in a o2scl::table object.

inline void from_table(o2scl::table<> &t, std::string colx, std::string coly, size_t n_bins)¶: Create a histogram from a column of data and a column of weights in a o2scl::table object.

inline size_t size() const¶

The histogram size.

This is the number of bins and one less than the number of bin edges. If the size is zero, then the histogram is empty.

Public Members

bool extend_rhs¶

If true, allow abcissae beyond the last bin (default false)

If this is true, the histogram will allow data with corresponding to bins larger than the largest bin (for increasing bin edges) or smaller than the smallest bin (for decreasing bin edges).

bool extend_lhs¶: If true, allow abcissae before the first bin (default false)

Protected Types

typedef interp_vec<ubvector> interp_t¶: Interpolation typedef.

Protected Functions

void set_reps_auto()¶: Set the representative array according to current rmode (if not in user rep mode)

void allocate(size_t n)¶

Allocate vectors for a histogram of size n.

This function also sets all the weights to zero.

Protected Attributes

ubvector ubin¶: Bin locations (N+1)

ubvector uwgt¶: Bin contents (N)

ubvector urep¶: Bin representative values (N)

ubvector user_rep¶: User-defined representative values (N)

size_t hsize¶: Number of bins.

size_t rmode¶: Representative mode.

size_t itype¶: Interpolation type.