Histogram statistics of unbinned values.

Every call to Fill updates sums to compute the number of effective entries as well as the arithmetic mean and other statistical quantities per dimension:

ROOT::Experimental::RHistStats stats(1);
stats.Fill(8.5);
stats.Fill(1.5);
// stats.ComputeMean() will return 5.0

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

Definition at line 41 of file RHistStats.hxx.

Classes
struct	RDimensionStats
	Statistics for one dimension. More...

Public Member Functions
	RHistStats (std::size_t nDimensions)
	Construct a statistics object.

void	Add (const RHistStats &other)
	Add all entries from another statistics object.

void	AddAtomic (const RHistStats &other)
	Add all entries from another statistics object using atomic instructions.

void	Clear ()
	Clear this statistics object.

double	ComputeKurtosis (std::size_t dim=0) const
	Compute the (excess) kurtosis of unbinned values.

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	ComputeSkewness (std::size_t dim=0) const
	Compute the skewness of unbinned values.

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

double	ComputeVariance (std::size_t dim=0) const
	Compute the variance of unbinned values.

void	DisableDimension (std::size_t dim)
	Disable one dimension of this statistics object.

template<typename... A>
void	Fill (const A &...args)
	Fill an entry into this statistics object.

template<typename... A>
void	Fill (const std::tuple< A... > &args)
	Fill an entry into this statistics object.

template<typename... A>
void	Fill (const std::tuple< A... > &args, RWeight weight)
	Fill an entry into this statistics object with a weight.

const RDimensionStats &	GetDimensionStats (std::size_t dim=0) const
	Get the statistics object for one dimension.

std::size_t	GetNDimensions () const

std::uint64_t	GetNEntries () const

double	GetSumW () const

double	GetSumW2 () const

bool	IsEnabled (std::size_t dim) const

bool	IsTainted () const

void	Scale (double factor)
	Scale the histogram statistics.

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

void	Taint ()
	Taint this statistics object.

Private Member Functions
template<std::size_t I, typename... A>
void	FillImpl (const std::tuple< A... > &args)

template<std::size_t I, std::size_t N, typename... A>
void	FillImpl (const std::tuple< A... > &args, double w)

void	ThrowIfTainted () const

Private Attributes
std::vector< RDimensionStats >	fDimensionStats
	The sums per dimension.

std::uint64_t	fNEntries = 0
	The number of entries.

double	fSumW = 0.0
	The sum of weights.

double	fSumW2 = 0.0
	The sum of weights squared.

bool	fTainted = false
	Whether this object is tainted, in which case read access will throw.

#include <ROOT/RHistStats.hxx>

Constructor & Destructor Documentation

◆ RHistStats()

ROOT::Experimental::RHistStats::RHistStats ( std::size_t nDimensions )

inlineexplicit

Construct a statistics object.

Parameters

[in] nDimensions the number of dimensions, must be > 0

Definition at line 132 of file RHistStats.hxx.

Member Function Documentation

◆ Add()

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

inline

Add all entries from another statistics object.

Throws an exception if the number of dimensions are not identical.

Parameters

[in] other another statistics object

Definition at line 196 of file RHistStats.hxx.

◆ AddAtomic()

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

inline

Add all entries from another statistics object using atomic instructions.

Throws an exception if the number of dimensions are not identical.

Parameters

[in] other another statistics object that must not be modified during the operation

Definition at line 222 of file RHistStats.hxx.

◆ Clear()

void ROOT::Experimental::RHistStats::Clear ( )

inline

Clear this statistics object.

Definition at line 244 of file RHistStats.hxx.

◆ ComputeKurtosis()

double ROOT::Experimental::RHistStats::ComputeKurtosis ( std::size_t dim = 0 ) const

inline

Compute the (excess) kurtosis of unbinned values.

The kurtosis is based on the fourth standardized moment:

\[ E\left[\left(\frac{X - \mu}{\sigma}\right)^4\right] \]

The excess kurtosis subtracts 3 from the standardized moment to have a value of 0 for a normal distribution:

\[ E\left[\left(\frac{X - \mu}{\sigma}\right)^4\right] - 3 \]

