All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Private Attributes | List of all members
util::Binner< T > Class Template Reference

Helper class binning values in a range. More...

#include <Binner.h>

Public Types

using Data_t = T
 Type of values on the binning axis. More...
 
using Step_t = decltype(std::declval< Data_t >()-std::declval< Data_t >())
 Type of difference between binning axis values. More...
 

Public Member Functions

 Binner (Data_t lower, Data_t upper, Step_t step)
 Constructor: covers the range from lower to upper or above. More...
 
Access

Returns the lower limit of the range.

Data_t lower () const
 
Data_t upper () const
 Returns the upper limit of the range. More...
 
Step_t step () const
 Returns the step size. More...
 
unsigned int nBins () const
 Returns the number of bins in the range. More...
 
Bin index queries

Type of supported queries:

  • whether a value is within the range: contains()
  • bin "index" for a value:
    • fractional value (relative()): a value in the middle of the bin will have a index with fractional part 0.5;
    • integral value, with different treatment for overflows:
      • bin() (also operator()): no range check at all, index can be any integral value
      • cappedBin(): if the bin index is smaller, or larger, than the specified minimum and maximum bin numbers, the returned value is clamped to those minimum and maximum bin numbers;
      • cappedBin(): the bin index is between 0 and nBins() - 1, where bin 0 also includes all values smaller than lower() and bin nBins() - 1 includes all values larger or equal to upper()
      • cappedBinWithOverflows(): the bin index is between -1 and nBins(), where bin -1 includes all values smaller than lower() and bin nBins() includes all values larger or equal to upper()
double relative (Data_t value) const
 Returns value relative to the range (lower = 0, upper = 1). More...
 
int bin (Data_t value) const
 Returns bin number for value (unbound). More...
 
int operator() (Data_t value) const
 
int cappedBin (Data_t value, int min, int max) const
 Returns a bin number for value clamped between min and max included. More...
 
int cappedBin (Data_t value) const
 Returns a valid bin index, capping if value is out of range. More...
 
int cappedBinWithOverflows (Data_t value) const
 Returns a valid bin index or -1 for underflow or nBins() for overflow. More...
 
Range queries
bool contains (Data_t value) const
 Returns if value is in the range. More...
 
Data_t lowerEdge (int iBin) const
 Returns the lower edge of the bin with the specified index iBin. More...
 
Data_t upperEdge (int iBin) const
 Returns the upper edge of the bin with the specified index iBin. More...
 
Data_t binCenter (int iBin) const
 Returns the center of the bin with the specified index iBin. More...
 

Private Attributes

Data_t fLower
 Lower bound of the covered range. More...
 
Step_t fStep
 Width of the bins. More...
 
unsigned int fNBins
 Number of bins in the range. More...
 
Data_t fUpper
 Upper bound of the covered range. More...
 

Detailed Description

template<typename T>
class util::Binner< T >

Helper class binning values in a range.

Template Parameters
Ttype of data on the axis

This object provides binning and indexing of a range of values from lower() to upper(). The range is divided in nBins() bins all of the same size step().

The type of the values is T; the type of step() may be T or something else, automatically detected.

Example of usage:

