ROOT::Experimental::RHistEngine< BinContentType > Class Template Reference

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

A histogram data structure to bin data along multiple dimensions.

Every call to Fill bins the data according to the axis configuration and increments the bin content:

ROOT::Experimental::RHistEngine<int> hist(10, 5, 15);
hist.Fill(8.5);
// hist.GetBinContent(ROOT::Experimental::RBinIndex(3)) will return 1

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 significant 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}));
ROOT::Experimental::RHistEngine<int> hist(axes);
// hist.GetNDimensions() will return 2

Warning

This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback is welcome!

Definition at line 60 of file RHistEngine.hxx.

Public Member Functions
	RHistEngine (const RHistEngine< BinContentType > &)=delete
	The copy constructor is deleted.
	RHistEngine (RHistEngine< BinContentType > &&)=default
	Efficiently move construct a histogram engine.
	RHistEngine (std::size_t nNormalBins, double low, double high)
	Construct a one-dimensional histogram engine with a regular axis.
	RHistEngine (std::vector< RAxisVariant > axes)
	Construct a histogram engine.
	~RHistEngine ()=default
void	Add (const RHistEngine< BinContentType > &other)
	Add all bin contents of another histogram.
void	Clear ()
	Clear all bin contents.
RHistEngine< BinContentType >	Clone () const
	Clone this histogram engine.
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 BinContentType &	GetBinContent (const A &...args) const
	Get the content of a single bin.
template<std::size_t N>
const BinContentType &	GetBinContent (const std::array< RBinIndex, N > &indices) const
	Get the content of a single bin.
std::size_t	GetNDimensions () const
std::size_t	GetTotalNBins () const
RHistEngine< BinContentType > &	operator= (const RHistEngine< BinContentType > &)=delete
	The copy assignment operator is deleted.
RHistEngine< BinContentType > &	operator= (RHistEngine< BinContentType > &&)=default
	Efficiently move a histogram engine.
void	Streamer (TBuffer &)
	ROOT Streamer function to throw when trying to store an object of this class.

Static Public Attributes
static constexpr bool	SupportsWeightedFilling
	Whether this histogram engine type supports weighted filling.

Private Attributes
Internal::RAxes	fAxes
	The axis configuration for this histogram. Relevant methods are forwarded from the public interface.
std::vector< BinContentType >	fBinContents
	The bin contents for this histogram.

#include <ROOT/RHistEngine.hxx>

Constructor & Destructor Documentation

RHistEngine() [1/4]

template<typename BinContentType >

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

inlineexplicit

Construct a histogram engine.

Parameters

[in]

axes

the axis objects, must have size > 0

Definition at line 70 of file RHistEngine.hxx.

RHistEngine() [2/4]

template<typename BinContentType >

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

inline

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

Parameters

[in]	nNormalBins	the number of normal bins, must be > 0
[in]	low	the lower end of the axis interval (inclusive)
[in]	high	the upper end of the axis interval (exclusive), must be > low

See also

the constructor of RRegularAxis

Definition at line 83 of file RHistEngine.hxx.

RHistEngine() [3/4]

template<typename BinContentType >

ROOT::Experimental::RHistEngine< BinContentType >::RHistEngine ( const RHistEngine< BinContentType > & )

delete

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

RHistEngine() [4/4]

template<typename BinContentType >

ROOT::Experimental::RHistEngine< BinContentType >::RHistEngine ( RHistEngine< BinContentType > && )

default

Efficiently move construct a histogram engine.

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

~RHistEngine()

template<typename BinContentType >

ROOT::Experimental::RHistEngine< BinContentType >::~RHistEngine ( )

default

Member Function Documentation

Add()

template<typename BinContentType >

void ROOT::Experimental::RHistEngine< BinContentType >::Add ( const RHistEngine< BinContentType > & other )

inline

Add all bin contents of another histogram.

Throws an exception if the axes configurations are not identical.

Parameters

[in]

other

another histogram

Definition at line 178 of file RHistEngine.hxx.

Clear()

template<typename BinContentType >

void ROOT::Experimental::RHistEngine< BinContentType >::Clear ( )

inline

Clear all bin contents.

Definition at line 189 of file RHistEngine.hxx.

Clone()

template<typename BinContentType >

RHistEngine< BinContentType > ROOT::Experimental::RHistEngine< BinContentType >::Clone ( ) const

inline

Clone this histogram engine.

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

Returns

the cloned object

Definition at line 201 of file RHistEngine.hxx.

Fill() [1/3]

template<typename BinContentType >

