Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
ROOT::Experimental::RHist< BinContentType > Class Template Referencefinal

template<typename BinContentType>
class ROOT::Experimental::RHist< BinContentType >

A histogram for aggregation of data along multiple dimensions.

Every call to Fill increments the bin content and is reflected in global statistics:

hist.Fill(8.5);
// hist.GetBinContent(ROOT::Experimental::RBinIndex(3)) will return 1
A histogram for aggregation of data along multiple dimensions.
Definition RHist.hxx:55

The class is templated on the bin content type. For counting, as in the example above, it may be an integer type such as int or long. Narrower types such as unsigned char or short are supported, but may overflow due to their limited range and must be used with care. For weighted filling, the bin content type must be a floating-point type such as float or double, or the special type RBinWithError. Note that float has a limited significand precision of 24 bits.

An object can have arbitrary dimensionality determined at run-time. The axis configuration is passed as a vector of RAxisVariant:

std::vector<ROOT::Experimental::RAxisVariant> axes;
axes.push_back(ROOT::Experimental::RRegularAxis(10, 5, 15));
axes.push_back(ROOT::Experimental::RVariableBinAxis({1, 10, 100, 1000}));
// hist.GetNDimensions() will return 2
A regular axis with equidistant bins in the interval .
An axis with variable bins defined by their edges.
Warning
This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback is welcome!

Definition at line 55 of file RHist.hxx.

Public Member Functions

 RHist (const RHist< BinContentType > &)=delete
 The copy constructor is deleted.
 
 RHist (RHist< BinContentType > &&)=default
 Efficiently move construct a histogram.
 
 RHist (std::size_t nNormalBins, double low, double high)
 Construct a one-dimensional histogram engine with a regular axis.
 
 RHist (std::vector< RAxisVariant > axes)
 Construct a histogram.
 
 ~RHist ()=default
 
void Add (const RHist< BinContentType > &other)
 Add all bin contents and statistics of another histogram.
 
void Clear ()
 Clear all bin contents and statistics.
 
RHist< BinContentTypeClone () const
 Clone this histogram.
 
double ComputeMean (std::size_t dim=0) const
 Compute the arithmetic mean of unbinned values.
 
double ComputeNEffectiveEntries () const
 Compute the number of effective entries.
 
double ComputeStdDev (std::size_t dim=0) const
 Compute the standard deviation of unbinned values.
 
template<typename... A>
void Fill (const A &...args)
 Fill an entry into the histogram.
 
template<typename... A>
void Fill (const std::tuple< A... > &args)
 Fill an entry into the histogram.
 
template<typename... A>
void Fill (const std::tuple< A... > &args, RWeight weight)
 Fill an entry into the histogram with a weight.
 
const std::vector< RAxisVariant > & GetAxes () const
 
template<typename... A>
const BinContentTypeGetBinContent (const A &...args) const
 Get the content of a single bin.
 
template<std::size_t N>
const BinContentTypeGetBinContent (const std::array< RBinIndex, N > &indices) const
 Get the content of a single bin.
 
const RHistEngine< BinContentType > & GetEngine () const
 
std::size_t GetNDimensions () const
 
std::uint64_t GetNEntries () const
 
const RHistStatsGetStats () const
 
std::size_t GetTotalNBins () const
 
RHist< BinContentType > & operator= (const RHist< BinContentType > &)=delete
 The copy assignment operator is deleted.
 
RHist< BinContentType > & operator= (RHist< BinContentType > &&)=default
 Efficiently move a histogram.
 
void Streamer (TBuffer &)
 ROOT Streamer function to throw when trying to store an object of this class.
 

Private Member Functions

 RHist (RHistEngine< BinContentType > engine)
 Private constructor based off an engine.
 

Private Attributes

RHistEngine< BinContentTypefEngine
 The histogram engine including the bin contents.
 
RHistStats fStats
 The global histogram statistics.
 

#include <ROOT/RHist.hxx>

Constructor & Destructor Documentation

◆ RHist() [1/5]

Private constructor based off an engine.

Definition at line 62 of file RHist.hxx.

◆ RHist() [2/5]

ROOT::Experimental::RHist< BinContentType >::RHist ( std::vector< RAxisVariant > axes)
inlineexplicit

Construct a histogram.

Parameters
[in]axesthe axis objects, must have size > 0

Definition at line 68 of file RHist.hxx.

◆ RHist() [3/5]

