A profile histogram, computing statistical quantities of an additional variable per bin.

Calling Fill requires an additional value:

ROOT::Experimental::RProfile profile(10, {5, 15});
profile.Fill(8.2, 23.0);
profile.Fill(8.7, 25.0);
// Bin 3 has a mean of 24.0 and a standard deviation of 1.0

The class is not templated, the bin content is always of type RProfileBin.

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::RProfile profile(axes);
// profile.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 58 of file RProfile.hxx.

Classes
struct	RProfileBin
	The bin content type of a profile histogram. More...

struct	RValueWeightWrapper

struct	RValueWrapper

Public Member Functions
template<typename... Axes>
	RProfile (const RAxisVariant &axis1, const Axes &...axes)
	Construct a profile histogram.

	RProfile (const RProfile &)=delete
	The copy constructor is deleted.

	RProfile (RProfile &&)=default
	Efficiently move construct a profile histogram.

	RProfile (std::initializer_list< RAxisVariant > axes)
	Construct a profile histogram.

	RProfile (std::uint64_t nNormalBins, std::pair< double, double > interval)
	Construct a one-dimensional profile histogram with a regular axis.

	RProfile (std::vector< RAxisVariant > axes)
	Construct a profile histogram.

	~RProfile ()=default

RProfile &	operator= (const RProfile &)=delete
	The copy assignment operator is deleted.

RProfile &	operator= (RProfile &&)=default
	Efficiently move a profile histogram.

void	Streamer (TBuffer &)
	ROOT Streamer function to throw when trying to store an object of this class.

Accessors
const RHistEngine< RProfileBin > &	GetEngine () const

const RHistStats &	GetStats () const

const std::vector< RAxisVariant > &	GetAxes () const

std::size_t	GetNDimensions () const

std::uint64_t	GetTotalNBins () const

std::uint64_t	GetNEntries () const

template<std::size_t N>
const RProfileBin &	GetBinContent (const std::array< RBinIndex, N > &indices) const
	Get the content of a single bin.

const RProfileBin &	GetBinContent (const std::vector< RBinIndex > &indices) const
	Get the content of a single bin.

template<typename... A>
const RProfileBin &	GetBinContent (const A &...args) const
	Get the content of a single bin.

RBinIndexMultiDimRange	GetFullMultiDimRange () const
	Get the multidimensional range of all bins.

template<std::size_t N, typename V >
void	SetBinContent (const std::array< RBinIndex, N > &indices, const V &value)
	Set the content of a single bin.

template<typename... A>
void	SetBinContent (const A &...args)
	Set the content of a single bin.

Computations
double	ComputeNEffectiveEntries () const
	Compute the number of effective entries.

double	ComputeMean (std::size_t dim=0) const
	Compute the arithmetic mean of unbinned values.

double	ComputeStdDev (std::size_t dim=0) const
	Compute the standard deviation of unbinned values.

Filling
template<typename... A, typename V >
void	Fill (const std::tuple< A... > &args, const V &value)
	Fill an entry into the profile histogram.

template<typename... A, typename V >
void	Fill (const std::tuple< A... > &args, const V &value, RWeight weight)
	Fill an entry into the profile histogram with a weight.

template<typename... A>
void	Fill (const A &...args)
	Fill an entry into the profile histogram.

Operations
void	Add (const RProfile &other)
	Add all bin contents and statistics of another profile histogram.

void	AddAtomic (const RProfile &other)
	Add all bin contents and statistics of another profile histogram using atomic instructions.

void	Clear ()
	Clear all bin contents and statistics.

RProfile	Clone () const
	Clone this profile histogram.

void	Scale (double factor)
	Scale all bin contents and statistics.

Private Member Functions
	RProfile (RHistEngine< RProfileBin > engine)
	Private constructor based off an engine.

Private Attributes
RHistEngine< RProfileBin >	fEngine
	The histogram engine including the bin contents.

