Public Types | Public Member Functions | Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | Friends | List of all members
o2scl::hist Class Reference

A one-dimensional histogram class. More...

#include <hist.h>

Public Types

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

Public Member Functions

 hist ()
 Create an empty histogram.
 
 hist (const hist &h)
 Copy constructor.
 
histoperator= (const hist &h)
 Copy constructor.
 
template<class vec_t >
 hist (size_t nv, const vec_t &v, size_t n_bins)
 Create from a vectors of data.
 
template<class vec_t , class vec2_t >
 hist (size_t nv, const vec_t &v, const vec2_t &v2, size_t n_bins)
 Create from a vectors of data.
 
template<class vec_t >
 hist (const vec_t &v, size_t n_bins)
 Create from vectors of data.
 
template<class vec_t , class vec2_t >
 hist (const vec_t &v, const vec2_t &v2, size_t n_bins)
 Create from vectors of data.
 
void from_table (o2scl::table<> &t, std::string colx, size_t n_bins)
 
void from_table (o2scl::table<> &t, std::string colx, std::string coly, size_t n_bins)
 
size_t size () const
 The histogram size.
 
Initial bin setup
void set_bin_edges (uniform_grid< double > g)
 Set bins from a uniform_grid object. More...
 
template<class vec_t >
void set_bin_edges (size_t n, const vec_t &v)
 Set the bins from a vector. More...
 
Weight functions
void update (double x, double val=1.0)
 Increment bin for x by value val.
 
void update_i (size_t i, double val=1.0)
 Increment bin with index i by value val.
 
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.
 
const double & get_wgt (double x) const
 Return contents of bin for x.
 
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.
 
void set_wgt (double x, double val)
 Set contents of bin for x to value val.
 
const ubvectorget_wgts () const
 Get a reference to the full y vector.
 
const double & operator[] (size_t i) const
 Get a reference to the weight for the bin at index i.
 
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. More...
 
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.
 
double & get_bin_low (double x)
 Get the lower edge of bin of index i.
 
const double & get_bin_low (double x) const
 Get the lower edge of bin of index i.
 
double & get_bin_high (double x)
 Get the upper edge of bin of index i.
 
const double & get_bin_high (double x) const
 Get the upper edge of bin of index i.
 
const ubvectorget_bins () const
 Get a reference to the full vector of bin specifications.
 
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 >
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. More...
 
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. More...
 
double get_rep (double x)
 Return the representative of bin containing x.
 
template<class resize_vec_t >
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.
 
Other functions
double sum_wgts ()
 Return the sum of all of the weights.
 
double integ_wgts ()
 Return the integral under the histogram. More...
 
template<class vec_t >
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 . More...
 
void normalize (double new_sum)
 Renormalize the weights to fix the integral. More...
 
void is_valid () const
 Internal consistency check.
 
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. More...
 

Public Attributes

bool extend_rhs
 If true, allow abcissae beyond the last bin (default false) More...
 
bool extend_lhs
 If true, allow abcissae before the first bin (default false)
 

Static Public Attributes

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.
 

Protected Types

typedef interp_vec< ubvectorinterp_t
 Interpolation typedef.
 

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

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.
 

Friends

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

Detailed Description

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.

To save space, representative vectors are not allocated until they are used.

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


Todo:

Check implementation of hist::extend_lhs.

More testing.

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

Definition at line 113 of file hist.h.

Member Function Documentation

◆ allocate()

void o2scl::hist::allocate ( size_t  n)
protected

This function also sets all the weights to zero.

◆ copy_to_table()

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

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.

◆ get_bin_index()

size_t o2scl::hist::get_bin_index ( double  x) const

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

◆ get_rep_i()

double o2scl::hist::get_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.

◆ integ_wgts()

double o2scl::hist::integ_wgts ( )

This function returns the sum of

\[ w_i ( \mathrm{high}_i - \mathrm{low}_i) \, . \]

◆ normalize()

void o2scl::hist::normalize ( double  new_sum)

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.

◆ set_bin_edges() [1/2]

void o2scl::hist::set_bin_edges ( uniform_grid< double >  g)

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

◆ set_bin_edges() [2/2]

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

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.

Definition at line 285 of file hist.h.

◆ set_rep_mode()

void o2scl::hist::set_rep_mode ( size_t  mode)

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

◆ swap_reps()

void o2scl::hist::swap_reps ( ubvector v)

This function resizes the vector v if necessary.

Member Data Documentation

◆ extend_rhs

bool o2scl::hist::extend_rhs

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

Definition at line 254 of file hist.h.


The documentation for this class was generated from the following file:

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).