ROOT::Experimental::RHist< BinContentType >::RHist ( std::size_t nNormalBins,
double low,
double high )
inline

Construct a one-dimensional histogram engine with a regular axis.

Parameters
[in]nNormalBinsthe number of normal bins, must be > 0
[in]lowthe lower end of the axis interval (inclusive)
[in]highthe upper end of the axis interval (exclusive), must be > low
See also
the constructor of RRegularAxis

Definition at line 78 of file RHist.hxx.

◆ RHist() [4/5]

The copy constructor is deleted.

Copying all bin contents can be an expensive operation, depending on the number of bins. If required, users can explicitly call Clone().

◆ RHist() [5/5]

Efficiently move construct a histogram.

After this operation, the moved-from object is invalid.

◆ ~RHist()

Member Function Documentation

◆ Add()

Add all bin contents and statistics of another histogram.

Throws an exception if the axes configurations are not identical.

Parameters
[in]otheranother histogram

Definition at line 171 of file RHist.hxx.

◆ Clear()

void ROOT::Experimental::RHist< BinContentType >::Clear ( )
inline

Clear all bin contents and statistics.

Definition at line 178 of file RHist.hxx.

◆ Clone()

Clone this histogram.

Copying all bin contents can be an expensive operation, depending on the number of bins.

Returns
the cloned object

Definition at line 189 of file RHist.hxx.

◆ ComputeMean()

double ROOT::Experimental::RHist< BinContentType >::ComputeMean ( std::size_t dim = 0) const
inline

Compute the arithmetic mean of unbinned values.

\[ \mu = \frac{\sum w_i \cdot x_i}{\sum w_i} \]

Parameters
[in]dimthe dimension index, starting at 0
Returns
the arithmetic mean of unbinned values

Definition at line 113 of file RHist.hxx.

◆ ComputeNEffectiveEntries()

double ROOT::Experimental::RHist< BinContentType >::ComputeNEffectiveEntries ( ) const
inline

Compute the number of effective entries.

\[ \frac{(\sum w_i)^2}{\sum w_i^2} \]

Returns
the number of effective entries

Definition at line 111 of file RHist.hxx.

◆ ComputeStdDev()

double ROOT::Experimental::RHist< BinContentType >::ComputeStdDev ( std::size_t dim = 0) const
inline

Compute the standard deviation of unbinned values.

This function computes the uncorrected sample standard deviation:

\[ \sigma = \sqrt{\frac{1}{\sum w_i} \sum(w_i \cdot x_i - \mu)^2} \]

With some rewriting, this is equivalent to:

\[ \sigma = \sqrt{\frac{\sum w_i \cdot x_i^2}{\sum w_i} - \frac{(\sum w_i \cdot x_i)^2}{(\sum w_i)^2}} \]

This function does not include Bessel's correction needed for an unbiased estimator of population variance. In other words, the return value is a biased estimation lower than the actual population standard deviation.

Parameters
[in]dimthe dimension index, starting at 0
Returns
the standard deviation of unbinned values

Definition at line 115 of file RHist.hxx.

◆ Fill() [1/3]

template<typename... A>
void ROOT::Experimental::RHist< BinContentType >::Fill ( const A &... args)
inline

Fill an entry into the histogram.

ROOT::Experimental::RHist<int> hist({/* two dimensions */});
hist.Fill(8.5, 10.5);
void Fill(const std::tuple< A... > &args)
Fill an entry into the histogram.
Definition RHist.hxx:214

For weighted filling, pass an RWeight as the last argument:

ROOT::Experimental::RHist<float> hist({/* two dimensions */});
hist.Fill(8.5, 10.5, ROOT::Experimental::RWeight(0.8));
A weight for filling histograms.
Definition RWeight.hxx:17

This is only available for floating-point bin content types (see RHistEngine::SupportsWeightedFilling).

If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently discarded.

Throws an exception if the number of arguments does not match the axis configuration.

Parameters
[in]argsthe arguments for each axis
See also
the function overloads accepting std::tuple for unweighted filling and for weighted filling

Definition at line 272 of file RHist.hxx.

◆ Fill() [2/3]

template<typename... A>
void ROOT::Experimental::RHist< BinContentType >::Fill ( const std::tuple< A... > & args)
inline

Fill an entry into the histogram.

ROOT::Experimental::RHist<int> hist({/* two dimensions */});
auto args = std::make_tuple(8.5, 10.5);
hist.Fill(args);

If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently discarded.

Throws an exception if the number of arguments does not match the axis configuration.