RHistStats	fStats
	The global histogram statistics.

#include <ROOT/RProfile.hxx>

Constructor & Destructor Documentation

◆ RProfile() [1/7]

ROOT::Experimental::RProfile::RProfile ( RHistEngine< RProfileBin > engine )

inlineprivate

Private constructor based off an engine.

Definition at line 135 of file RProfile.hxx.

◆ RProfile() [2/7]

ROOT::Experimental::RProfile::RProfile ( std::vector< RAxisVariant > axes )

inlineexplicit

Construct a profile histogram.

Parameters

[in] axes the axis objects, must have size > 0

Definition at line 141 of file RProfile.hxx.

◆ RProfile() [3/7]

ROOT::Experimental::RProfile::RProfile ( std::initializer_list< RAxisVariant > axes )

inlineexplicit

Construct a profile histogram.

Note that there is no perfect forwarding of the axis objects. If that is needed, use the overload accepting a std::vector.

Parameters

[in] axes the axis objects, must have size > 0

Definition at line 158 of file RProfile.hxx.

◆ RProfile() [4/7]

template<typename... Axes>

ROOT::Experimental::RProfile::RProfile	(	const RAxisVariant &	axis1,
		const Axes &...	axes )

inlineexplicit

Construct a profile histogram.

Note that there is no perfect forwarding of the axis objects. If that is needed, use the overload accepting a std::vector.

Parameters

[in]	axis1	the first axis object
[in]	axes	the remaining axis objects

Definition at line 168 of file RProfile.hxx.

◆ RProfile() [5/7]

ROOT::Experimental::RProfile::RProfile	(	std::uint64_t	nNormalBins,
		std::pair< double, double >	interval )

inline

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

Parameters

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

See also: the constructor of RRegularAxis

Definition at line 180 of file RProfile.hxx.

◆ RProfile() [6/7]

ROOT::Experimental::RProfile::RProfile ( const RProfile & )

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

◆ RProfile() [7/7]

ROOT::Experimental::RProfile::RProfile ( RProfile && )

default

Efficiently move construct a profile histogram.

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

◆ ~RProfile()

ROOT::Experimental::RProfile::~RProfile ( )

default

Member Function Documentation

◆ Add()

void ROOT::Experimental::RProfile::Add ( const RProfile & other )

inline

Add all bin contents and statistics of another profile histogram.

Throws an exception if the axes configurations are not identical.

Parameters

[in] other another profile histogram

Definition at line 483 of file RProfile.hxx.

◆ AddAtomic()

void ROOT::Experimental::RProfile::AddAtomic ( const RProfile & other )

inline

Add all bin contents and statistics of another profile histogram using atomic instructions.

Throws an exception if the axes configurations are not identical.

Parameters

[in] other another profile histogram that must not be modified during the operation

Definition at line 494 of file RProfile.hxx.

◆ Clear()

void ROOT::Experimental::RProfile::Clear ( )

inline

Clear all bin contents and statistics.

Definition at line 501 of file RProfile.hxx.

◆ Clone()

RProfile ROOT::Experimental::RProfile::Clone ( ) const

inline

Clone this profile histogram.

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

Returns: the cloned object

Definition at line 512 of file RProfile.hxx.

◆ ComputeMean()

double ROOT::Experimental::RProfile::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] dim the dimension index, starting at 0

Returns: the arithmetic mean of unbinned values

Definition at line 226 of file RProfile.hxx.

◆ ComputeNEffectiveEntries()

double ROOT::Experimental::RProfile::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 224 of file RProfile.hxx.

◆ ComputeStdDev()

double ROOT::Experimental::RProfile::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] dim the dimension index, starting at 0

Returns: the standard deviation of unbinned values

Definition at line 228 of file RProfile.hxx.

◆ Fill() [1/3]

template<typename... A>

void ROOT::Experimental::RProfile::Fill ( const A &... args )

inline

Fill an entry into the profile histogram.