template<typename... A>

void ROOT::Experimental::RHistEngine< BinContentType >::Fill ( const A &... args )

inline

Fill an entry into the histogram.

ROOT::Experimental::RHistEngine<int> hist({/* two dimensions */});
hist.Fill(8.5, 10.5);

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

ROOT::Experimental::RHistEngine<float> hist({/* two dimensions */});
hist.Fill(8.5, 10.5, ROOT::Experimental::RWeight(0.8));

This is only available for floating-point bin content types (see 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]

args

the arguments for each axis

See also

the function overloads accepting std::tuple for unweighted filling and for weighted filling

Definition at line 307 of file RHistEngine.hxx.

Fill() [2/3]

template<typename BinContentType >

template<typename... A>

void ROOT::Experimental::RHistEngine< BinContentType >::Fill ( const std::tuple< A... > & args )

inline

Fill an entry into the histogram.

ROOT::Experimental::RHistEngine<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]

args

the arguments for each axis

See also

the variadic function template overload accepting arguments directly and the overload for weighted filling

Definition at line 232 of file RHistEngine.hxx.

Fill() [3/3]

template<typename BinContentType >

template<typename... A>

void ROOT::Experimental::RHistEngine< 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 SupportsWeightedFilling).

ROOT::Experimental::RHistEngine<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]	args	the arguments for each axis
[in]	weight	the weight for this entry

See also

the variadic function template overload accepting arguments directly and the overload for unweighted filling

Definition at line 267 of file RHistEngine.hxx.

GetAxes()

template<typename BinContentType >

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

inline

Definition at line 109 of file RHistEngine.hxx.

GetBinContent() [1/2]

template<typename BinContentType >

template<typename... A>

const BinContentType & ROOT::Experimental::RHistEngine< BinContentType >::GetBinContent ( const A &... args ) const

inline

Get the content of a single bin.

ROOT::Experimental::RHistEngine<int> hist({/* two dimensions */});
int content = hist.GetBinContent(ROOT::Experimental::RBinIndex(3), ROOT::Experimental::RBinIndex(5));
// ... or construct the RBinIndex arguments implicitly from integers:
content = hist.GetBinContent(3, 5);

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]

args

the arguments for each axis

Returns

the bin content

See also

the function overload accepting std::array

Definition at line 167 of file RHistEngine.hxx.

GetBinContent() [2/2]

template<typename BinContentType >

template<std::size_t N>

const BinContentType & ROOT::Experimental::RHistEngine< BinContentType >::GetBinContent ( const std::array< RBinIndex, N > & indices ) const

inline

Get the content of a single bin.

ROOT::Experimental::RHistEngine<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]

indices

the array of indices for each axis

Returns

the bin content

See also

the variadic function template overload accepting arguments directly

Definition at line 132 of file RHistEngine.hxx.

GetNDimensions()

template<typename BinContentType >

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

inline

Definition at line 110 of file RHistEngine.hxx.

GetTotalNBins()

template<typename BinContentType >

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

inline

Definition at line 111 of file RHistEngine.hxx.

operator=() [1/2]

template<typename BinContentType >

RHistEngine< BinContentType > & ROOT::Experimental::RHistEngine< BinContentType >::operator= ( const RHistEngine< BinContentType > & )

delete

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]

template<typename BinContentType >

RHistEngine< BinContentType > & ROOT::Experimental::RHistEngine< BinContentType >::operator= ( RHistEngine< BinContentType > && )

default

Efficiently move a histogram engine.

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

Streamer()

template<typename BinContentType >

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

inline

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

Definition at line 329 of file RHistEngine.hxx.

Member Data Documentation

fAxes

template<typename BinContentType >

Internal::RAxes ROOT::Experimental::RHistEngine< BinContentType >::fAxes

private

The axis configuration for this histogram. Relevant methods are forwarded from the public interface.

Definition at line 62 of file RHistEngine.hxx.

fBinContents

template<typename BinContentType >

std::vector<BinContentType> ROOT::Experimental::RHistEngine< BinContentType >::fBinContents

private

The bin contents for this histogram.

Definition at line 64 of file RHistEngine.hxx.

SupportsWeightedFilling

template<typename BinContentType >

constexpr bool ROOT::Experimental::RHistEngine< BinContentType >::SupportsWeightedFilling

staticconstexpr

Initial value:

=
      std::is_floating_point_v<BinContentType> || std::is_same_v<BinContentType, RBinWithError>

Whether this histogram engine type supports weighted filling.

Definition at line 211 of file RHistEngine.hxx.