Parameters
[in]argsthe arguments for each axis
See also
the variadic function template overload accepting arguments directly and the overload for weighted filling

Definition at line 214 of file RHist.hxx.

◆ Fill() [3/3]

template<typename... A>
void ROOT::Experimental::RHist< BinContentType >::Fill ( const std::tuple< A... > & args,
RWeight weight )
inline

Fill an entry into the histogram with a weight.

This overload is only available for floating-point bin content types (see RHistEngine::SupportsWeightedFilling).

ROOT::Experimental::RHist<float> hist({/* two dimensions */});
auto args = std::make_tuple(8.5, 10.5);
hist.Fill(args, ROOT::Experimental::RWeight(0.8));

If one of the arguments is outside the corresponding axis and flow bins are disabled, the entry will be silently discarded.

Throws an exception if the number of arguments does not match the axis configuration.

Parameters
[in]argsthe arguments for each axis
[in]weightthe weight for this entry
See also
the variadic function template overload accepting arguments directly and the overload for unweighted filling

Definition at line 242 of file RHist.hxx.

◆ GetAxes()

const std::vector< RAxisVariant > & ROOT::Experimental::RHist< BinContentType >::GetAxes ( ) const
inline

Definition at line 105 of file RHist.hxx.

◆ GetBinContent() [1/2]

template<typename... A>
const BinContentType & ROOT::Experimental::RHist< BinContentType >::GetBinContent ( const A &... args) const
inline

Get the content of a single bin.

ROOT::Experimental::RHist<int> hist({/* two dimensions */});
// ... or construct the RBinIndex arguments implicitly from integers:
content = hist.GetBinContent(3, 5);
A bin index with special values for underflow and overflow bins.
Definition RBinIndex.hxx:22
Note
Compared to TH1 conventions, the first normal bin has index 0 and underflow and overflow bins are special values. See also the class documentation of RBinIndex.

Throws an exception if the number of arguments does not match the axis configuration or the bin is not found.

Parameters
[in]argsthe arguments for each axis
Returns
the bin content
See also
the function overload accepting std::array

Definition at line 161 of file RHist.hxx.

◆ GetBinContent() [2/2]

template<std::size_t N>
const BinContentType & ROOT::Experimental::RHist< BinContentType >::GetBinContent ( const std::array< RBinIndex, N > & indices) const
inline

Get the content of a single bin.

ROOT::Experimental::RHist<int> hist({/* two dimensions */});
std::array<ROOT::Experimental::RBinIndex, 2> indices = {3, 5};
int content = hist.GetBinContent(indices);
Note
Compared to TH1 conventions, the first normal bin has index 0 and underflow and overflow bins are special values. See also the class documentation of RBinIndex.

Throws an exception if the number of indices does not match the axis configuration or the bin is not found.

Parameters
[in]indicesthe array of indices for each axis
Returns
the bin content
See also
the variadic function template overload accepting arguments directly

Definition at line 136 of file RHist.hxx.

◆ GetEngine()

Definition at line 102 of file RHist.hxx.

◆ GetNDimensions()

std::size_t ROOT::Experimental::RHist< BinContentType >::GetNDimensions ( ) const
inline

Definition at line 106 of file RHist.hxx.

◆ GetNEntries()

std::uint64_t ROOT::Experimental::RHist< BinContentType >::GetNEntries ( ) const
inline

Definition at line 109 of file RHist.hxx.

◆ GetStats()

Definition at line 103 of file RHist.hxx.

◆ GetTotalNBins()

std::size_t ROOT::Experimental::RHist< BinContentType >::GetTotalNBins ( ) const
inline

Definition at line 107 of file RHist.hxx.

◆ operator=() [1/2]

The copy assignment operator is deleted.

Copying all bin contents can be an expensive operation, depending on the number of bins. If required, users can explicitly call Clone().

◆ operator=() [2/2]

Efficiently move a histogram.

After this operation, the moved-from object is invalid.

◆ Streamer()

void ROOT::Experimental::RHist< BinContentType >::Streamer ( TBuffer & )
inline

ROOT Streamer function to throw when trying to store an object of this class.

Definition at line 279 of file RHist.hxx.

Member Data Documentation

◆ fEngine

The histogram engine including the bin contents.

Definition at line 57 of file RHist.hxx.

◆ fStats

The global histogram statistics.

Definition at line 59 of file RHist.hxx.

  • hist/histv7/inc/ROOT/RHist.hxx