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 38 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	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.

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

std::size_t	GetNDimensions () const

std::uint64_t	GetNEntries () const

double	GetSumW () const

double	GetSumW2 () const

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

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)

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.

#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 94 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 115 of file RHistStats.hxx.

◆ Clear()

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

inline

Clear this statistics object.

Definition at line 129 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 269 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 162 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 146 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 232 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 215 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 188 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 378 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 322 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 347 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 289 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 298 of file RHistStats.hxx.

◆ GetDimensionStats()

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

inline

Definition at line 108 of file RHistStats.hxx.

◆ GetNDimensions()

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

inline

Definition at line 102 of file RHistStats.hxx.

◆ GetNEntries()

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

inline

Definition at line 104 of file RHistStats.hxx.

◆ GetSumW()

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

inline

Definition at line 105 of file RHistStats.hxx.

◆ GetSumW2()

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

inline

Definition at line 106 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 397 of file RHistStats.hxx.

Member Data Documentation

◆ fDimensionStats

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

private

The sums per dimension.

Definition at line 88 of file RHistStats.hxx.

◆ fNEntries

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

private

The number of entries.

Definition at line 82 of file RHistStats.hxx.

◆ fSumW

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

private

The sum of weights.

Definition at line 84 of file RHistStats.hxx.

◆ fSumW2

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

private

The sum of weights squared.

Definition at line 86 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()

◆ Clear()

◆ ComputeKurtosis()

◆ ComputeMean()

◆ ComputeNEffectiveEntries()

◆ ComputeSkewness()

◆ ComputeStdDev()

◆ ComputeVariance()

◆ Fill() [1/3]

◆ Fill() [2/3]

◆ Fill() [3/3]

◆ FillImpl() [1/2]

◆ FillImpl() [2/2]

◆ GetDimensionStats()

◆ GetNDimensions()

◆ GetNEntries()

◆ GetSumW()

◆ GetSumW2()

◆ Streamer()

Member Data Documentation

◆ fDimensionStats

◆ fNEntries

◆ fSumW

◆ fSumW2