ROOT::Experimental::RProfile profile({/* two dimensions */});

profile.Fill(8.5, 10.5, 23.0);

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

profile.Fill(8.5, 10.5, 23.0, ROOT::Experimental::RWeight(0.8));

ROOT::Experimental::RWeight

A weight for filling histograms.

Definition RWeight.hxx:17

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, or if an argument cannot be converted for the axis type at run-time.

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 449 of file RProfile.hxx.

◆ Fill() [2/3]

template<typename... A, typename V >

void ROOT::Experimental::RProfile::Fill	(	const std::tuple< A... > &	args,
		const V &	value )

inline

Fill an entry into the profile histogram.

ROOT::Experimental::RProfile profile({/* two dimensions */});
auto args = std::make_tuple(8.5, 10.5);
profile.Fill(args, 23.0);

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, or if an argument cannot be converted for the axis type at run-time.

Parameters

[in]	args	the arguments for each axis
[in]	v	the additional argument

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

Definition at line 388 of file RProfile.hxx.

◆ Fill() [3/3]

template<typename... A, typename V >

void ROOT::Experimental::RProfile::Fill	(	const std::tuple< A... > &	args,
		const V &	value,
		RWeight	weight )

inline

Fill an entry into the profile histogram with a weight.

ROOT::Experimental::RProfile profile({/* two dimensions */});
auto args = std::make_tuple(8.5, 10.5);
profile.Fill(args, 23.0, 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, or if an argument cannot be converted for the axis type at run-time.

Parameters

[in]	args	the arguments for each axis
[in]	v	the additional argument
[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 417 of file RProfile.hxx.

◆ GetAxes()

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

inline

Definition at line 213 of file RProfile.hxx.

◆ GetBinContent() [1/3]

template<typename... A>

const RProfileBin & ROOT::Experimental::RProfile::GetBinContent ( const A &... args ) const

inline

Get the content of a single bin.

ROOT::Experimental::RProfile profile({/* two dimensions */});

const auto &content = profile.GetBinContent(3, 5);

ROOT::Detail::TRangeCast

Definition TCollection.h:312

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 overloads accepting `std::array` or `std::vector`

Definition at line 299 of file RProfile.hxx.

◆ GetBinContent() [2/3]

template<std::size_t N>

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

inline

Get the content of a single bin.

ROOT::Experimental::RProfile profile({/* two dimensions */});
std::array<ROOT::Experimental::RBinIndex, 2> indices = {3, 5};
const auto &content = profile.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 253 of file RProfile.hxx.

◆ GetBinContent() [3/3]

const RProfileBin & ROOT::Experimental::RProfile::GetBinContent ( const std::vector< RBinIndex > & indices ) const

inline

Get the content of a single bin.

ROOT::Experimental::RProfile profile({/* two dimensions */});
std::vector<ROOT::Experimental::RBinIndex> indices = {3, 5};
const auto &content = profile.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 276 of file RProfile.hxx.

◆ GetEngine()

const RHistEngine< RProfileBin > & ROOT::Experimental::RProfile::GetEngine ( ) const

inline

Definition at line 210 of file RProfile.hxx.

◆ GetFullMultiDimRange()

RBinIndexMultiDimRange ROOT::Experimental::RProfile::GetFullMultiDimRange ( ) const

inline

Get the multidimensional range of all bins.

Returns: the multidimensional range

Definition at line 307 of file RProfile.hxx.

◆ GetNDimensions()

std::size_t ROOT::Experimental::RProfile::GetNDimensions ( ) const

inline

Definition at line 214 of file RProfile.hxx.

◆ GetNEntries()

std::uint64_t ROOT::Experimental::RProfile::GetNEntries ( ) const

inline

Definition at line 217 of file RProfile.hxx.

◆ GetStats()

const RHistStats & ROOT::Experimental::RProfile::GetStats ( ) const

inline

Definition at line 211 of file RProfile.hxx.

◆ GetTotalNBins()

std::uint64_t ROOT::Experimental::RProfile::GetTotalNBins ( ) const

inline

Definition at line 215 of file RProfile.hxx.

◆ operator=() [1/2]

RProfile & ROOT::Experimental::RProfile::operator= ( const RProfile & )

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]

RProfile & ROOT::Experimental::RProfile::operator= ( RProfile && )

default

Efficiently move a profile histogram.

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

◆ Scale()

void ROOT::Experimental::RProfile::Scale ( double factor )

inline

Scale all bin contents and statistics.

Parameters

[in] factor the scale factor

Definition at line 522 of file RProfile.hxx.

◆ SetBinContent() [1/2]

template<typename... A>

void ROOT::Experimental::RProfile::SetBinContent ( const A &... args )

inline

Set the content of a single bin.

ROOT::Experimental::RProfile profile({/* two dimensions */});
ROOT::Experimental::RProfile::RProfileBin value = /* ... */;
profile.SetBinContent(3, 5, value);

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.

Warning: Setting the bin content will taint the global histogram statistics. Attempting to access its values, for example calling GetNEntries(), will throw exceptions.

Parameters

[in] args the arguments for each axis and the new value of the bin content

See also: the function overload accepting std::array

Definition at line 358 of file RProfile.hxx.

◆ SetBinContent() [2/2]

template<std::size_t N, typename V >

void ROOT::Experimental::RProfile::SetBinContent	(	const std::array< RBinIndex, N > &	indices,
		const V &	value )

inline

Set the content of a single bin.

ROOT::Experimental::RProfile profile({/* two dimensions */});
std::array<ROOT::Experimental::RBinIndex, 2> indices = {3, 5};
ROOT::Experimental::RProfile::RProfileBin value = /* ... */;
profile.SetBinContent(indices, value);

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.

Warning: Setting the bin content will taint the global histogram statistics. Attempting to access its values, for example calling GetNEntries(), will throw exceptions.

Parameters

[in]	indices	the array of indices for each axis
[in]	value	the new value of the bin content

See also: the variadic function template overload accepting arguments directly

Definition at line 331 of file RProfile.hxx.

◆ Streamer()

void ROOT::Experimental::RProfile::Streamer ( TBuffer & )

inline

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

Definition at line 531 of file RProfile.hxx.

Member Data Documentation

◆ fEngine

RHistEngine<RProfileBin> ROOT::Experimental::RProfile::fEngine

private

The histogram engine including the bin contents.

Definition at line 130 of file RProfile.hxx.

◆ fStats

RHistStats ROOT::Experimental::RProfile::fStats

private

The global histogram statistics.

Definition at line 132 of file RProfile.hxx.

Libraries for ROOT::Experimental::RProfile:

[legend]

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

hist/histv7/inc/ROOT/RProfile.hxx

Classes

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ RProfile() [1/7]

◆ RProfile() [2/7]

◆ RProfile() [3/7]

◆ RProfile() [4/7]

◆ RProfile() [5/7]

◆ RProfile() [6/7]

◆ RProfile() [7/7]

◆ ~RProfile()

Member Function Documentation

◆ Add()

◆ AddAtomic()

◆ Clear()

◆ Clone()

◆ ComputeMean()

◆ ComputeNEffectiveEntries()

◆ ComputeStdDev()

◆ Fill() [1/3]

◆ Fill() [2/3]

◆ Fill() [3/3]

◆ GetAxes()

◆ GetBinContent() [1/3]

◆ GetBinContent() [2/3]

◆ GetBinContent() [3/3]

◆ GetEngine()

◆ GetFullMultiDimRange()

◆ GetNDimensions()

◆ GetNEntries()

◆ GetStats()

◆ GetTotalNBins()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Scale()

◆ SetBinContent() [1/2]

◆ SetBinContent() [2/2]

◆ Streamer()

Member Data Documentation

◆ fEngine

◆ fStats