util::Binner<float> const bins(-1.0f, +1.0f, 0.1f);
std::cout << "Binning: " << bins << std::endl; // print binning on screen
// print the bin index for some known values
std::cout << "\nBin indices (no range constraint):";
for (float const value: { -1.5f, -1.0f, -0.5f, 0.0f, +0.5f, +1.0f, +1.5f })
std::cout << " - bin index for " << value << ": " << bins(value) << std::endl;
std::cout << std::flush;
// print the bin index for some known values
std::cout << "\nBin relative indices (no range constraint):";
for (float const value: { -1.5f, -1.0f, -0.5f, 0.0f, +0.5f, +1.0f, +1.5f })
std::cout << "\n - " << value << " => [" << bins.relative(value) << "]";
std::cout << std::flush;
// print the capped bin index for some known values
std::cout << "\nBin indices (capped):";
for (float const value: { -1.5f, -1.0f, -0.5f, 0.0f, +0.5f, +1.0f, +1.5f }) {
std::cout << "\n - " << value << " => [" << bins.cappedBin(value) << "]";
std::cout << std::flush;

Note that the upper bound of each bin does not belong to that bin, but rather to the next one (and, differently from ROOT, this also holds for the last bin, i.e. the upper() value).

Definition at line 24 of file Binner.h.

Member Typedef Documentation

template<typename T>
using util::Binner< T >::Data_t = T

Type of values on the binning axis.

Definition at line 75 of file Binner.h.

template<typename T>
using util::Binner< T >::Step_t = decltype(std::declval<Data_t>() - std::declval<Data_t>())

Type of difference between binning axis values.

Definition at line 78 of file Binner.h.

Constructor & Destructor Documentation

template<typename T >
util::Binner< T >::Binner ( Data_t  lower,
Data_t  upper,
Step_t  step 
)

Constructor: covers the range from lower to upper or above.

Parameters
lowerlower bound of the binning range (used exact)
upperupper bound of the binning range (see description)
stepbin width (used exact)

The binning range is defined to include an integral number of bins all with width step, starting exactly at lower value. The bins are enough that the last one includes or touches the upper value. In other words the number of bins is set by the formula $ \lceil (upper - lower) / step \rceil $, and the actual upper() value is computed accordingly, to accommodate that many bins.

Definition at line 208 of file Binner.h.

209  : fLower(lower)
210  , fStep(step)
211  , fNBins(static_cast<unsigned int>(std::ceil((upper - lower) / step)))
212  , fUpper(lowerEdge(fNBins))
213  { assert(lower <= upper); }
util::Binner::fStep
Step_t fStep
Width of the bins.
Definition: Binner.h:197
util::Binner::lowerEdge
Data_t lowerEdge(int iBin) const
Returns the lower edge of the bin with the specified index iBin.
Definition: Binner.h:183
util::Binner::fUpper
Data_t fUpper
Upper bound of the covered range.
Definition: Binner.h:199
util::Binner::fLower
Data_t fLower
Lower bound of the covered range.
Definition: Binner.h:196
util::Binner::fNBins
unsigned int fNBins
Number of bins in the range.
Definition: Binner.h:198
util::Binner::upper
Data_t upper() const
Returns the upper limit of the range.
Definition: Binner.h:104
util::Binner::step
Step_t step() const
Returns the step size.
Definition: Binner.h:107
util::Binner::lower
Data_t lower() const
Definition: Binner.h:101

Member Function Documentation

template<typename T>
int util::Binner< T >::bin ( Data_t  value) const
inline

Returns bin number for value (unbound).

Definition at line 148 of file Binner.h.

149  { return static_cast<int>(std::floor(relative(value))); }
util::Binner::relative
double relative(Data_t value) const
Returns value relative to the range (lower = 0, upper = 1).
Definition: Binner.h:143
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
template<typename T>
Data_t util::Binner< T >::binCenter ( int  iBin) const
inline

Returns the center of the bin with the specified index iBin.

Definition at line 189 of file Binner.h.

189 { return lowerEdge(iBin) + fStep / 2; }
util::Binner::fStep
Step_t fStep
Width of the bins.
Definition: Binner.h:197
util::Binner::lowerEdge
Data_t lowerEdge(int iBin) const
Returns the lower edge of the bin with the specified index iBin.
Definition: Binner.h:183
template<typename T>
int util::Binner< T >::cappedBin ( Data_t  value,
int  min,
int  max 
) const
inline

Returns a bin number for value clamped between min and max included.

Definition at line 155 of file Binner.h.

156  { return std::clamp(bin(value), min, max); }
util::Binner::bin
int bin(Data_t value) const
Returns bin number for value (unbound).
Definition: Binner.h:148
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
template<typename T>
int util::Binner< T >::cappedBin ( Data_t  value) const
inline

Returns a valid bin index, capping if value is out of range.

Definition at line 161 of file Binner.h.

161 { return cappedBin(value, 0, nBins() - 1); }
util::Binner::cappedBin
int cappedBin(Data_t value, int min, int max) const
Returns a bin number for value clamped between min and max included.
Definition: Binner.h:155
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
util::Binner::nBins
unsigned int nBins() const
Returns the number of bins in the range.
Definition: Binner.h:110
template<typename T>
int util::Binner< T >::cappedBinWithOverflows ( Data_t  value) const
inline

Returns a valid bin index or -1 for underflow or nBins() for overflow.

Definition at line 166 of file Binner.h.

167  { return cappedBin(value, -1, nBins()); }
util::Binner::cappedBin
int cappedBin(Data_t value, int min, int max) const
Returns a bin number for value clamped between min and max included.
Definition: Binner.h:155
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
util::Binner::nBins
unsigned int nBins() const
Returns the number of bins in the range.
Definition: Binner.h:110
template<typename T>
bool util::Binner< T >::contains ( Data_t  value) const
inline

Returns if value is in the range.

Definition at line 179 of file Binner.h.

180  { return (value >= fLower) && (value < fUpper); }
util::Binner::fUpper
Data_t fUpper
Upper bound of the covered range.
Definition: Binner.h:199
util::Binner::fLower
Data_t fLower
Lower bound of the covered range.
Definition: Binner.h:196
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
template<typename T>
Data_t util::Binner< T >::lower ( ) const
inline

Definition at line 101 of file Binner.h.

101 { return fLower; }
util::Binner::fLower
Data_t fLower
Lower bound of the covered range.
Definition: Binner.h:196
template<typename T>
Data_t util::Binner< T >::lowerEdge ( int  iBin) const
inline

Returns the lower edge of the bin with the specified index iBin.

Definition at line 183 of file Binner.h.

183 { return fLower + fStep * iBin; }
util::Binner::fStep
Step_t fStep
Width of the bins.
Definition: Binner.h:197
util::Binner::fLower
Data_t fLower
Lower bound of the covered range.
Definition: Binner.h:196
template<typename T>
unsigned int util::Binner< T >::nBins ( ) const
inline

Returns the number of bins in the range.

Definition at line 110 of file Binner.h.

110 { return fNBins; }
util::Binner::fNBins
unsigned int fNBins
Number of bins in the range.
Definition: Binner.h:198
template<typename T>
int util::Binner< T >::operator() ( Data_t  value) const
inline

Definition at line 150 of file Binner.h.

150 { return bin(value); }
util::Binner::bin
int bin(Data_t value) const
Returns bin number for value (unbound).
Definition: Binner.h:148
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
template<typename T>
double util::Binner< T >::relative ( Data_t  value) const
inline

Returns value relative to the range (lower = 0, upper = 1).

Definition at line 143 of file Binner.h.

143 { return (value - fLower) / fStep; }
util::Binner::fStep
Step_t fStep
Width of the bins.
Definition: Binner.h:197
util::Binner::fLower
Data_t fLower
Lower bound of the covered range.
Definition: Binner.h:196
value
temporary value
Definition: pmtsimulation_icarus.fcl:216
template<typename T>
Step_t util::Binner< T >::step ( ) const
inline

Returns the step size.

Definition at line 107 of file Binner.h.

107 { return fStep; }
util::Binner::fStep
Step_t fStep
Width of the bins.
Definition: Binner.h:197
template<typename T>
Data_t util::Binner< T >::upper ( ) const
inline

Returns the upper limit of the range.

Definition at line 104 of file Binner.h.

104 { return fUpper; }
util::Binner::fUpper
Data_t fUpper
Upper bound of the covered range.
Definition: Binner.h:199
template<typename T>
Data_t util::Binner< T >::upperEdge ( int  iBin) const
inline

Returns the upper edge of the bin with the specified index iBin.

Definition at line 186 of file Binner.h.

186 { return lowerEdge(iBin + 1); }
util::Binner::lowerEdge
Data_t lowerEdge(int iBin) const
Returns the lower edge of the bin with the specified index iBin.
Definition: Binner.h:183

Member Data Documentation

template<typename T>
Data_t util::Binner< T >::fLower
private

Lower bound of the covered range.

Definition at line 196 of file Binner.h.

template<typename T>
unsigned int util::Binner< T >::fNBins
private

Number of bins in the range.

Definition at line 198 of file Binner.h.

template<typename T>
Step_t util::Binner< T >::fStep
private

Width of the bins.

Definition at line 197 of file Binner.h.

template<typename T>
Data_t util::Binner< T >::fUpper
private

Upper bound of the covered range.

Definition at line 199 of file Binner.h.

The documentation for this class was generated from the following file:
Generated by   doxygen 1.8.5