With support for weighted filling and after some rewriting, the (excess kurtosis) is computed as:

\[ \frac{\frac{\sum w_i \cdot x_i^4}{\sum w_i} - 4 \cdot \frac{\sum w_i \cdot x_i^3}{\sum w_i} \cdot \mu + 6 \cdot \frac{\sum w_i \cdot x_i^2}{\sum w_i} \cdot \mu^2 - 3 \cdot \mu^4}{\sigma^4} - 3 \]

Parameters

[in] dim the dimension index, starting at 0

Returns: the (excess) kurtosis of unbinned values

Definition at line 386 of file RHistStats.hxx.

◆ ComputeMean()

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

◆ ComputeNEffectiveEntries()

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

◆ ComputeSkewness()

double ROOT::Experimental::RHistStats::ComputeSkewness ( std::size_t dim = 0 ) const

inline

Compute the skewness of unbinned values.

The skewness is the third standardized moment:

\[ E\left[\left(\frac{X - \mu}{\sigma}\right)^3\right] \]

With support for weighted filling and after some rewriting, it is computed as:

\[ \frac{\frac{\sum w_i \cdot x_i^3}{\sum w_i} - 3 \cdot \frac{\sum w_i \cdot x_i^2}{\sum w_i} \cdot \mu + 2 \cdot \mu^3}{\sigma^3} \]

Parameters

[in] dim the dimension index, starting at 0

Returns: the skewness of unbinned values

Definition at line 349 of file RHistStats.hxx.

◆ ComputeStdDev()

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

◆ ComputeVariance()

double ROOT::Experimental::RHistStats::ComputeVariance ( std::size_t dim = 0 ) const

inline

Compute the variance of unbinned values.

This function computes the uncorrected sample variance:

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

With some rewriting, this is equivalent to:

\[ \sigma^2 = \frac{\sum w_i \cdot x_i^2}{\sum w_i} - \mu^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 variance.

Parameters

[in] dim the dimension index, starting at 0

Returns: the variance of unbinned values

Definition at line 305 of file RHistStats.hxx.

◆ DisableDimension()

void ROOT::Experimental::RHistStats::DisableDimension ( std::size_t dim )

inline

Disable one dimension of this statistics object.

All future calls to Fill will ignore the corresponding argument. Once disabled, a dimension cannot be reenabled.

Parameters

[in] dim the dimension index, starting at 0

Definition at line 180 of file RHistStats.hxx.

◆ Fill() [1/3]

template<typename... A>

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

inline

Fill an entry into this statistics object.

ROOT::Experimental::RHistStats stats(2);

stats.Fill(8.5, 10.5);

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

ROOT::Experimental::RHistStats stats(2);

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

ROOT::Experimental::RWeight

A weight for filling histograms.

Definition RWeight.hxx:17

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

Parameters

[in] args the arguments for each dimension

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

Definition at line 511 of file RHistStats.hxx.

◆ Fill() [2/3]

template<typename... A>

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

inline

Fill an entry into this statistics object.

ROOT::Experimental::RHistStats stats(2);
auto args = std::make_tuple(8.5, 10.5);
stats.Fill(args);

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

Parameters

[in] args the arguments for each dimension

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

Definition at line 455 of file RHistStats.hxx.

◆ Fill() [3/3]

template<typename... A>

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

inline

Fill an entry into this statistics object with a weight.

ROOT::Experimental::RHistStats stats(2);
auto args = std::make_tuple(8.5, 10.5);
stats.Fill(args, ROOT::Experimental::RWeight(0.8));

Parameters

[in]	args	the arguments for each dimension
[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 480 of file RHistStats.hxx.

◆ FillImpl() [1/2]

template<std::size_t I, typename... A>

void ROOT::Experimental::RHistStats::FillImpl ( const std::tuple< A... > & args )

inlineprivate

Definition at line 406 of file RHistStats.hxx.

◆ FillImpl() [2/2]

template<std::size_t I, std::size_t N, typename... A>

void ROOT::Experimental::RHistStats::FillImpl	(	const std::tuple< A... > &	args,
		double	w )

inlineprivate

Definition at line 422 of file RHistStats.hxx.

◆ GetDimensionStats()

const RDimensionStats & ROOT::Experimental::RHistStats::GetDimensionStats ( std::size_t dim = 0 ) const

inline

Get the statistics object for one dimension.

Throws an exception if the dimension is disabled.

Parameters

[in] dim the dimension index, starting at 0

Returns: the statistics object

Definition at line 164 of file RHistStats.hxx.

◆ GetNDimensions()

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

inline

Definition at line 140 of file RHistStats.hxx.

◆ GetNEntries()

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

inline

Definition at line 142 of file RHistStats.hxx.

◆ GetSumW()

double ROOT::Experimental::RHistStats::GetSumW ( ) const

inline

Definition at line 147 of file RHistStats.hxx.

◆ GetSumW2()

double ROOT::Experimental::RHistStats::GetSumW2 ( ) const

inline

Definition at line 152 of file RHistStats.hxx.

◆ IsEnabled()

bool ROOT::Experimental::RHistStats::IsEnabled ( std::size_t dim ) const

inline

Definition at line 182 of file RHistStats.hxx.

◆ IsTainted()

bool ROOT::Experimental::RHistStats::IsTainted ( ) const

inline

Definition at line 189 of file RHistStats.hxx.

◆ Scale()

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

inline

Scale the histogram statistics.

Parameters

[in] factor the scale factor

Definition at line 535 of file RHistStats.hxx.

◆ Streamer()

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

inline

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

Definition at line 549 of file RHistStats.hxx.

◆ Taint()

void ROOT::Experimental::RHistStats::Taint ( )

inline

Taint this statistics object.

It can still be filled, but any read access will throw until Clear() is called.

Definition at line 187 of file RHistStats.hxx.

◆ ThrowIfTainted()

void ROOT::Experimental::RHistStats::ThrowIfTainted ( ) const

inlineprivate

Definition at line 121 of file RHistStats.hxx.

Member Data Documentation

◆ fDimensionStats

std::vector<RDimensionStats> ROOT::Experimental::RHistStats::fDimensionStats

private

The sums per dimension.

Definition at line 116 of file RHistStats.hxx.

◆ fNEntries

std::uint64_t ROOT::Experimental::RHistStats::fNEntries = 0

private

The number of entries.

Definition at line 110 of file RHistStats.hxx.

◆ fSumW

double ROOT::Experimental::RHistStats::fSumW = 0.0

private

The sum of weights.

Definition at line 112 of file RHistStats.hxx.

◆ fSumW2

double ROOT::Experimental::RHistStats::fSumW2 = 0.0

private

The sum of weights squared.

Definition at line 114 of file RHistStats.hxx.

◆ fTainted

bool ROOT::Experimental::RHistStats::fTainted = false

private

Whether this object is tainted, in which case read access will throw.

This is used if a user modifies bin contents explicitly or slices histograms without preserving all entries, for example.

Definition at line 119 of file RHistStats.hxx.

Libraries for ROOT::Experimental::RHistStats:

[legend]

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

hist/histv7/inc/ROOT/RHistStats.hxx

Classes

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ RHistStats()

Member Function Documentation

◆ Add()

◆ AddAtomic()

◆ Clear()

◆ ComputeKurtosis()

◆ ComputeMean()

◆ ComputeNEffectiveEntries()

◆ ComputeSkewness()

◆ ComputeStdDev()

◆ ComputeVariance()

◆ DisableDimension()

◆ Fill() [1/3]

◆ Fill() [2/3]

◆ Fill() [3/3]

◆ FillImpl() [1/2]

◆ FillImpl() [2/2]

◆ GetDimensionStats()

◆ GetNDimensions()

◆ GetNEntries()

◆ GetSumW()

◆ GetSumW2()

◆ IsEnabled()

◆ IsTainted()

◆ Scale()

◆ Streamer()

◆ Taint()

◆ ThrowIfTainted()

Member Data Documentation

◆ fDimensionStats

◆ fNEntries

◆ fSumW

◆ fSumW2

◆ fTainted